程序员不得不知道的 API 接口常识

程序员需掌握的 API 接口核心常识包括设计规范、限流策略、版本管理、权限安全及团队互通原则，以下为具体知识体系梳理：

• RESTful 设计原则

  资源定位：通过 URL 明确资源，如 GET /users 表示查询用户列表。

  HTTP 方法语义化：

  GET：安全读取，无副作用（如查询订单）。

  POST：创建资源（如提交新用户）。

  PUT：完整替换资源（如更新用户全部信息）。

  PATCH：部分更新资源（如修改用户地址）。

  DELETE：删除资源（如删除订单）。

  状态码规范：

  200 OK：成功响应。

  400 Bad Request：客户端错误（如参数缺失）。

  401 Unauthorized：未授权访问。

  500 Internal Server Error：服务端错误。

• 文档自动化工具

  Swagger/OpenAPI：通过代码注释自动生成交互式文档，减少手动维护成本。

  Postman：支持 API 测试与文档共享，适合团队协作。

• 限流必要性

  防止突发流量击垮服务（如秒杀活动）。

  避免依赖的第三方服务因过载拒绝响应。

• 常见算法与实现

  令牌桶算法：

  以固定速率生成令牌，请求需获取令牌才能执行。

  适用场景：单体架构，如 TokenBucket(rate=10, capacity=100) 表示每秒生成 10 个令牌，桶容量为 100。

  漏桶算法：

  请求以固定速率处理，突发流量排队等待。

  适用场景：需要严格速率限制的场景（如 API 网关）。

  分布式限流：

  结合 Redis 实现集群环境限流，如使用 INCR 和 EXPIRE 命令统计单位时间请求数。

• 云服务支持

  主流云厂商（如阿里云、AWS）提供 API 网关，支持自动限流、熔断降级。

• 版本控制策略

  URL 路径版本化：

  GET /api/v1/users（旧版）。

  GET /api/v2/users（新版，支持更多字段）。

  请求头版本化：

  通过 Accept: application/vnd.company.v2+json 指定版本。

• 版本迭代原则

  向后兼容：新增字段或接口时，确保旧版客户端正常工作。

  废弃策略：

  标记旧版接口为 deprecated，并在文档中说明替代方案。

  设置下线时间（如 6 个月后移除 v1 接口）。

• 常见鉴权方式

  IP 白名单：

  适用场景：内部服务调用（如微服务间通信）。

  Token 鉴权：

  JWT（JSON Web Token）：无状态鉴权，适合 ToB 业务（如开放平台 API）。

  OAuth 2.0：授权框架，支持第三方应用访问用户资源（如微信登录）。

  Session/Cookie：

  适用场景：ToC 业务（如用户登录后操作购物车）。

• 安全最佳实践

  数据脱敏：

  避免直接暴露用户 ID，使用 GET /users/me/orders 替代。

  HTTPS 加密：

  所有 API 强制使用 HTTPS，防止中间人攻击。

  输入校验：

  验证参数类型、长度、范围（如年龄必须为正整数）。

• 协作原则

  可读性：遵循 RESTful 规范，减少沟通成本。

  稳定性：通过限流、熔断保护双方服务。

  合规性：明确调用权限（如需申请 API Key）。

• 治理工具

  API 市场：

  内部平台统一管理 API 文档、调用权限（如康威定律下的组织适配）。

  服务网格（Service Mesh）：

  通过 Sidecar 代理实现流量监控、限流、加密（如 Istio）。

• 一致性：统一团队规范，降低理解成本。
• 可维护性：通过版本管理、文档自动化减少技术债务。
• 安全性：从鉴权到数据脱敏，构建多层防御。
• 可观测性：通过日志、监控追踪 API 调用情况（如 Prometheus + Grafana）。

延伸建议：

• 学习 HATEOAS（超媒体作为应用状态引擎） 进一步优化 RESTful 设计。
• 探索 GraphQL 替代 REST 的场景（如多资源灵活查询）。
• 关注 gRPC 在内部微服务通信中的高性能表现。