api-design

api-design 技能为构建强大、可扩展且标准化的后端服务提供了结构化的框架。它专为后端工程师和系统架构师而设计，确保 API 的一致性、可维护性以及客户端与服务器组件之间的清晰沟通。无论您是在构建新的微服务、实施 GraphQL schema，还是重构现有的 REST 端点，此技能都能通过行业标准的设计模式，协助您减少技术债并提升开发速度。

• 资源导向架构：强制使用复数名词和逻辑资源嵌套结构，严格避免在 URL 中使用动词，以保持 RESTful 路径的可预测性。

• HTTP 方法对齐：验证正确使用 GET、POST、PUT、PATCH 和 DELETE 动词，并强调幂等性以确保系统作业安全。

• 标准化响应模式：实施一致的数据包装、分页元数据字段，以及使用适当 HTTP 状态码的统一错误报告结构。

• 高级查询能力：利用标准化查询参数，简化强大的筛选、排序、字段选取和搜索机制的设计。

• API 生命周期管理：支持有效的版本控制策略（包括基于 URL 和 Header 的版本控制），并提供 OpenAPI 3.0/Swagger 文档模板。

• GraphQL 最佳实践：提供 schema 设计模式、输入验证、自定义错误处理以及类型安全的 mutation 结构。

• 常见输入包括新资源的技术需求、数据库 schema 定义或需要现代化的旧版 API 端点。

• 常见输出包括干净的路由定义、OpenAPI YAML 文档、JSON 响应契约，以及分页或验证处理程序的实施蓝图。

• 用户应遵守既定的命名规范（小写/连字符），以确保团队间 API 的一致性。

• 实施复杂筛选时，请善用所提供的范围筛选模式（如 created_gte、price_min），以保持系统的可预测性。

• 确保所有错误响应都能提供可执行的详细信息，例如错误代码和字段级别消息，并避免泄露敏感的内部堆栈追踪或数据库细节。