RESTful API 设计简单介绍

前后端一旦分离，两边就只剩"接口"这一个契约。但接口怎么写才算规范？很多人写的接口长这样：/getUserList、/deleteUserById、/api/queryUserInfo……能用，但不规范，多了之后很容易乱。本文把它拉回正轨。

一、RESTful 到底在"规矩"什么

REST 是一种**用 URL 表示"资源"、用 HTTP 动词表示"动作"**的设计风格。核心就两条：

• URL 只描述"资源是什么"，不描述"要干什么"。
• "要干什么"交给 HTTP 动词（GET/POST/PUT/DELETE…）来表达。

所以一个用户资源，所有操作都围绕 /users 这个名词转，靠动词区分：

对照看就明白野路子错在哪：

记住一句话：URL 是名词，动词留给 HTTP 方法。别把俩都塞进 URL。

二、URL 设计的几个习惯

1. 用复数，不用单数：/users 而不是 /user。列表和详情统一在复数下，少一种例外。
2. 层级用嵌套表达关系：/users/1/orders 表示"用户 1 的订单"，资源从属关系一目了然。
3. 过滤/分页/排序放 query：GET /users?page=1&size=20&sort=-createdAt。这些是"怎么查"，不是资源本身。
4. 版本放路径最前面：/v1/users。以后大改不破坏老客户端。
5. 小写 + 中划线：/order-items 而不是 /orderItems 或 /OrderItems，统一最省心。

三、状态码

有的人图省事的，所有接口都返回 200，成功失败靠 body 里的 code 字段判断。能用，但丢了 HTTP 本身的语义。建议对齐：

约定：4xx 是"你（客户端）的问题"，5xx 是"我（服务端）的问题"。前端拿到 4xx 该提示用户检查输入，拿到 5xx 该上报运维或者后端。

四、响应体要有统一格式

别有的接口返回数组、有的返回 {data: [...]}、有的返回 {result: ...}。统一一种，比如：

{
  "code": 0,
  "message": "ok",
  "data": {
    "id": 1,
    "name": "张三",
    "roles": ["admin"]
  }
}

分页再套一层：

{
  "code": 0,
  "message": "ok",
  "data": {
    "list": [ { "id": 1, "name": "张三" } ],
    "total": 135,
    "page": 1,
    "size": 20
  }
}

前端拿到后只认 data 字段，管你后面换什么数据库、什么语言，照常解析。

五、字段命名和安全的小细节

• 命名统一：要么全 camelCase（userName），要么全 snake_case（user_name），前后端对齐，别混。
• 别过度暴露：返回用户对象时，密码、盐值、内部标记这些字段坚决不往下发。
• 时间用标准格式：2026-08-25T10:13:16+08:00（ISO 8601），前端好解析，别发 "8月25号"这种的。
• 写文档：用 OpenAPI/Swagger 把上面的约定固化成文档，前后端对着文档开发。

六、小结

RESTful 不是固定规矩，但它的"名词 URL + 动词方法 + 标准状态码 + 统一响应"这一套，能极大降低前后端的沟通成本。不规范方便的接口短期省事，长期全是技术债——新同事接收后看不懂、网关没法优化、客户端判断逻辑越写越乱。