不同的业务场景适合不同的 API 技术栈。REST 易理解、生态成熟；GraphQL 灵活查询、减少往返；gRPC 高性能、强契约，适用于微服务通信。本文将全面介绍现代API设计的最佳实践。
API范式选型：REST vs GraphQL vs gRPC
| 特性 | REST | GraphQL | gRPC |
|---|---|---|---|
| 传输协议 | HTTP/1.1+JSON | HTTP/HTTPS+JSON | HTTP/2+Protobuf |
| 灵活性 | 一般 | 高（客户端自定义查询） | 低（服务端定义契约） |
| 性能 | 中等 | 中等（取决于查询复杂度） | 高（二进制、多路复用） |
| 生态/工具 | 最成熟 | 活跃 | 增长快 |
| 适用场景 | 公开API、简单CRUD | 多端聚合API、复杂数据需求 | 内部微服务、低延迟 |
统一资源设计与URL规范
- 使用名词复数表示资源集合：
/users、/orders - 层级关系用路径嵌套：
/users/{id}/orders - 过滤、排序、分页通过查询参数：
?status=active&sort=created_at&page=2&size=20 - 避免动词路径：
/getUser❌ →/users/{id}✅
GET /products?category=books&sort=-price&page=1&size=10版本管理策略
常见做法：
- URI版本控制：
/api/v1/users（直观，易缓存） - 请求头版本控制：
Accept: application/vnd.myapi.v1+json（URL干净） - 避免在同版本中破坏性变更，采用向后兼容字段新增方式
认证与授权
推荐使用 OAuth 2.0 + JWT 进行无状态认证，细粒度 RBAC 或 ABAC 授权。
💡 JWT优势
JWT 可在负载中包含用户角色与权限，减少后端查库次数。
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...错误处理与状态码
使用标准 HTTP 状态码：
- 200 OK、201 Created
- 400 Bad Request、401 Unauthorized、403 Forbidden
- 404 Not Found、409 Conflict
- 500 Internal Server Error
错误响应体应含 code、message、details：
{
"code": "invalid_parameter",
"message": "page size exceeds limit",
"details": { "field": "size", "max": 100 }
}速率限制与缓存
在网关或中间件层实现速率限制（令牌桶/漏桶算法），防止滥用。
利用 HTTP 缓存头（ETag、Cache-Control）与 CDN，减少后端压力。
安全性最佳实践
- 强制 HTTPS
- 防 SQL/NoSQL 注入、XSS、CSRF
- 请求签名防篡改
- 敏感数据脱敏
⚠️ 安全提醒
API安全需贯穿整个开发生命周期，从设计到部署都需要持续关注。
性能与可观测性
启用 Gzip/Brotli 压缩、分页、字段筛选。监控指标包括：响应时间、错误率、饱和度。
结构化日志记录请求 ID、用户信息、错误栈，便于追踪。
