接口又乱又难用？老司机带你掌握 8 个 API 设计绝招，告别低效协作！

嘿，大家好，我是老码小张。

不知道你有没有遇到过这样的情况？刚接手一个项目，或者要跟隔壁团队的伙伴联调接口，结果发现 API 设计得那叫一个"百花齐放"：有的接口名叫 /getUserInfo，有的叫 /queryUserList，还有的直接是 /user/find；参数呢，一会儿是 userId，一会儿是 user_id，一会儿又是 uid... 文档要么语焉不详，要么干脆就没更新。每次对接，都感觉像在玩"大家来找茬"，沟通成本蹭蹭往上涨，开发效率直线下降，心里那叫一个苦啊！

是不是感觉膝盖中了一箭？别慌，这其实是很多项目，尤其是快速迭代的项目中常见的问题。接口设计得好不好，直接关系到团队协作的效率，甚至影响到系统的稳定性和可维护性。一个清晰、规范、易于理解的 API，就像团队之间的一门"通用语言"，能让沟通顺畅，开发高效。

今天，我就结合自己踩过的一些坑，以及业界比较成熟的一些经验，给大家分享 8 个实用的 API 设计技巧。掌握了它们，不敢说让你立马成为 API 设计大师，但至少能让你设计的接口，看起来更专业，用起来更顺手，跟别人协作起来也更轻松！

一、数据格式？没啥说的，拥抱 JSON 吧！

现在都什么年代了，API 返回的数据格式，基本上没啥悬念，JSON (JavaScript Object Notation) 就是最优选。为啥？

1. 人类可读：结构清晰，一眼就能看明白数据是啥样的。
2. 机器友好：几乎所有编程语言都有现成的库来解析和生成 JSON，处理起来方便得很。
3. 轻量高效：相比 XML，体积更小，网络传输更快。

别用那些古老的 XML 或者自定义的奇奇怪怪格式了，除非有非常特殊的理由。坚持用 JSON，能省不少事儿。

// 推荐的 JSON 格式
{
  "id": 12345,
  "username": "laomaxiaozhang",
  "email": "[email protected]",
  "isActive": true
}

二、URL 命名：用名词，不用动词，还要用复数！

这是 RESTful API 设计风格的核心思想之一：把一切都看作是资源 (Resource)。URL（统一资源定位符）就是用来定位这些资源的。

所以，URL 里应该用名词来表示资源，而不是动词。

• 反例 ：/getUserById?id=123, /createUser, /deleteOrder
• 正例 ：/users/123, /users, /orders/456

而且，对于表示资源集合的 URL，推荐使用名词复数。

• 反例 ：/user, /product （获取列表时）
• 正例 ：/users, /products

这样设计，URL 结构清晰，表达的意思也更直观。你看 /users 就知道是跟用户集合打交道，/users/123 就是特指 ID 为 123 的那个用户。

三、资源嵌套：表达关联关系的好帮手

如果资源之间有明确的从属或关联关系，可以用 URL 嵌套来体现。

比如，一个用户有很多订单 (Orders)，一个订单有很多订单项 (OrderItems)。可以这样设计：

• 获取某个用户的所有订单： GET /users/{userId}/orders
• 获取某个用户的某个特定订单：GET /users/{userId}/orders/{orderId}

这样设计的好处是，URL 本身就能清晰地表达资源之间的层级和关联。但注意，嵌套层级不宜过深，一般建议最多两到三层，太深了 URL 会变得冗长复杂，反而不美观也不实用。

四、别忘了过滤、排序和分页三件套

当你提供一个获取资源列表的 API 时（比如 GET /users），返回成千上万条数据显然是不现实的，对吧？这时候，过滤 (Filtering)、排序 (Sorting) 和分页 (Pagination) 就派上用场了。

通常，我们把这些控制参数放在 URL 的查询参数 (Query Parameters) 里。

• 过滤 ：允许调用者根据特定条件筛选资源。
  • GET /users?status=active (只看活跃用户)
  • GET /orders?createDate=2023-10-26 (只看某天创建的订单)
• 排序 ：允许调用者指定按哪个字段排序，以及升序还是降序。
  • GET /products?sort=price_asc (按价格升序)
  • GET /users?sort=createdAt_desc (按创建时间降序)
• 分页 ：控制返回数据的数量和页码。
  • GET /articles?page=2&limit=20 (获取第 2 页，每页 20 条)

这三个功能对于列表查询类 API 来说，几乎是标配。设计好了，能极大提升 API 的灵活性和性能。

五、HTTP 方法：选对姿势很重要

RESTful API 很重要的一点就是利用 HTTP 协议本身的方法 (Methods) 来表达对资源的操作意图。别一股脑全用 GET 或 POST 了，那跟 RPC (远程过程调用) 没啥区别。

常用的 HTTP 方法及其约定用途如下表：

HTTP 方法	主要操作	示例 URL	描述	是否幂等 (Idempotent)
GET	读取资源	/users, /users/{id}	获取用户列表或单个用户的信息	是
POST	创建新资源	/users	创建一个新用户 (通常返回新资源信息或 ID)	否
PUT	完整替换资源	/users/{id}	用请求中的数据完全替换指定 ID 的用户信息	是
PATCH	部分更新资源	/users/{id}	只更新请求中提供的用户信息的字段	否 (理论上)
DELETE	删除资源	/users/{id}	删除指定 ID 的用户	是

稍微解释下"幂等" ：简单说，就是同一个请求，执行一次和执行多次，对资源产生的影响是相同的。GET、PUT、DELETE 都是幂等的。比如，你删一个用户 (DELETE /users/123)，删一次是删了，再删一次（假设允许对不存在资源执行删除）结果还是一样（用户没了）。但 POST 不是幂等的，你发两次 POST /users 请求，理论上会创建两个新用户。PATCH 是否幂等有争议，但通常认为它不是。

用对 HTTP 方法，能让你的 API 更符合 REST 规范，也更容易被理解和使用。

六、优雅地处理错误：状态码和错误信息要清晰

API 调用不可能永远成功。网络问题、参数错误、服务器内部异常... 总会有出错的时候。这时候，怎么告诉调用方"出错了，错在哪了"，就显得尤为重要。

别动不动就返回 200 OK，然后在响应体里塞个 {"success": false, "errorMsg": "..."}。这不规范！

正确姿势：

1. 使用标准的 HTTP 状态码 ：
   • 2xx (成功)：200 OK, 201 Created, 204 No Content (比如 DELETE 成功)
   • 4xx (客户端错误)：400 Bad Request (参数错), 401 Unauthorized (未认证), 403 Forbidden (无权限), 404 Not Found (资源不存在)
   • 5xx (服务器错误)：500 Internal Server Error (服务器内部崩了), 503 Service Unavailable (服务暂不可用)
2. 在响应体中提供详细的错误信息：只给个状态码有时候不够，最好在 JSON 响应体里，提供更具体的错误代码 (业务错误码)、错误消息 (给人看的描述)、可能还有详细的错误细节 (比如哪个字段错了)。

// 示例：一个 400 Bad Request 的响应体
{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "请求参数校验失败",
    "details": [
      {
        "field": "email",
        "issue": "邮箱格式不正确"
      }
    ]
  }
}

这样设计，调用方拿到响应，一看状态码就知道大概情况，再看响应体就能快速定位问题。

七、API 版本控制：给未来留条后路

你的业务在发展，系统在迭代，API 不可能一成不变。但你又不能随便改动线上正在使用的 API，否则依赖它的客户端或服务可能就挂了。怎么办？

API 版本控制就是答案。

常见的版本控制方式有：

1. URL 路径中加版本号 (推荐) ：比如 /v1/users, /v2/users。这是最常见、最直观的方式。
2. 查询参数中加版本号 ：比如 /users?version=1。
3. 请求头 (Header) 中加版本号 ：比如 Accept: application/vnd.myapi.v1+json。

我个人更推荐在 URL 路径中加版本号 (/v1/, /v2/...)，因为它最清晰明了，对客户端和开发者都友好。

有了版本控制，你就可以在不破坏旧版本兼容性的前提下，发布新的 API 版本，让调用方按需升级。

八、锦上添花：一些实战小建议

除了上面说的主要几点，还有些小细节能让你的 API 设计更上一层楼：

• 提供 API 文档：再好的设计，没有文档也是白搭。使用 Swagger (OpenAPI Specification) 这样的工具自动生成交互式文档，谁用谁知道，效率提升杠杠的！
• 考虑安全性：API 不能裸奔。HTTPS 是必须的。身份认证 (Authentication) 和授权 (Authorization) 也要考虑清楚，比如用 JWT、OAuth2 等机制。
• 保持一致性 ：命名规范、数据结构、错误处理方式等，在整个项目或团队内部尽量保持一致。别一个接口返回 userId，另一个接口返回 userID，逼死强迫症。
• 拥抱 HATEOAS (Hypermedia as the Engine of Application State)：这是 REST 更高阶的理念，简单说就是在 API 响应中包含相关操作的链接，让客户端可以根据这些链接"发现"下一步能做什么。这个对于初级开发者可能有点复杂，可以先了解一下。

好了，关于 API 设计的这 8 个技巧就先聊到这。它们不是什么高深莫测的理论，更多的是业界沉淀下来的最佳实践。把它们应用到你的日常开发中，多思考，多实践，相信你设计的 API 会越来越优雅，跟人协作也会越来越顺畅。

记住，好的 API 设计不是一蹴而就的，它是一个持续学习和改进的过程。希望今天的分享能给你带来一些启发。

---

我是老码小张，一个喜欢研究技术原理，并且在实践中不断成长的技术人。希望今天的分享对你有帮助，也欢迎大家在评论区多多交流，一起进步！