嘿，大家好，我是老码小张。
不知道你有没有遇到过这样的情况？刚接手一个项目，或者要跟隔壁团队的伙伴联调接口，结果发现 API 设计得那叫一个"百花齐放"：有的接口名叫 /getUserInfo，有的叫 /queryUserList，还有的直接是 /user/find；参数呢，一会儿是 userId，一会儿是 user_id，一会儿又是 uid... 文档要么语焉不详，要么干脆就没更新。每次对接，都感觉像在玩"大家来找茬"，沟通成本蹭蹭往上涨，开发效率直线下降，心里那叫一个苦啊！
是不是感觉膝盖中了一箭？别慌，这其实是很多项目，尤其是快速迭代的项目中常见的问题。接口设计得好不好，直接关系到团队协作的效率，甚至影响到系统的稳定性和可维护性。一个清晰、规范、易于理解的 API，就像团队之间的一门"通用语言"，能让沟通顺畅，开发高效。
今天，我就结合自己踩过的一些坑，以及业界比较成熟的一些经验，给大家分享 8 个实用的 API 设计技巧。掌握了它们，不敢说让你立马成为 API 设计大师，但至少能让你设计的接口，看起来更专业，用起来更顺手，跟别人协作起来也更轻松！
一、数据格式？没啥说的，拥抱 JSON 吧！
现在都什么年代了，API 返回的数据格式，基本上没啥悬念，JSON (JavaScript Object Notation) 就是最优选。为啥？
- 人类可读：结构清晰，一眼就能看明白数据是啥样的。
- 机器友好：几乎所有编程语言都有现成的库来解析和生成 JSON，处理起来方便得很。
- 轻量高效：相比 XML，体积更小，网络传输更快。
别用那些古老的 XML 或者自定义的奇奇怪怪格式了，除非有非常特殊的理由。坚持用 JSON，能省不少事儿。
json
// 推荐的 JSON 格式
{
"id": 12345,
"username": "laomaxiaozhang",
"email": "laoma@example.com",
"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": "..."}。这不规范！
正确姿势：
- 使用标准的 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(服务暂不可用)
- 在响应体中提供详细的错误信息：只给个状态码有时候不够，最好在 JSON 响应体里，提供更具体的错误代码 (业务错误码)、错误消息 (给人看的描述)、可能还有详细的错误细节 (比如哪个字段错了)。
json
// 示例：一个 400 Bad Request 的响应体
{
"error": {
"code": "INVALID_PARAMETER",
"message": "请求参数校验失败",
"details": [
{
"field": "email",
"issue": "邮箱格式不正确"
}
]
}
}这样设计，调用方拿到响应，一看状态码就知道大概情况，再看响应体就能快速定位问题。
七、API 版本控制：给未来留条后路
你的业务在发展，系统在迭代，API 不可能一成不变。但你又不能随便改动线上正在使用的 API，否则依赖它的客户端或服务可能就挂了。怎么办？
API 版本控制就是答案。
常见的版本控制方式有：
- URL 路径中加版本号 (推荐) ：比如
/v1/users,/v2/users。这是最常见、最直观的方式。 - 查询参数中加版本号 ：比如
/users?version=1。 - 请求头 (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 设计不是一蹴而就的，它是一个持续学习和改进的过程。希望今天的分享能给你带来一些启发。
我是老码小张，一个喜欢研究技术原理，并且在实践中不断成长的技术人。希望今天的分享对你有帮助，也欢迎大家在评论区多多交流，一起进步！