Menu
API 和接口设计——稳定合约、清晰边界。当需要设计 REST/HTTP API、endpoint、接口契约、请求响应 DTO、错误语义、分页、幂等、权限边界或 API 合约测试时使用
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Baseado na classificação ocupacional SOC
结构化脑暴——发散探索 + 收敛评估。当想法模糊、面临开放性问题或需要方案对比，或提到"脑暴""想法""方案对比""怎么办"
恢复保存的工作上下文。当新 session 需要继续之前的工作，或提到"恢复""restore""继续上次"
保存工作上下文。当需要保存当前工作状态供后续 session 恢复，或提到"保存""save""checkpoint""挂起"
架构决策记录（ADR）。当面临技术选型、架构决策、方案取舍需要记录，或提到"ADR""决策记录""为什么这样做"
发布或导出检查 → Go/No-Go → 归档。当审查通过后需要上线或交付最终产物，或提到"发布""上线""ship""Go/No-Go"
合并 PR → 等待 CI → 验证生产。当 PR 已创建需要合并到主分支并验证部署，或提到"合并""merge""PR""land"
| name | build-backend-api-design |
| description | API 和接口设计——稳定合约、清晰边界。当需要设计 REST/HTTP API、endpoint、接口契约、请求响应 DTO、错误语义、分页、幂等、权限边界或 API 合约测试时使用 |
这个 Skill 不是负责写 API 实现，而是负责在实现前冻结 API 合约：资源、端点、DTO、错误、权限、分页、幂等、并发、兼容性和合约测试。
build-workflow-execute）build-quality-tdd/SKILL.mdbuild-backend-database）所有可观察行为都可能成为事实合约。字段类型、null 语义、默认值、错误 code、HTTP status、排序、分页结构均视为合约。
执行规则： 设计时假定每个行为都是永久的。判断变更是否兼容，不看服务端能不能跑，只看旧客户端是否无需修改仍能正确工作。
先定义 Method + Path + Request + Response + Error + Auth + Pagination + Schema，再进入实现。
执行规则： API 设计顺序——资源 → endpoint → Request DTO → Response DTO → Error Codes → 权限 → 分页/排序/过滤 → 幂等/并发 → schema → contract tests → 再进入实现。
遵循 HTTP method 语义。默认使用资源名词建模，不把 CRUD 动词放在 URL 路径中。
执行规则：
POST /tasks/:id/complete）仅在动作有明确业务含义、触发复杂副作用、且错误语义和幂等性已定义时使用PATCH /tasks/:id { "status": "completed" }错误响应必须统一、稳定、机器可读。
执行规则：
{ error: { code, message, details, requestId } }code：大写 snake_case，稳定不变，如 TASK_TITLE_REQUIRED、IDEMPOTENCY_KEY_CONFLICTmessage：给人看的，可本地化，不作为程序判断依据requestId：用于排查和链路追踪DB Model 是内部实现，API Output 是外部合约。
执行规则：
API 边界验证格式；Service / Domain 保护业务规则和不变量。
执行规则：
优先兼容扩展，避免 breaking change。
执行规则： 遵循兼容性矩阵——新增可选字段通常安全；修改字段类型/语义、删除字段、新增必填字段、修改默认排序/默认值/错误格式通常 breaking。版本化是最后手段，不是默认方案。
有副作用且可能重试的 POST 必须评估幂等性。
执行规则： 推荐 Idempotency-Key header。相同 key + 相同 body → 返回第一次结果；相同 key + 不同 body → 409 Conflict IDEMPOTENCY_KEY_CONFLICT。
可能并发更新的 PATCH / PUT 必须评估 version / ETag / If-Match。
执行规则： version 放 body 或 If-Match header 取决于项目风格，但必须明确一种。版本冲突返回 409 TASK_VERSION_CONFLICT。
列表接口必须分页，必须定义默认排序。
执行规则：
createdAt desc 或 id desctotal / totalPages 为可选（计算 total 可能很贵）TypeScript interface 只提供编译期约束。API 边界必须使用运行时 schema（Zod / Valibot / TypeBox / JSON Schema / OpenAPI）。
执行规则： Request 使用 schema 验证；OpenAPI 从 schema 生成或保持同步。不要只写 interface 后直接信任 req.body。
每个端点必须明确：是否需要认证、角色/权限、资源级权限、租户隔离、无权限时 403 还是 404。
设计 API 时按顺序自检：Resource → Contract → Compatibility → Security → Reliability → Test。
| 说辞 | 现实 | 后果 |
|---|---|---|
| "现在就我们一个消费者" | Hyrum 法则。1 个消费者时最容易做对。 | 新消费者接入时需重构接口 |
| "错误格式不重要" | 不一致 = 每个消费者需要不同的解析器。 | n 个端点 × m 种格式 = n×m 个解析器 |
| "以后再补分页" | 不分页的列表端点会在某个星期五爆炸。 | 数据增长后服务崩溃、超时 |
| "v2 不兼容就废弃" | 扩展优于版本化，两个版本 = 双倍维护。 | 双倍测试 + 双倍 bug + 迁移成本 |
| "POST 重试就重试呗" | 客户端重试是网络环境的正常行为。 | 重复订单 / 重复扣款 |
| "并发更新很少见" | 双击、重试、移动端网络切换都会触发。 | 覆盖更新丢失 |
/createTask、/getTasks）| 验证项 | 失败表现 | 处理方式 |
|---|---|---|
| 合约未先于实现 | 先写代码再定义类型 | 停止实现，先定义 schema 和 DTO |
| 没有错误 code | 只返回 message | 增加稳定 error.code，message 只给人看 |
| 错误格式不一致 | 不同端点不同错误结构 | 统一为 { error: { code, message, details, requestId } } |
| 无分页 | 列表返回全部数据 | 添加分页参数和 PaginatedResponse wrapper |
| 无默认排序 | 分页结果顺序不稳定 | 增加固定排序字段 |
| 无幂等策略 | POST 重试重复创建 | 增加 Idempotency-Key |
| 无并发控制 | PATCH 相互覆盖 | 增加 version / If-Match |
| DB model 直出 | 返回内部字段 | 定义 Output DTO 和 mapper |
| 无权限说明 | 只写 authenticated | 明确 role、permission、ownership |
| 无 schema | 只有 interface | 增加 Zod / OpenAPI schema |
| 修改已有字段 | 改类型或语义 | 停止，改为新增字段或版本化策略 |
API 设计完成：
资源模型:
- Task: 用户任务资源
- Comment: 任务评论子资源
端点列表:
- GET /tasks → GetTasksQuery → PagePaginatedResponse<TaskOutput>
- POST /tasks → CreateTaskRequest → TaskOutput
- GET /tasks/:id → TaskOutput
- PATCH /tasks/:id → PatchTaskRequest → TaskOutput
- DELETE /tasks/:id → 204
- GET /tasks/:id/comments → CursorPaginatedResponse<CommentOutput>
权限规则:
- 所有端点需要 authenticated
- GET /tasks/:id 需要 task:read + tenant ownership
- PATCH /tasks/:id 需要 task:write + tenant ownership
- 无权限是否返回 403/404: 私有资源返回 404
错误格式:
{ error: { code, message, details, requestId } }
错误 code:
- TASK_TITLE_REQUIRED / TASK_NOT_FOUND / TASK_PERMISSION_DENIED
- TASK_VERSION_CONFLICT / IDEMPOTENCY_KEY_CONFLICT
命名规范:
- URL path: plural resource names
- JSON body: camelCase
- TypeScript: camelCase
- Error code: UPPER_SNAKE_CASE
分页: 管理列表 page/pageSize，Feed/大数据 cursor/limit，必须有默认排序
幂等性: 有副作用的 POST 支持 Idempotency-Key，冲突返回 409
并发控制: PATCH/PUT 使用 version 或 If-Match，冲突返回 409
输入/输出分离: Output DTO + mapper 白名单，不暴露 DB model
Schema: src/schemas/task.schema.ts + src/types/api.ts + openapi.yaml
合约测试: tests/api-contracts/tasks.contract.test.ts
Done When:
- endpoint、DTO、schema、错误 code、权限、分页、幂等、并发控制、contract tests 全部定义完成
- 未进入业务实现