返回目录 / 开发工具
API 设计：让资源与读写语义清楚可演进
审查 REST/GraphQL 资源模型、HTTP 方法、schema 与消费者兼容性。
Skills
先列出 API 消费者、资源名词、层级关系与核心查询/变更，再决定 REST 或 GraphQL 结构。REST 使用名词资源和正确 HTTP 语义：GET 安全且幂等，POST 创建，PUT 完整替换，PATCH 局部更新，DELETE 删除；GraphQL 用 schema 类型区分 query 与 mutation。统一分页、错误结构、认证和幂等键策略。检查新增字段/枚举对旧客户端的影响，写 OpenAPI/GraphQL 示例并列出兼容迁移步骤；不能把接口设计稿当成已上线契约。
权限边界
前置条件
- 设计或审查 REST/GraphQL API 规范、资源边界、错误模型与兼容策略。
- 需明确消费者、核心资源、读写操作与版本兼容要求。
权限边界
- 可编辑 API schema/spec 与文档；不得假定规范变更已经部署。
- 写接口实现或改变生产兼容行为需单独授权。
限制
GET 应保持安全/幂等语义，POST/PUT/PATCH/DELETE表达写操作；版本演进需保护现有消费者。
固定上游来源
- 仓库
- wshobson/agents
- 文件路径
- plugins/backend-development/skills/api-design-principles/SKILL.md
- 固定提交
46891e7e60da0e52baf1050b7b6391b64e84c6d9- 来源检查
- 2026-10-14 · 已按固定上游来源核对
仓库指标
以下数字属于上游仓库整体，不代表单个 Skill 或指南的点赞/热度。
- Stars
- 未取得
- Forks
- 未取得
- 观测时间
- 未取得
尚未取得指标快照。
许可证: MIT
适用工具
API specification editor · OpenAPI schema · GraphQL schema review