用途:在设计 API、选择 REST/GraphQL/gRPC 协议、进行资源建模、建立一致的 API 约定以及优化开发者体验时提供指导。
主要能力:对比三种协议的适用场景与优缺点——REST 适合 CRUD、公开 API 与广泛客户端兼容;GraphQL 适合复杂数据需求、移动端与多服务聚合,单一端点、强类型 schema;gRPC 适合内部微服务、高性能与多语言系统,基于 Protocol Buffers 与 HTTP/2,支持双向流。附协议选择决策树与多因素对比表,覆盖公开 API、移动端、微服务、实时、浏览器支持、缓存与学习曲线。
REST 设计实践:资源命名用名词、复数、kebab-case,关系用嵌套路径;HTTP 方法语义与幂等/安全性对照;状态码使用场景(200/201/204/400/401/403/404/409/422/429/500);分页(offset 与 cursor)、过滤排序、字段选择;统一错误响应结构(code/message/details/request_id)。
GraphQL 实践:清晰类型与连接式分页、mutation 输入类型;通过深度限制、复杂度评分、超时与限流防止昂贵查询;用 DataLoader 批处理与请求内缓存避免 N+1。
gRPC 实践:聚焦的 message、请求/响应包装类型、流式处理大数据集,以及标准状态码。
API 演进:兼容变更包括新增端点、可选字段、末尾新增枚举值与放宽校验;破坏性变更包括删除端点/字段、改类型、重命名、新增必填字段。弃用流程为标记弃用、记录迁移路径、设定下线日期、监控使用、到期移除。
限制:资料未提供具体安装命令、价格、平台支持范围或实际效果数据。