القائمة
API 和接口设计——稳定合约、清晰边界。当需要设计 REST/HTTP API、endpoint、接口契约、请求响应 DTO、错误语义、分页、幂等、权限边界或 API 合约测试时使用
يُحدَّد Prompt الذي يراجع المصدر أولًا بشكل افتراضي. يمكنك التبديل إلى أمر مباشر أو تنزيل نسخة محلية.
اقرأ SKILL.md وأي ملفات مرافقة يعرضها SkillsMP قبل أن تقرر التثبيت.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
يتجاوز الأمر المباشر Prompt المخصّص للمراجعة. افحص المصدر قبل تشغيله.
npx skills add https://github.com/ZeroZ-lab/unified-skills --skill build-backend-api-designيبقى الأمر في سطر واحد. مرّر أفقيًا لمراجعته كاملًا قبل النسخ.
تفضّل نسخة محلية؟ نزّل الملفات المتاحة حاليًا لدى SkillsMP.
استنادا إلى تصنيف SOC المهني
عرض SKILL.md
| 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 全部定义完成
- 未进入业务实现