api-design

用途：为构建直观、一致、可扩展的 API 提供设计原则，覆盖 REST、GraphQL、gRPC 以及 WebSocket、SSE 等实时协议。

主要能力：

1. REST 设计：资源用名词复数命名，避免动词路径；嵌套资源最多两级；规定 GET/POST/PUT/PATCH/DELETE 对应状态码；统一响应结构（data、meta、error）；支持偏移与游标分页、过滤与排序（如 sort=-createdAt,name、age[gte]=18）。
2. GraphQL：Schema 设计、Relay 风格 Connection 分页、DataLoader 防止 N+1、字段级授权、用 union 或 payload errors 处理可预期错误。
3. gRPC：Protocol Buffers 定义服务与消息，支持流式 RPC；并给出 REST/GraphQL/gRPC 选型对照（公开 API 与浏览器客户端适合 REST/GraphQL，微服务与实时场景适合 gRPC）。
4. 版本控制：URL、Header、查询参数三种策略；区分破坏性与非破坏性变更；弃用策略（Deprecation、Sunset、Link 响应头）。
5. 实时 API：WebSocket 订阅/取消订阅示例与 SSE 服务端、客户端写法。
6. 文档与安全：OpenAPI 3.0 示例；认证、限流、输入校验、CORS、HTTPS、请求 ID 等实践；限流响应头 X-RateLimit-*。
7. 常见陷阱：破坏性变更、过度取得、取得不足、错误格式不一致、缺乏限流。
8. 校验规则：禁止用 HTTP 200 返回错误、API 路径含动词、缺少输入验证、硬编码状态码、缺少版本前缀。

使用方式：作为技能参考，在编写接口路由、Schema、Proto 或文档时对照上述规范与校验模式，按需选用。

适用场景：公开 API、移动端接口、微服务、实时推送、需要版本演进与统一错误处理的系统。

限制：资料未提供安装命令、收费、价格、平台支持或效果数据；文中代码示例仅为示意，具体实现需结合自身技术栈。