技能说明
适合新接口设计、规范审查和 REST/GraphQL 演进，覆盖资源命名、HTTP 方法、版本策略、分页、限流、错误格式、OpenAPI、DataLoader 和查询复杂度。技能提供设计与审查框架，不替代具体项目的认证、数据模型和部署决策。
关于此技能
帮助设计和审查直观、可扩展、易维护的 REST 与 GraphQL API，统一资源、版本、错误和性能实践。
核心能力
REST 与 GraphQL 设计
覆盖资源命名、HTTP 方法语义、schema-first、查询与变更等核心设计原则。
版本与数据访问
提供版本策略、分页、限流、缓存、DataLoader 和查询复杂度等可落地检查点。
文档与错误规范
强调正确状态码、结构化错误、OpenAPI 文档和避免接口结构紧绑数据库。
适用场景
新接口设计
从资源、操作、参数和返回结构开始，为新 REST 或 GraphQL API 建立统一约定。
接口规范审查
在实现前检查命名、版本、分页、认证边界、错误格式和潜在性能问题。
接口迁移与演进
规划 REST 与 GraphQL 之间的迁移，或为已有接口补齐兼容性和废弃策略。
使用步骤
- 01
第一步：确认业务资源
列出核心资源、关系、读写动作和客户端约束，避免直接照搬数据库表结构。
- 02
第二步：确定接口契约
选择 REST 或 GraphQL 形式，统一命名、状态码、错误格式、分页和版本策略。
- 03
第三步：做性能与文档检查
检查限流、N+1、查询复杂度、输入校验和 OpenAPI 文档，再进入实现。
常见问题
它只适用于 REST API 吗？+
不是。SKILL.md 同时覆盖 REST 和 GraphQL，适合接口设计、评审与迁移规划。
它会替我生成完整后端代码吗？+
不会。技能提供设计原则和审查清单，具体框架实现、数据模型和部署仍需结合项目实际决定。
GraphQL 一定能解决所有数据获取问题吗？+
不能。技能仍要求处理 DataLoader、输入校验、查询复杂度、分页和监控等问题，GraphQL 不会自动消除性能风险。
安装前检查
把兼容性、来源和安装入口先看清楚，再放进自己的工作流。
Claude Code · Codex · Cursor
已提供来源链接
命令可直接复制
2026/09/03
安装提醒：即使有清晰的来源和安装方式，也建议先阅读 SKILL.md，确认它会访问哪些文件和服务。
npx skills add wshobson/agents --skill api-design-principles -a claude-code -g