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 セキュリティ設計

4 層のセキュリティモデル：

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 を参照してください。

よくある落とし穴

DTO で列挙型を公開する→string code | Command／Query DTO を混用する→分離する | null 安全性→Optional を処理する | VO で DB フィールドをそのまま公開する→ビューをカスタマイズする | 冪等性の欠如→Idempotency-Key | エラーでスタックトレースをそのまま返す→requestId | 深いネスト→2 層以下 | ドメインオブジェクトのシリアライズ→DTO／VO を介する

ルール

• Command／Query DTO の分離 — 書き込み操作と読み取り操作には個別の DTO を使用し、同じ構造の再利用は禁止です
• Controller でのプロトコル変換 — Controller 層では HTTP プロトコルの適合のみを行い、ビジネスロジックやドメイン呼び出しは含めません
• エラーコードのプレフィックスを統一 — ビジネスエラーは 5 桁のコードです。先頭 1 桁はカテゴリ（4＝クライアント／5＝サーバー）、次の 2 桁は HTTP、末尾 3 桁は具体的なエラーを表します
• BFF の責務範囲 — BFF はデータ集約と形式の適合のみを行い、データベースへの直接アクセスやビジネスルールの実装は行いません
• レスポンスのラッパー — すべての API レスポンスを Result<T> でラップします。例外は 204 No Content とファイルダウンロードのみです

FAQ

質問	回答
DO と DTO のフィールドが同じなら再利用できますか？	できません。DO は振る舞いを含みますが、DTO は純粋なデータであり、進化の方向が異なります。
すべての API でレスポンス形式を統一する必要がありますか？	はい。例外はファイルダウンロードと 204 のみです。
エラーコードはどのように設計しますか？	5 桁の数字です。先頭 1 桁はカテゴリ、次の 2 桁は HTTP、末尾 3 桁は具体的なエラーを表します。
BFF が必要なのはどのような場合ですか？	複数のフロントエンドプラットフォームがある場合、またはフロントエンドで複数のサービスのデータを組み合わせる必要がある場合です。
子リソースのネストは最大何層ですか？	最大 2 層です。2 層を超える場合は、集約の境界に問題があることを示しています。
Controller にビジネスロジックを記述できますか？	できません。プロトコル変換のみを行います。

キーワード

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/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 与数据库结构解耦。