服务端API设计规范：让接口更清晰、更稳定

做后端开发，写API是家常便饭。但很多人一开始只图自己写得快，结果调用方一多，问题就来了：字段命名不统一、返回格式五花八门、错误码满天飞。时间一长，连自己都不想维护。

统一风格，从命名开始

比如查用户订单，有人写 /getOrderList，有人写 /user/orders。前者像在写函数，后者才像在设计资源访问路径。RESTful 的思路就是把数据当资源看，用 HTTP 方法表达操作意图。

推荐使用小写中划线（kebab-case）或小写下划线（snake_case）来命名路径和参数：

/api/v1/user-orders?status=completed&page=1
/api/v1/user_info

字段名也一样，别一会儿 userName，一会儿 user_name，团队里定个规则，坚持用一种。

状态码别乱用

200 不是万能钥匙。删除成功应该返回 204 No Content，创建成功用 201 Created。客户端靠这个判断下一步动作，不是光看返回体里的 success: true 就完事了。

常见用法：

• 200 OK - 查询成功
• 201 Created - 资源新建
• 400 Bad Request - 参数不对
• 401 Unauthorized - 没登录
• 403 Forbidden - 登录了但没权限
• 404 Not Found - 路径错了或资源不存在
• 500 Internal Server Error - 服务器出问题

返回结构要一致

不管成功失败，外层结构最好固定。这样前端处理起来省心，不会每次都要猜“这次有没有 data 字段”。

{
  "code": 0,
  "message": "OK",
  "data": {
    "id": 123,
    "name": "张三"
  }
}

出错时：

{
  "code": 4001,
  "message": "手机号格式不正确",
  "data": null
}

code 可以自定义业务错误码，方便定位问题。

分页参数标准化

别自己发明轮子。主流做法是用 page 和 size，或者 offset 和 limit。选一个，全系统统一。

/api/v1/articles?page=2&size=10

返回时带上总数，不然前端没法画分页条。

{
  "data": [...],
  "total": 87,
  "page": 2,
  "size": 10
}

版本控制别忽略

API 一旦上线，就不能随便改。加字段可以，删字段或改含义不行。所以从一开始就考虑版本，路径里带上 v1：

/api/v1/users

哪天要动大手术，出个 v2，老接口还能撑一段时间。

文档不是摆设

写完不写文档，等于没写。用 Swagger 或 OpenAPI 生成可交互文档，让前端同学能直接试接口。参数类型、是否必填、示例值都标清楚，少扯皮。

比如标注一个查询参数：

GET /api/v1/posts?category_id=5&include_draft=false

// category_id: integer, required
// include_draft: boolean, optional, default false

这些细节堆起来，决定了团队协作效率。好 API 不是跑得快，而是让人用得顺。”,”seo_title”:”服务端API设计规范指南 – 数智应用帮”,”seo_description”:”掌握服务端API设计规范的关键要点，包括命名约定、状态码使用、返回结构统一、分页标准和版本控制，提升系统可维护性与协作效率。”,”keywords”:”服务端API设计, API设计规范, RESTful API, 接口设计, 后端开发, API文档, 状态码使用”}