hexagonal-architecture

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Hexagonal Architecture (Ports & Adapters)

六边形架构（端口与适配器）

This skill applies only to projects that have opted in to hexagonal architecture. Do not apply these patterns to projects that use a different architecture. For introducing hex arch into an existing codebase incrementally, see

resources/incremental-adoption.md

For domain modeling (entities, value objects, aggregates, ubiquitous language), load the

domain-driven-design

skill. Hex arch and DDD are complementary but independent — hex arch provides structural isolation (how the outside connects), DDD provides the domain model (what lives in the center). A project may use one without the other.

Deep-dive resources are in the

resources/

directory. Load them on demand:

Resource	Load when...
`worked-example.md`	Need a full feature traced through every layer with tests and file map
`testing-hex-arch.md`	Writing tests, creating fakes, setting up `createTestDb` , swappability test
`cqrs-lite.md`	Reads need to JOIN across aggregates, separating read/write paths
`cross-cutting-concerns.md`	Placing auth, logging, transactions, or error formatting
`incremental-adoption.md`	Introducing hex arch into an existing codebase

For authoritative sources, see

../REFERENCES.md

本技能仅适用于已选择采用六边形架构的项目。请勿将这些模式应用于使用其他架构的项目。如需在现有代码库中逐步引入六边形架构，请查看

resources/incremental-adoption.md

。

如需进行领域建模（实体、值对象、聚合根、通用语言），请加载

domain-driven-design

技能。六边形架构与DDD相辅相成但彼此独立——六边形架构提供结构隔离（外部如何与内部连接），DDD提供领域模型（核心层包含的内容）。项目可以单独使用其中一种。

深度学习资源位于

resources/

目录下，可按需加载：

资源	加载时机...
`worked-example.md`	需要完整功能的全链路追踪，包含测试和文件映射
`testing-hex-arch.md`	编写测试、创建模拟实现、设置 `createTestDb` 、可替换性测试
`cqrs-lite.md`	查询需要跨聚合根进行JOIN操作，需分离读写路径
`cross-cutting-concerns.md`	处理认证、日志、事务或错误格式化
`incremental-adoption.md`	在现有代码库中引入六边形架构

权威参考资料请查看

../REFERENCES.md

。

Core Concept

核心概念

Business logic lives in the center. External systems connect through ports (interfaces) and adapters (implementations). Dependencies point inward — the domain never knows about the outside world.

         Driving (left)                    Driven (right)
    ┌──────────────────┐            ┌──────────────────┐
    │  Route handlers  │            │  Repositories    │
    │  CLI commands    │──────┐┌────│  API clients     │
    │  Event listeners │      ││    │  Email services  │
    └──────────────────┘      ││    └──────────────────┘
         call into ──────►  ┌────┐  ◄────── implement
                            │    │
                            │ DO │
                            │ MA │
                            │ IN │
                            │    │
         call into ──────►  └────┘  ◄────── implement
    ┌──────────────────┐      ││    ┌──────────────────┐
    │  Cron triggers   │──────┘└────│  File storage    │
    │  Message queues  │            │  Payment gateway │
    └──────────────────┘            └──────────────────┘

Driving adapters (left): initiate actions on the application. They call use cases. Driven adapters (right): the application reaches out to them. They implement port interfaces.

This asymmetry is fundamental. Driving adapters depend on use case interfaces. Driven adapters implement repository/gateway interfaces defined by the domain.

业务逻辑位于核心层。外部系统通过端口（接口）和适配器（实现）与核心层连接。依赖方向向内——领域层永远不知道外部世界的存在。

         Driving (left)                    Driven (right)
    ┌──────────────────┐            ┌──────────────────┐
    │  Route handlers  │            │  Repositories    │
    │  CLI commands    │──────┐┌────│  API clients     │
    │  Event listeners │      ││    │  Email services  │
    └──────────────────┘      ││    └──────────────────┘
         call into ──────►  ┌────┐  ◄────── implement
                            │    │
                            │ DO │
                            │ MA │
                            │ IN │
                            │    │
         call into ──────►  └────┘  ◄────── implement
    ┌──────────────────┐      ││    ┌──────────────────┐
    │  Cron triggers   │──────┘└────│  File storage    │
    │  Message queues  │            │  Payment gateway │
    └──────────────────┘            └──────────────────┘

驱动适配器（左侧）：向应用发起动作，调用用例。 从动适配器（右侧）：应用主动调用它们，实现端口接口。

这种不对称性是核心原则。驱动适配器依赖于用例接口，从动适配器实现领域层定义的仓储/网关接口。

Ports = Interfaces

端口 = 接口

Ports define contracts between layers. They are always

interface

types (behavior contracts, not data shapes).

typescript

// Driven port — defined in domain, implemented by adapters
interface UserRepository {
  readonly findById: (id: UserId) => Promise<User | undefined>;
  readonly save: (user: User) => Promise<void>;
}

// Driven port — defined in domain, implemented by adapters
interface PaymentGateway {
  readonly charge: (amount: Money, paymentInfo: PaymentInfo) => Promise<ChargeResult>;
}

// Driven port — event publishing (outbound to message brokers)
interface OrderEventPublisher {
  readonly publish: (event: OrderEvent) => Promise<void>;
}

Port design principles:

Name ports by business purpose, not technology (
```
UserRepository
```
, not
```
DatabasePort
```
)
Keep ports focused — one per aggregate or capability, not one god port
Port methods use domain types, never infrastructure types (no
```
SqlRow
```
, no
```
HttpResponse
```
)
Creation param schemas co-locate with the repository port they describe

端口定义了层与层之间的契约。它们始终是

interface

类型（行为契约，而非数据结构）。

typescript

// Driven port — defined in domain, implemented by adapters
interface UserRepository {
  readonly findById: (id: UserId) => Promise<User | undefined>;
  readonly save: (user: User) => Promise<void>;
}

// Driven port — defined in domain, implemented by adapters
interface PaymentGateway {
  readonly charge: (amount: Money, paymentInfo: PaymentInfo) => Promise<ChargeResult>;
}

// Driven port — event publishing (outbound to message brokers)
interface OrderEventPublisher {
  readonly publish: (event: OrderEvent) => Promise<void>;
}

端口设计原则：

按业务用途命名端口，而非技术名称（如
```
UserRepository
```
，而非
```
DatabasePort
```
）
保持端口聚焦——每个聚合根或能力对应一个端口，而非单一全能端口
端口方法使用领域类型，绝不使用基础设施类型（无
```
SqlRow
```
，无
```
HttpResponse
```
）
创建参数模式与对应的仓储端口放在一起

Adapters = Implementations

适配器 = 实现

Adapters implement ports for specific technologies. A good adapter is simple — it translates between the port's domain types and the technology's native types. No business logic.

typescript

// Driven adapter — implements the repository port using Drizzle/D1
const createDrizzleUserRepository = (db: D1Database): UserRepository => ({
  findById: async (id) => {
    const row = await db.select().from(users).where(eq(users.id, id)).get();
    return row ? toUser(row) : undefined;
  },
  save: async (user) => {
    await db.insert(users).values(toRow(user)).onConflictDoUpdate({ ... });
  },
});

// Driven adapter — implements the same port for tests
const createFakeUserRepository = (initial: readonly User[] = []): UserRepository => {
  const store = new Map(initial.map(u => [u.id, u]));
  return {
    findById: async (id) => store.get(id),
    save: async (user) => { store.set(user.id, user); },
  };
};

Adapter error handling: Infrastructure errors (connection lost, timeout, constraint violation) should either propagate as exceptions to a top-level handler or be translated into domain-appropriate results at the adapter boundary. The domain never catches infrastructure errors — it doesn't know infrastructure exists.

typescript

// Driven adapter: translate expected infrastructure errors into domain-specific errors
const createDrizzleUserRepository = (db: Database): UserRepository => ({
  save: async (user) => {
    try {
      await db.insert(users).values(toRow(user)).onConflictDoUpdate({ ... });
    } catch (e) {
      if (isUniqueConstraintError(e)) throw new UserAlreadyExistsError(user.id);
      throw e; // unexpected errors (connection lost, disk full) propagate
    }
  },
});

Expected constraint violations become domain-specific errors (caught by the use case or driving adapter). Unexpected infrastructure errors propagate to the top-level handler.

Key principle: If swapping an adapter requires changing domain code, the boundary is wrong.

适配器针对特定技术实现端口。优秀的适配器应简洁——仅在端口的领域类型与技术原生类型之间进行转换，不包含业务逻辑。

typescript

// Driven adapter — implements the repository port using Drizzle/D1
const createDrizzleUserRepository = (db: D1Database): UserRepository => ({
  findById: async (id) => {
    const row = await db.select().from(users).where(eq(users.id, id)).get();
    return row ? toUser(row) : undefined;
  },
  save: async (user) => {
    await db.insert(users).values(toRow(user)).onConflictDoUpdate({ ... });
  },
});

// Driven adapter — implements the same port for tests
const createFakeUserRepository = (initial: readonly User[] = []): UserRepository => {
  const store = new Map(initial.map(u => [u.id, u]));
  return {
    findById: async (id) => store.get(id),
    save: async (user) => { store.set(user.id, user); },
  };
};

适配器错误处理：基础设施错误（连接丢失、超时、约束冲突）应要么作为异常传播到顶层处理器，要么在适配器边界转换为适合领域的结果。领域层永远不会捕获基础设施错误——它不知道基础设施的存在。

typescript

// Driven adapter: translate expected infrastructure errors into domain-specific errors
const createDrizzleUserRepository = (db: Database): UserRepository => ({
  save: async (user) => {
    try {
      await db.insert(users).values(toRow(user)).onConflictDoUpdate({ ... });
    } catch (e) {
      if (isUniqueConstraintError(e)) throw new UserAlreadyExistsError(user.id);
      throw e; // unexpected errors (connection lost, disk full) propagate
    }
  },
});

预期的约束冲突会转换为领域特定错误（由用例或驱动适配器捕获）。意外的基础设施错误会传播到顶层处理器。

核心原则：如果更换适配器需要修改领域代码，说明边界设计错误。

Reads vs Writes (CQRS-lite)

读操作 vs 写操作（CQRS-lite）

Not all reads need to go through repositories. The repository pattern enforces aggregate boundaries — essential for writes, but reads often need to JOIN across aggregates for display.

Operation	Pattern	Example
Write	Repository (one aggregate)	`userRepo.save(user)`
Read (single aggregate)	Repository	`userRepo.findById(id)`
Read (cross-aggregate, display)	Query function (JOINs freely)	`getEventDetail(db, eventId)`

Query functions are driven adapters too — they live in the adapter layer (e.g.,

db/queries/

) and return read-optimized DTOs. They bypass the repository pattern intentionally.

typescript

// Query function — JOINs across aggregates for display
// Lives in db/queries/, NOT in domain/
const getParticipantEventView = async (db: Database, eventId: string) => {
  return db.select({ ... })
    .from(events)
    .innerJoin(occasions, ...)
    .leftJoin(giftClaims, ...)
    .where(eq(events.id, eventId))
    .all();
};

Domain-layer pure functions can transform query results into display types — these encode business rules about what data means (e.g., "is this item claimed by the current user?"). The query fetches; the domain function interprets.

For detailed CQRS-lite guidance, see

resources/cqrs-lite.md

并非所有读操作都需要通过仓储。仓储模式强制聚合根边界——这对写操作至关重要，但读操作通常需要跨聚合根进行JOIN以展示数据。

操作	模式	示例
写	仓储（单一聚合根）	`userRepo.save(user)`
读（单一聚合根）	仓储	`userRepo.findById(id)`
读（跨聚合根，用于展示）	查询函数（自由JOIN）	`getEventDetail(db, eventId)`

查询函数也是从动适配器——它们位于适配器层（如

db/queries/

），返回优化后的查询DTO。它们有意绕过仓储模式。

typescript

// Query function — JOINs across aggregates for display
// Lives in db/queries/, NOT in domain/
const getParticipantEventView = async (db: Database, eventId: string) => {
  return db.select({ ... })
    .from(events)
    .innerJoin(occasions, ...)
    .leftJoin(giftClaims, ...)
    .where(eq(events.id, eventId))
    .all();
};

领域层的纯函数可以将查询结果转换为展示类型——这些函数编码了关于数据含义的业务规则（例如“当前用户是否已认领该物品？”）。查询负责获取数据，领域函数负责解释数据。

如需详细的CQRS-lite指导，请查看

resources/cqrs-lite.md

。

Dependency Injection

Inject all dependencies via function parameters. No DI container needed. The driving adapter gathers impure dependencies, passes them to the use case, and acts on the result — Seemann's "impureim sandwich" (impure/pure/impure).

typescript

// WRONG — creates dependencies internally (untestable, tightly coupled)
const createOrder = async (order: NewOrder) => {
  const repo = new DrizzleOrderRepo(getDb());          // hardcoded
  const gateway = new StripeGateway(process.env.KEY);   // hardcoded
  // ...
};

// RIGHT — dependencies as parameters (testable, swappable)
const createOrder = async (
  repo: OrderRepository,
  gateway: PaymentGateway,
  order: NewOrder,
): Promise<OrderResult> => {
  const charge = await gateway.charge(order.total, order.payment);
  if (!charge.success) return { success: false, reason: charge.error };
  const saved = await repo.save({ ...order, chargeId: charge.id });
  return { success: true, order: saved };
};

Composition root: Wiring happens at the application entry point — where adapters are created from environment/config and injected into use cases. This is the only place that knows about concrete implementations.

typescript

// Route handler = composition root + driving adapter
export async function POST(request: Request) {
  const { env } = getCloudflareContext();
  const db = createDb(env.DB);

  // Wire adapters
  const repo = createDrizzleOrderRepository(db);
  const gateway = createStripeGateway(env.STRIPE_KEY);

  // Call use case
  const body = CreateOrderSchema.parse(await request.json());
  const result = await createOrder(repo, gateway, body);
  return NextResponse.json(result);
}

The route handler is thin glue: parse input → wire adapters → call use case → return response. No business logic.

Non-HTTP driving adapters follow the same pattern — parse, wire, delegate:

typescript

// Queue consumer = driving adapter (same structure as route handler)
const handlePledgeMessage = async (message: SQSMessage, env: Env) => {
  const db = createDb(env.DB);
  const occasionRepo = createDrizzleOccasionRepository(db);
  const contributorRepo = createDrizzleContributorRepository(db);

  const dto = PledgeSchema.parse(JSON.parse(message.body));
  await handlePledge(occasionRepo, contributorRepo, dto);
};

The use case doesn't know or care whether it was triggered by an HTTP request, a queue message, a cron job, or a CLI command. Every driving adapter is thin glue.

Naming: Use cases are named after the business operation —

createOrder

placeOrder

handlePledge

. Never

createOrderUseCase

PlaceOrderHandler

. Pattern suffixes are technical jargon, not domain language. You can tell a use case from a domain function by its signature — use cases take ports (repositories, gateways) as parameters; domain functions take only domain types.

通过函数参数注入所有依赖项，无需DI容器。驱动适配器收集不纯依赖项，将其传递给用例，并处理结果——这就是Seemann提出的“不纯-纯-不纯三明治”（impure/pure/impure）。

typescript

// WRONG — creates dependencies internally (untestable, tightly coupled)
const createOrder = async (order: NewOrder) => {
  const repo = new DrizzleOrderRepo(getDb());          // hardcoded
  const gateway = new StripeGateway(process.env.KEY);   // hardcoded
  // ...
};

// RIGHT — dependencies as parameters (testable, swappable)
const createOrder = async (
  repo: OrderRepository,
  gateway: PaymentGateway,
  order: NewOrder,
): Promise<OrderResult> => {
  const charge = await gateway.charge(order.total, order.payment);
  if (!charge.success) return { success: false, reason: charge.error };
  const saved = await repo.save({ ...order, chargeId: charge.id });
  return { success: true, order: saved };
};

组合根：依赖注入的组装发生在应用入口点——在这里根据环境/配置创建适配器，并注入到用例中。这是唯一知晓具体实现的地方。

typescript

// Route handler = composition root + driving adapter
export async function POST(request: Request) {
  const { env } = getCloudflareContext();
  const db = createDb(env.DB);

  // Wire adapters
  const repo = createDrizzleOrderRepository(db);
  const gateway = createStripeGateway(env.STRIPE_KEY);

  // Call use case
  const body = CreateOrderSchema.parse(await request.json());
  const result = await createOrder(repo, gateway, body);
  return NextResponse.json(result);
}

路由处理器是一层薄胶水：解析输入 → 组装适配器 → 调用用例 → 返回响应。不包含业务逻辑。

非HTTP驱动适配器遵循相同模式——解析、组装、委托：

typescript

// Queue consumer = driving adapter (same structure as route handler)
const handlePledgeMessage = async (message: SQSMessage, env: Env) => {
  const db = createDb(env.DB);
  const occasionRepo = createDrizzleOccasionRepository(db);
  const contributorRepo = createDrizzleContributorRepository(db);

  const dto = PledgeSchema.parse(JSON.parse(message.body));
  await handlePledge(occasionRepo, contributorRepo, dto);
};

用例不知道也不关心它是由HTTP请求、队列消息、定时任务还是CLI命令触发的。每个驱动适配器都是一层薄胶水。

命名规则：用例以业务操作命名——

createOrder

、

placeOrder

、

handlePledge

。绝不要命名为

createOrderUseCase

或

PlaceOrderHandler

。模式后缀是技术行话，而非领域语言。可以通过签名区分用例和领域函数——用例将端口（仓储、网关）作为参数；领域函数仅接受领域类型。

File Organization

文件组织

Layer	Location	Contains	Tests
Domain	`src/domain/`	Business logic (pure functions), types, port interfaces, use cases (orchestration)	Unit + use case tests (fakes)
Adapters (driven)	`src/db/` , `src/infrastructure/`	Repository impls, API clients, query functions	Integration tests (real DB/MSW)
Adapters (driving)	`src/app/`	Route handlers, event listeners	E2E tests (Playwright)
Wiring	`src/lib/` , `src/context.ts`	Adapter factories, config, composition	Covered by E2E

Key rules:

Domain has zero external dependencies (no framework, database, or HTTP imports)
Port interfaces live in domain alongside the entity they serve
Schemas co-locate with their entity in domain
Adapters import from domain, never the reverse
Route handlers are thin — parse, wire, delegate, respond

层	位置	包含内容	测试
领域层	`src/domain/`	业务逻辑（纯函数）、类型、端口接口、用例（编排）	单元测试 + 用例测试（模拟实现）
适配器（从动）	`src/db/` 、 `src/infrastructure/`	仓储实现、API客户端、查询函数	集成测试（真实数据库/MSW）
适配器（驱动）	`src/app/`	路由处理器、事件监听器	端到端测试（Playwright）
组装层	`src/lib/` 、 `src/context.ts`	适配器工厂、配置、组合逻辑	由端到端测试覆盖

核心规则：

领域层无任何外部依赖（无框架、数据库或HTTP导入）
端口接口与对应的实体一起放在领域层
模式与对应的实体一起放在领域层
适配器从领域层导入，绝无反向导入
路由处理器要简洁——解析、组装、委托、响应

Testing Strategy

测试策略

Hex arch's primary benefit is testability. The primary test boundary is the use case — call it with driven ports replaced by in-memory fakes (not mocks). This proves the feature works as a whole.

Priority	Boundary	What it proves
Primary	Use case (faked driven ports)	Feature works end-to-end within the hexagon
Complement	Domain pure functions	Complex business rules in isolation
Secondary	Driven adapters (real DB/MSW)	Adapter translates correctly
Verification	E2E (full stack)	User experience works

Fakes over mocks: Fakes implement the real interface and maintain state. Mocks verify call sequences and break on refactoring. See

resources/testing-hex-arch.md

for detailed patterns.

For a complete worked example showing one feature traced through every layer (glossary → types → domain → use case → adapters → tests → file locations), see

resources/worked-example.md

六边形架构的主要优势是可测试性。主要测试边界是用例——使用内存中的**模拟实现（fakes）**替换从动端口来调用它（而非mocks）。这可以验证功能整体是否正常工作。

优先级	边界	验证内容
首要	用例（替换为模拟从动端口）	六边形内部的功能端到端正常工作
补充	领域纯函数	复杂业务规则的隔离验证
次要	从动适配器（真实数据库/MSW）	适配器转换逻辑正确
验证	端到端（全栈）	用户体验正常

优先使用模拟实现（fakes）而非mocks：fakes实现真实接口并维护状态，mocks验证调用顺序且在重构时容易失效。如需详细模式，请查看

resources/testing-hex-arch.md

。

如需完整的示例，展示一个功能从术语表→类型→领域层→用例→适配器→测试→文件位置的全链路追踪，请查看

resources/worked-example.md

。

Cross-Cutting Concerns

横切关注点

Concern	Where	Why
Authentication (who are you?)	Driving adapter	Protocol-specific (JWT, session, API key)
Authorization (are you allowed?)	Domain	Business rule about permissions
Logging	Adapters (both sides)	Side effect, not business logic
Transactions	Adapter / composition root	Infrastructure concern, domain unaware
Error formatting	Driving adapter	Translates domain results to HTTP/gRPC

The domain never imports a logger, catches HTTP errors, or manages transactions. It returns results; adapters handle the rest. See

resources/cross-cutting-concerns.md

for detailed patterns.

关注点	位置	原因
认证（你是谁？）	驱动适配器	协议相关（JWT、会话、API密钥）
授权（你是否被允许？）	领域层	关于权限的业务规则
日志	适配器（两侧）	副作用，非业务逻辑
事务	适配器 / 组合根	基础设施关注点，领域层不知情
错误格式化	驱动适配器	将领域结果转换为HTTP/gRPC格式

领域层永远不会导入日志器、捕获HTTP错误或管理事务。它返回结果，适配器处理其余部分。如需详细模式，请查看

resources/cross-cutting-concerns.md

。

Anti-Patterns

反模式

Domain Depending on Infrastructure

领域层依赖基础设施

The most common hex arch violation. Domain code imports from frameworks, databases, or external services.

typescript

// ❌ Domain imports Drizzle
import { eq } from 'drizzle-orm';
export const findActiveUsers = async (db) => db.select()...

// ✅ Domain defines the contract; adapter implements it
interface UserRepository {
  readonly findActive: () => Promise<readonly User[]>;
}

最常见的六边形架构违反情况。领域代码导入框架、数据库或外部服务。

typescript

// ❌ Domain imports Drizzle
import { eq } from 'drizzle-orm';
export const findActiveUsers = async (db) => db.select()...

// ✅ Domain defines the contract; adapter implements it
interface UserRepository {
  readonly findActive: () => Promise<readonly User[]>;
}

Business Logic in Adapters

适配器中包含业务逻辑

Route handlers or repositories contain business rules instead of delegating to domain.

typescript

// ❌ Business rule in route handler
export async function POST(request: Request) {
  const order = await orderRepo.findById(id);
  if (order.total > 1000) { await requireManagerApproval(order); } // business rule!
  ...
}

// ✅ Business rule in domain
const placeOrder = (order: Order): PlaceOrderResult => {
  if (order.total > 1000) return { success: false, reason: 'requires-approval' };
  ...
};

路由处理器或仓储包含业务规则，而非委托给领域层。

typescript

// ❌ Business rule in route handler
export async function POST(request: Request) {
  const order = await orderRepo.findById(id);
  if (order.total > 1000) { await requireManagerApproval(order); } // business rule!
  ...
}

// ✅ Business rule in domain
const placeOrder = (order: Order): PlaceOrderResult => {
  if (order.total > 1000) return { success: false, reason: 'requires-approval' };
  ...
};

Bypass Adapters

绕过适配器

Route handler accesses the database directly instead of going through a port.

typescript

// ❌ Route handler hits DB directly
export async function GET(request: Request) {
  const users = await db.select().from(users).where(eq(users.active, true));
  ...
}

// ✅ Route handler calls use case, which uses a port
const result = await getActiveUsers(userRepo);

路由处理器直接访问数据库，而非通过端口。

typescript

// ❌ Route handler hits DB directly
export async function GET(request: Request) {
  const users = await db.select().from(users).where(eq(users.active, true));
  ...
}

// ✅ Route handler calls use case, which uses a port
const result = await getActiveUsers(userRepo);

Port Proliferation

端口泛滥

Creating a port for every tiny abstraction. Ports should represent meaningful boundaries — one per aggregate (repositories) or per external capability (payment, email, auth).

为每个微小的抽象创建端口。端口应代表有意义的边界——每个聚合根（仓储）或每个外部能力（支付、邮件、认证）对应一个端口。

Technology-Shaped Ports

技术导向的端口

Port methods that expose technology details. Port methods should use domain language.

typescript

// ❌ Technology leaks into port
interface UserRepository {
  readonly findBySqlQuery: (sql: string) => Promise<User[]>;
  readonly getFromRedisCache: (key: string) => Promise<User>;
}

// ✅ Business language
interface UserRepository {
  readonly findActive: () => Promise<readonly User[]>;
  readonly findById: (id: UserId) => Promise<User | undefined>;
}

端口方法暴露技术细节。端口方法应使用领域语言。

typescript

// ❌ Technology leaks into port
interface UserRepository {
  readonly findBySqlQuery: (sql: string) => Promise<User[]>;
  readonly getFromRedisCache: (key: string) => Promise<User>;
}

// ✅ Business language
interface UserRepository {
  readonly findActive: () => Promise<readonly User[]>;
  readonly findById: (id: UserId) => Promise<User | undefined>;
}

hexagonal-architecture

Original

Translation

Hexagonal Architecture (Ports & Adapters)

六边形架构（端口与适配器）

Core Concept

核心概念

Ports = Interfaces

端口 = 接口

Adapters = Implementations

适配器 = 实现

Reads vs Writes (CQRS-lite)

读操作 vs 写操作（CQRS-lite）

Dependency Injection

Dependency Injection

File Organization

文件组织

Testing Strategy

测试策略

Cross-Cutting Concerns

横切关注点

Anti-Patterns

反模式

Domain Depending on Infrastructure

领域层依赖基础设施

Business Logic in Adapters

适配器中包含业务逻辑

Bypass Adapters

绕过适配器

Port Proliferation

端口泛滥

Technology-Shaped Ports

技术导向的端口

Checklist

检查清单