ddd-api-designer

DDD API Designer

从领域模型到 REST API 的完整设计指南：CQRS 读写分离、四层数据对象转换链（PO→DO→DTO→VO）、统一响应格式、BFF 多端适配、版本管理与安全设计。

Workflow

1. 识别 Command vs Query — 将领域行为分为命令（写）和查询（读），决定 Method 和端点
2. 设计数据对象转换链 — 建立 PO→DO→DTO→VO 四层转换，各层独立职责
3. 设计 REST 端点 — Command 动词后缀, Query 资源命名
4. 定义统一响应格式 — Result<T> 包装 + 业务错误码体系
5. 应用 BFF — 每前端一个 BFF, 数据聚合 + 格式适配 + 协议转换
6. 选择版本策略 — 推荐 URL Path: /api/v1/orders, CDN 友好
7. 施加安全控制 — AuthN + AuthZ + 三层校验 + 差异化限流

When to Use

✅ ALWAYS use when	❌ Skip when
API 设计、REST API、接口设计	内部工具无外部消费者
DTO/VO 设计、数据对象转换	GraphQL/gRPC 项目
BFF / Backend for Frontend	无领域模型时 → domain-designer
OpenAPI / Swagger / API 文档	简单 CRUD 无 DDD
API 版本管理 / 安全设计	纯 gRPC 微服务（用 protobuf IDL）
需要将 DDD 聚合暴露为 REST API	快速原型不关心 API 规范

Boundary

✅ 明确适用

• 需要将 DDD 领域模型暴露为 REST API — CQRS 读写分离、数据对象转换链完整落地
• CQRS 命令/查询分离设计 — 独立 Command DTO 和 Query DTO，各自演化
• 多端（Web/iOS/MiniApp）API 统一设计 — BFF 模式按平台适配
• 统一响应格式与错误码体系设计 — Result<T> + 业务错误码标准化
• OpenAPI/Swagger 规范输出 — 代码生成策略保持接口与实现同步

⚠ 需谨慎评估

• 团队对 DDD/CQRS 不熟悉 → 先学习基础概念
• 单体应用无扩展需求 → 评估 ROI，可能过度设计
• 现有 API 无消费者兼容需求 → 版本管理可简化

❌ 不适用

• GraphQL/gRPC 项目 → 使用对应 IDL 和工具链
• 简单 CRUD 无 DDD → 先用通用 REST 框架或 domain-designer
• 快速原型/演示阶段 → 先用简化 API，后续再引入规范
• 纯 gRPC 微服务 → 使用 protobuf IDL + gRPC 拦截器
• 内部工具无外部消费者 → 简化 API 设计

CQRS API Design

Command（写）动词驱动，Query（读）资源驱动：

维度	Command	Query
HTTP Method	POST/PUT/DELETE	GET
URL 动词	需要（confirm, cancel）	不需要
请求体	Command 对象	仅查询参数
DTO 分离	独立 Command DTO	独立 Query DTO
幂等性	必须实现	天然幂等
缓存	从不缓存	ETag, max-age
响应	创建的资源摘要	数据 DTO / 列表

原则：Command DTO 和 Query DTO 始终分开定义。子资源嵌套最多 2 层。详见 references/patterns/cqrs-api-design.md

数据对象转换链（PO → DO → DTO → VO）

对象	层	职责	可见性
PO	Infrastructure	ORM 映射，数据库结构对应	内部
DO	Domain	充血模型，含业务行为	内部
DTO	Interface/App	跨层跨服务数据传输	半内部
VO	Interface	页面专用展示数据	外部

读方向：PO→DO→DTO→VO；写方向：VO→DTO→Command→DO→PO。 一个 DO 可按场景转换为多个 DTO（详情 DTO、摘要 DTO 等），Controller 不直接返回领域对象。详见 references/examples-ref/data-object-transformation.md

API 设计规范

规则	示例
名词复数	/orders ✓
Kebab-case	/order-history ✓
最大 2 层嵌套	/orders/{id}/items
写动词后缀	/orders/{id}/confirm
查询参数	?status=PAID&page=1
无 URL 动词	❌ GET /getOrders → GET /orders

HTTP Status：201 Created（创建）、200 OK（查询/更新）、204 No Content（删除）、400（校验/业务）、404（未找到）、409（并发冲突）、429（限流）、500（内部错误）。详见 references/security/api-naming-conventions.md

统一响应格式

成功：{ "code": 0, "message": "success", "data": T } — 201/200/204 错误：{ "code": 40001, "message": "...", "detail": "...", "requestId": "req-xxx" } — 400/404/409/429/500

Response wrapper Result<T> 包含 code + message + data + requestId。错误响应绝不返回堆栈信息。详见 references/examples-ref/unified-response-format.md

BFF（Backend for Frontend）

每前端一个 BFF（Web/iOS/MiniApp），职责：

• 数据聚合：组合多服务数据为页面 VO（1 次前端调用替代 N 次）
• 格式适配：Web 全量字段 / 移动端精简字段
• 协议转换：内部 gRPC → 外部 REST/JSON
• 响应塑形：移除内部字段，添加 UI 元数据

与 API Gateway 区别：BFF 做视图聚合（页面级），Gateway 做路由+限流（服务级）。 BFF 不直接访问数据库，不包含业务逻辑。详见 references/patterns/BFF-design-pattern.md

API 版本管理

策略	示例	推荐度
URL Path ★	/api/v1/orders → /api/v2/orders	★★★★★
Request Header	Accept: vnd.company.v2+json	★★★☆☆
Query Param	/api/orders?version=2	★★☆☆☆

推荐 URL Path：直观、CDN 友好、Swagger 兼容。迁移流程：v1 → v1+v2 → v2 only → v1 sunset（410 Gone）。详见 references/migration/api-versioning-strategies.md

API 安全设计

四层安全模型：

1. 认证：JWT Bearer Token / OAuth2 / API Key（服务间）
2. 授权：按限界上下文 + 资源所有权 + 角色
3. 输入校验：Controller 格式 → Application 业务 → Domain 不变式
4. 限流：Command 50/s, Query 200/s, Auth 10/s。详见 references/security/api-security-design.md

Gotchas — 常见陷阱

DTO 暴露枚举→string code | Command/Query DTO 混用→分开 | null 安全→处理 Optional | VO 透传 DB 字段→视图定制 | 幂等缺失→Idempotency-Key | 错误透传堆栈→requestId | 深层嵌套→≤2 层 | 领域对象序列化→经 DTO/VO

Rules

• Command/Query DTO 分离 — 写操作和读操作使用独立 DTO，禁止复用同一结构
• Controller 协议转换 — Controller 层仅做 HTTP 协议适配，不包含业务逻辑或领域调用
• 统一错误码前缀 — 业务错误 5 位码：首位类别（4=客户端/5=服务端）+ 后两位 HTTP + 末三位具体错误
• BFF 职责边界 — BFF 只做数据聚合与格式适配，不直接访问数据库或不包含业务规则
• 响应封装 — 所有 API 响应使用 Result<T> 包装，仅 204 No Content 和文件下载可例外

FAQ

Question	Answer
DO 和 DTO 字段一样能复用吗？	不能。DO 含行为，DTO 纯数据，演化方向不同。
所有 API 都要统一响应格式？	是，仅文件下载、204 可例外。
错误码怎么设计？	5 位数字：首位类别+后两位 HTTP+末三位具体错误。
何时需要 BFF？	多前端平台或前端需组合多服务数据。
子资源最多嵌套几层？	最多 2 层，超 2 层说明聚合边界有问题。
Controller 中能放业务逻辑吗？	不能，只做协议转换。

Keywords

CQRS API REST endpoint design PO DO DTO VO data object transformation unified response format BFF Backend for Frontend OpenAPI Swagger API versioning API security command query separation Result<T> response wrapper input validation rate limiting idempotency pagination design

References

• references/patterns/cqrs-api-design.md — CQRS API 设计
• references/examples-ref/data-object-transformation.md — PO↔DO↔DTO↔VO 转换
• references/patterns/BFF-design-pattern.md — BFF 设计模式
• references/security/api-security-design.md — API 安全
• references/migration/api-versioning-strategies.md — 版本管理
• references/security/api-naming-conventions.md — 命名规范
• references/examples-ref/unified-response-format.md — 统一响应
• references/security/openapi-specification.md — OpenAPI 3.0 规范
• references/patterns/data-access-api.md — 数据访问层 API 设计
• references/patterns/idempotency-design.md — 幂等设计
• references/patterns/pagination-filtering-design.md — 分页过滤
• references/architecture/partme-16-service-data-view.md — 协作关系
• references/architecture/clean-ddd-hexagonal-hexagonal.md — 六边形架构
• references/examples-ref/api-error-handling.md — 错误处理
• references/security/api-rate-limiting.md — 限流设计
• references/examples-ref/event-driven-api.md — 事件驱动 API

Examples

• examples/order-api-design.md — 订单服务案例
• examples/user-api-design.md — 用户服务案例：注册/登录/资料 + 安全设计
• examples/BFF-aggregation-example.md — BFF 聚合案例：订单详情页多服务数据聚合
• examples/api-version-migration.md — API 版本迁移案例：v1 → v2 全流程
• examples/payment-api-design.md — 支付服务 API 案例：退款幂等、状态机、异步通知
• examples/openapi-codegen-example.md — OpenAPI 代码生成案例：Spec-first 策略
• examples/product-api-design.md — 商品服务 API 案例
• examples/inventory-api-design.md — 库存服务 API 案例
• examples/notification-api-design.md — 通知服务 API 案例
• examples/search-api-design.md — 搜索服务 API 案例

---

🧭 DDD Skills Journey

📍 当前：ddd-api-designer — Step 4: API 设计与数据转换

Step 1 (awesome) → Step 2 (selector) → Step 3 (架构落地) → Step 4 (领域+CQRS+API) → Step 5 (审查) → Step 6 (辅助) → Step 7 (文档)
                                                                    ↑
                                         ⭐ ddd-api-designer: 领域模型 → REST API

← 上一站: hand off to ddd-domain-designer skill — 先有领域模型再设计 API(Install: npx skills add full-stack-skills/ddd-skills --skill ddd-domain-designer). → 下一站: hand off to ddd-code-reviewer skill — 审查 API 设计合规性(Install: npx skills add full-stack-skills/ddd-skills --skill ddd-code-reviewer). 🔗 相关: hand off to ddd-cqrs-architecture skill — CQRS 深入(Install: npx skills add full-stack-skills/ddd-skills --skill ddd-cqrs-architecture) | ddd-architecture-doc skill — OpenAPI 文档输出(Install: npx skills add full-stack-skills/ddd-skills --skill ddd-architecture-doc).

核心原则：Command 和 Query 分开设计。牢记 PO→DO→DTO→VO 四层转换链，DTO 与领域对象解耦，VO 与数据库结构解耦。