一份API设计完整路线图，覆盖从基础到落地的全部要点

这份API设计路线图一共分为10个模块，从基础概念到实际落地，覆盖了API设计的方方面面。

第一模块是基础，内容包括：明确API是产品加契约，而非一堆端点；优先考虑使用者需求，面向开发者、移动端、其他服务、智能体；区分公开、合作伙伴、内部、前端后端分离（BFF）四类API；以HTTP为基础，涵盖HTTP方法、安全性幂等性定义、状态码正确使用、常用请求头、内容协商；默认使用JSON作为载荷格式，明确Protobuf/MessagePack的适用场景；关注延迟、载荷大小、接口通信方式；梳理需求，包含用例、服务水平协议（SLA）、兼容性承诺。

第二模块是选择设计风格，不要盲目默认选择：REST适合公开API、CRUD操作、可缓存资源；RPC/gRPC适合内部高查询率（QPS）场景，支持类型定义和流式传输；GraphQL适合多客户端场景，解决过度获取问题；Webhooks/回调用于事件通知，替代轮询；WebSockets/SSE适用于实时状态、信息流场景；AsyncAPI/事件适用于发后不管场景，支持最终一致性；常见混合模式是：公开REST + 前端GraphQL + 内部gRPC；决策维度包括数据所有权、可缓存性、演进成本、可观测性。

第三模块是REST核心的资源与URL设计：使用名词而非动词，比如用/orders不用/getOrders；集合用复数，资源用单数；公共API的ID优先使用UUID/ULID，而非自增ID；嵌套层级不超过1-2层，多余改用查询或链接；参考Google AIP风格命名资源；区分标准方法与自定义方法；区分集合、单资源、操作、任务；支持过滤、排序、字段选择；搜索与列表分开，不要给GET请求过度附加搜索功能；不要泄漏数据库结构，围绕使用者领域建模。

第四模块是契约设计：保持请求和响应格式一致；分页支持偏移量分页、游标分页，分页令牌保持不透明；定义过滤与排序契约；区分部分更新的PUT与PATCH用法；批量接口设计部分成功逻辑；长任务使用202状态码加状态查询资源；文件上传下载支持分块、签名链接、断点续传；POST请求增加幂等键，用于可重试操作；条件请求使用ETag等字段；统一错误格式，遵循RFC 9457规范，包含机器码、人工描述、请求ID，校验错误以列表形式返回；选择信封或裸资源格式后保持一致。

第五模块是版本管理与演进：兼容性本身就是产品；优先做增量变更，新增字段设为可选，不重复使用名称；明确区分破坏性与非破坏性变更；版本策略包括路径版本（最常用，利于缓存）、日期版本（参考Stripe模式）、请求头/媒体类型版本，GraphQL采用字段废弃而非全图版本；流程为废弃→添加Sunset头→终止服务，周期6到24个月；流量迁移阶段同时运行两个版本逐步迁移；更新日志是API的一部分，不能给客户端带来意外变更。

第六模块是优先规范与开发者体验：REST以OpenAPI 3.1作为统一标准，GraphQL用SDL、gRPC用protobuf，事件用AsyncAPI；规范存储在git中，像代码一样审核；可自动生成类型、桩、模拟、开发工具包（SDK）和文档；文档要简洁易读：5分钟内完成快速入门，先讲认证再讲正常调用流程，提供错误、幂等、分页示例，提供在线调试 playground；官方开发工具包优于社区方案，要贴合语言习惯，不做简单HTTP封装；后端未完成时可先提供模拟服务；做契约测试；AI时代新增要求：机器可读规范、llms.txt、稳定工具Schema。

第七模块是认证、授权与多租户：区分认证与授权；API密钥用于服务间调用，要轮换、加范围，永远不要放在URL中；区分会话、JWT与不透明令牌；用户应用使用OAuth 2.1/OIDC的授权码加PKCE流程；机器调用使用客户端凭证；内部高信任场景使用mTLS；明确范围、受众，使用短期访问令牌加刷新令牌；区分RBAC、ABAC与ReBAC三种权限模型；每个请求都做对象级权限检查，避免越权访问；做属性级检查，避免批量赋值漏洞；多租户隔离将租户信息放在令牌中，不只用URL标识；所有密钥、令牌、服务账号都遵循最小权限原则。

第八模块是设计阶段融入安全考量：覆盖2023版OWASP API安全Top 10核心风险，包含越权访问、认证失效、资源滥用、服务器端请求伪造、错误配置、影子API等；在边界做输入校验，不能信任客户端；输出过滤，避免过度暴露；配置速率限制、流量控制，区分突发与持续流量；CORS明确配置允许域名；日志中不记录敏感个人信息、密钥、完整卡号；Webhook增加签名、时间戳、重放窗口；提前设计针对重试、爬虫、智能体请求泛滥等滥用场景的应对方案。

第九模块是流量、可靠性与运行时设计：明确API网关、BFF、服务网格各自职责；配置超时、重试、退避、抖动；幂等性与去重存储；速率限制返回429状态码加Retry-After头；缓存使用Cache-Control、ETag、Vary，说明GraphQL/POST难以缓存的原因，公开GET请求使用CDN；分页配合写入场景下的一致性快照；边缘节点做背压与舱壁隔离；每个请求与错误都携带追踪ID；API服务水平指标包含可用性、p95/p99延迟、错误率、新鲜度；设计优雅降级，支持部分响应、功能开关、只读模式。

第十模块是经典API设计实践，需要掌握：带游标分页和RFC 9457错误规范的CRUD资源API；Stripe模式支付API，包含幂等键、Webhook、日期版本；GitHub风格列表过滤API，包含ETag、速率限制头、超媒体链接；带OAuth和JWT的认证API；带签名上传链接、断点续传、访问控制的文件存储API；优先Webhook加重试加死信队列的通知API；REST历史加WebSocket/SSE实时能力的聊天在线状态API；带查询语言、区分相关性与精确过滤的搜索API；带密钥、范围、速率分级的多租户SaaS API；带OpenAPI、SDK、废弃策略的公开平台API。

最终目标是设计出易于调用、安全重试、低成本演进的API。