| REST 六约束 | 客户端-服务端、无状态、可缓存、统一接口、分层系统、按需代码（可选） |
| 资源与 URI | 名词复数表资源（/orders/{id}），动作用 HTTP 方法表达，URI 里不出现动词 |
| HTTP 方法语义 | GET/HEAD 安全且幂等，PUT/DELETE 幂等，POST 非幂等，PATCH 局部更新 |
| 幂等 Idempotency | 同一请求执行多次与一次效果相同；支付、下单必须做幂等键 |
| 状态码要点 | 201 创建成功、204 无内容、409 冲突、422 语义校验失败、429 限流 |
| 统一错误结构 | code + message + details + traceId，让客户端能稳定判断与排障 |
| 版本策略 | URI 版本（/v1）最直观、Header 版本更纯粹、媒体类型版本最规范；选一种并写进规范 |
| 废弃流程 | 先标记 Deprecated、给 Sunset 头、双跑一段时间，再下线 |
| 分页 | offset 分页简单但深分页慢且会漏数据，大数据量用游标（cursor）分页 |
| 过滤 / 排序 / 字段裁剪 | 统一 ?filter=&sort=&fields= 约定，避免为每种组合开新接口 |
| 乐观锁与 ETag | If-Match + 版本号防并发覆盖，冲突返回 412 |
| 限流响应头 | X-RateLimit-Limit/Remaining/Reset、Retry-After，让客户端可自适应退避 |
| HATEOAS | 响应中给出后续可用链接；理论优雅，实践成本高，多数团队不用 |
| REST vs gRPC | REST 通用易调试，gRPC 用 HTTP/2 + Protobuf，强类型、高性能、适合内部服务 |
| gRPC 四种流 | 一元、服务端流、客户端流、双向流；还有 deadline、metadata、拦截器 |
| GraphQL | 客户端按需取字段、单请求多资源；难点是 N+1（用 DataLoader 批处理）、复杂度限流与缓存 |
| API 设计评审要点 | 命名一致、错误可判、幂等明确、向后兼容、可观测（traceId）、有文档与示例 |