api-design-principles

本技能为设计专业级 API 提供了完整的框架，重点在于业界标准范式，如 RESTful 资源导向架构与 GraphQL Schema-first 开发。适用于后端工程师、系统架构师与技术主管，他们需要建立 API 设计标准、进行设计评审或重构现有接口以提升可用性与维护性。无论是构建新服务或在不同范式间迁移，本技能都能确保您的 API 保持直观、高效且对开发者友好。

• 资源导向架构：应用名词作为资源，并正确使用 HTTP 动词语义（GET, POST, PUT, PATCH, DELETE）来维持一致的 API 行为。

• GraphQL 精通：实现 Schema-first 设计、高效的查询结构、变更（Mutations）与订阅（Subscriptions），以实现精确的客户端数据获取。

• 版本控制策略：实现健全的 URL、Header 或 Query 参数版本控制，以确保向后兼容性与平滑的转换。

• 进阶模式：应用 HATEOAS、分页、筛选，以及使用 HTTP 状态码进行标准化的错误处理，以改善客户端整合与调试流程。

• 文档标准：创建自解释性 API，强调清晰度、强类型与直观的层级，为第三方开发者提供绝佳体验。

• 在项目的架构设计阶段、编写端点逻辑或定义数据模型前使用此技能。

• 非常适合审查现有规范，以识别诸如以动作为导向的命名或不一致的错误响应等常见陷阱。

• 支持基于 Pydantic 的验证与 FastAPI 风格的实现模式，将设计原则转化为高质量代码。

• 输入通常包括技术需求、领域模型或有问题的现有端点；输出则是精炼后的 API 规范、设计模式或给开发者的结构化反馈。

• 约束：专注于后端 API 设计；请确保在维持此处提供的通用设计原则同时，遵守您特定框架（如 FastAPI, Apollo）的要求。