之前接手过一个老项目，API接口设计得乱七八糟。同样是获取用户信息，有的地方用getUserById，有的地方用queryUserInfo，还有的用fetchUser。数据类型也是随心所欲，有返回字符串的，有返回数字的，同一个字段在不同接口里格式还不一样。前端对接的时候怨声载道，我也头疼得很。

后来痛定思痛，决定规范一下API设计规范。查了不少资料，也踩了不少坑。今天把API设计的一些关键点整理出来，供大家参考。

URL设计要规范

URL是API的门面，设计得好不好直接影响使用体验。RESTful规范要求URL使用名词复数形式，不要用动词。

错误示例：/getUsers、/createUser、/deleteUserById
正确示例：GET /users（获取用户列表）、POST /users（创建用户）、DELETE /users/{id}（删除用户）

URL层级结构要清晰，表达资源归属关系。比如用户的订单，应该写成 /users/{userId}/orders，而不是 /userOrders这种模糊的命名。

避免过深的嵌套，一般不要超过三层。嵌套太深不仅URL难看，前端调用也不方便。如果确实需要复杂查询，优先考虑通过查询参数来实现。

URL全部小写，单词之间用连字符分隔。不要用下划线，有些人喜欢用下划线，但在某些字体下跟装饰线混淆。

HTTP方法要正确使用

GET用于获取资源，不应该有任何副作用。POST用于创建资源。PUT用于完整更新一个资源，PATCH用于部分更新。DELETE用于删除资源。

常见的错误是用GET做删除操作，或者用POST做查询。HTTP方法是有语义的，遵守这个语义能让API更容易理解，也方便使用HTTP缓存。

GET请求的参数可以通过查询字符串传递，比如 /users?status=active&page=1。POST、PUT、PATCH的数据通过请求体传递，用JSON格式。

响应状态码要正确。GET成功返回200，创建成功返回201，删除成功返回204。客户端错误返回4xx，服务端错误返回5xx。不要所有错误都返回200，然后在响应体里说"code": 500。

响应结构要统一

所有接口的响应格式要统一，这样前端才好处理。我推荐的结构是：

成功响应：
{
  "code": 0,
  "message": "success",
  "data": { ... }
}

错误响应：
{
  "code": 10001,
  "message": "用户不存在",
  "data": null
}

code是业务错误码，不同的错误类型用不同的code。message是给开发者看的错误描述，方便调试。data是实际数据，成功时返回，失败时为null或空对象。

分页列表的响应也要统一格式：
{
  "code": 0,
  "message": "success",
  "data": {
    "list": [...],
    "pagination": {
      "page": 1,
      "pageSize": 20,
      "total": 100
    }
  }
}

接口版本控制

API不可能一成不变，需求在变，业务在变，接口也要跟着变。但已有接口不能随便改，会影响已有的调用方。版本控制就是解决方案。

常见的版本控制方式有两种：URL路径版本和请求头版本。URL路径版本更直观，比如 /api/v1/users 和 /api/v2/users。请求头版本如 Accept: application/vnd.api+json;version=2。

我的建议是用URL路径版本，简单直接。前端调用的时候切换版本方便，API网关也容易配置。

版本号用主版本号就够了，不需要细化到次版本号。v1、v2这样就可以，大的版本号变更表示有不兼容的修改。

旧版本要有一定的存活时间，给调用方足够的迁移时间。一般建议旧版本至少保留一年，新版本出来后一年后再下架。

错误处理要完善

好的错误处理能大大提升API的可用性。客户端调用失败的时候，要能清楚地知道是什么问题，是重试还是修改参数。

首先，HTTP状态码要用对。400表示请求参数有问题，401表示未认证，403表示没有权限，404表示资源不存在，422表示参数校验失败，429表示请求过于频繁，500表示服务器内部错误。

其次，响应体里要有详细的错误信息。包括错误码、错误描述、哪个字段出错了、正确的格式是什么。这些信息对开发者调试非常重要。

参数校验要统一处理。请求参数校验失败的响应格式要和其他错误一致，不要有时候返回422，有时候返回400，格式混乱会让前端很难处理。

敏感信息不要出现在错误信息里。比如数据库连接错误、内部异常堆栈，这些不能让外部看到，会带来安全隐患。

安全性要考虑

API安全是个大话题，这里只说几个关键的点。

认证和授权要分开。认证是验证你是谁，授权是验证你能做什么。两步分开处理，逻辑更清晰，也更灵活。

接口限流要做好。防止恶意调用或者误操作对服务器造成压力。根据用户ID、IP等维度做限流，超过限制的返回429状态码。

跨域要处理好。如果API和前端不在同一个域，要正确配置CORS。不要用 * 允许所有来源，太危险了。

敏感数据要脱敏。日志里不要记录完整的手机号、身份证号、银行卡号，显示给前端的时候也要脱敏处理。

文档要写好

API设计得再好，别人不知道怎么用也是白搭。所以接口文档非常重要。

现在有很多API文档工具，比如Swagger、Apifox、Postman。这些工具能根据代码注释或者YAML文件自动生成文档，还能在线调试。

文档要包括：接口地址、请求方法、请求参数说明、响应格式示例、错误码说明。每个参数的类型、是否必填、取值范围都要写清楚。

文档要及时更新。代码改了文档也要改，宁可文档写得简单一点，也不要写一些过时的、让人误解的东西。

写在最后

API设计没有绝对的标准，重要的是团队内部保持一致。新项目开始的时候就把规范定下来，大家一起遵守，比后期改要省事得多。

好的API设计应该简洁、一致、易用。站在调用方的角度思考问题，让API用起来顺手，这才是一个好API该有的样子。