一个设计良好的 API 是“隐形”的——它应当自然顺畅、毫不费力地工作。在这份简单背后，其实依赖一套一致的设计原则，使 API 具备可预测性、安全性和可扩展性。

以下是一些优秀的 API 的特点：

• 幂等性

  • GET、HEAD、PUT、DELETE 必须具备幂等性：相同请求发送两次，应返回相同结果，且没有任何意外副作用。
  • POST 和 PATCH 不具备幂等性：每次调用都会创建新资源或以不同方式修改状态。

  实现方法：使用存储在 Redis 或数据库中的 幂等键（Idempotency Key）。
  客户端在重试时发送相同的键，服务器识别后返回原始响应，而不是再次处理。

• 版本管理

• 基于名词的资源命名

  资源名必须用名词，而不是动词。
  例如：

  • 正确：/api/products
  • 错误：/api/getProducts

• 安全性

  为每一个端点做好认证保护。
  Bearer Token（如 JWT）包含：

  • Header（头部）
  • Payload（负载）
  • Signature（签名）
    用于校验请求合法性。

  务必使用 HTTPS，并在每次调用中验证 Token。

• 分页

  在返回大型数据集时使用分页参数，使响应高效、可控、稳定。
  例如：?limit=10&offset=20