让你的API从能用变优雅：RESTful设计实战经验谈

干后端开发这些年，我见过最离谱的API长这样：/getUserInfoById?id=123，还有个兄弟版本叫/queryUser?id=123。两个接口都能跑，但谁也不知道该用哪个。你以为我在编故事？不，这是我入职第一天就遇到的真实惨剧。

API设计这东西，入行门槛极低——随便找个框架，三分钟就能写出一个接口。但想把API写优雅，那才是真正的技术活。今天就跟大家聊聊，RESTful API设计里那些容易被忽视但又至关重要的实战经验。

一、先把命名这关过了

很多新手写API，动词全靠猜：get、fetch、query、retrieve……同一个意思，四种写法，后端自己两星期后都分不清哪个是哪个。

RESTful的核心就一句话：用名词，用复数，别用动词。

反例：/getUsers、/createOrder、/updateUserInfo
正例：/users、/orders、/users/{id}

有人会抬杠：那查询参数怎么体现动作？兄弟，HTTP方法就是用来干这个的：

GET    /users        # 获取用户列表
POST   /users        # 创建用户
GET    /users/{id}   # 获取单个用户
PUT    /users/{id}   # 更新整个用户
PATCH  /users/{id}   # 部分更新用户
DELETE /users/{id}   # 删除用户

六个方法，覆盖增删改查基本操作。动词进了HTTP方法，URL里全是资源名词，语义清晰，一看就懂。这才叫约定大于配置。

二、状态码不是随便写的

我见过最敷衍的API设计：无论成功失败，返回值全是200加个{success: true/false}。这种设计完全浪费了HTTP协议自带的语义表达能力。

HTTP状态码是接口的语气。你跟人说苹果很好吃，对方回嗯和回哇塞太棒了，感觉完全不同。API也是这样：

200 OK                    # 成功，且响应有内容
201 Created               # 创建成功，常配合Location头
204 No Content            # 成功，但响应体为空（常见于DELETE）
400 Bad Request           # 请求参数有误，客户端该检查自己的代码
401 Unauthorized          # 没登录或token过期
403 Forbidden             # 登录了但没权限
404 Not Found             # 资源不存在
422 Unprocessable Entity  # 语法对了但语义错误（如校验失败）
500 Internal Server Error  # 服务端出错，这个不该直接抛给用户

特别说一下422。这个状态码很多人不熟悉，但在Validation Errors（校验错误）场景下极其好用。你POST一个用户注册请求，username字段填了空字符串，400显得太粗暴——400意思是你发的东西我不认识；422更精确：你的数据我认识，但不符合规则。

三、分页不是简单的limit offset

数据量大了，分页是刚需。但很多人做分页就停留在：

GET /users?page=1&size=20

这个设计有两个问题。第一，翻到第五页，用户删掉了自己的一条数据，第六页就会出现数据错位——用户会看到重复或跳跃。第二，count(*)全表计数，数据量大时慢得让人怀疑人生。

更推荐的做法是游标分页（Cursor Pagination）：

GET /users?limit=20&cursor=eyJpZCI6MTAwfQ==

cursor里编码了上一页最后一条的ID或时间戳。删数据不影响，已读过的不会重复出现。代价是没法制页——但说实话，产品里真正需要跳页的场景少之又少，大多数时候用户就是在无限滚动而已。

如果非要保留第X页的概念，至少把总数也返回给前端：

{
  "data": [...],
  "pagination": {
    "total": 1334,
    "page": 5,
    "per_page": 20,
    "total_pages": 67
  }
}

四、错误响应要有统一格式

混乱的错误格式是API的癌症。看看这些真实混搭：

// 风格1
{"error": "User not found"}

// 风格2
{"message": "用户不存在", "code": 404}

// 风格3
[{"field": "email", "msg": "邮箱格式不正确"}]

// 风格4
"用户不存在"

前端拿到这些，要写多少if-else做兼容？一个统一的错误格式应该是这样的：

{
  "error": {
    "code": "USER_NOT_FOUND",
    "message": "用户不存在",
    "details": [
      {"field": "user_id", "message": "提供的用户ID在系统中不存在"}
    ]
  },
  "request_id": "req_7f3k9d2m8n1p"
}

code是给程序看的错误码，便于前端做分支判断。message是给人看的提示。details是可选的附加信息，校验失败时尤其有用。request_id是我强烈建议加的——出问题时，用户把request_id报给你，你直接在后端日志里搜，一分钟定位问题。

五、版本管理：宁可预设，不可后改

接口上线后再改字段名、删返回值，比在高速公路上换轮胎还危险。你永远不知道哪个角落里的调用方在依赖你的某个字段。

所以，从第一天就把版本号放URL里：

/api/v1/users
/api/v2/users

v1跑稳定了，新需求来，v2走起。v1再维护一段时间，确认没人用了再下掉。这不是浪费，这是保险。

有人会说：URL带版本号不RESTful！兄弟，实用优先于教条。Stateless的API里带上版本号，前端知道该调哪个，后端知道该返回什么格式，这才是最重要的。某些大厂（GitHub、Stripe）都是这么干的。

六、Field Filtering：让接口更灵活

一个用户对象有50个字段，列表页只需要id和name，你返回50个字段试试？流量蹭蹭涨，数据库白做了无用功。

给GET类接口加上字段过滤：

GET /users?fields=id,name,email
# 返回 {"users": [{"id": 1, "name": "张三", "email": "zhangsan@example.com"}]}

这个功能实现起来极简——SQL里指定列名而已。但对前端和流量的优化效果是立竿见影的。列表页减少90%数据传输量，后端内存压力也下来了。

写在最后

API设计没有银弹，但有些原则是经过大量实战验证过的：名词复数定义资源，状态码传递语义，统一格式承载错误，游标分页对抗数据变动，版本号预留扩展空间，字段过滤榨干带宽。

好的API设计，本质上是让调用方用最少的时间理解你的接口。你多花一小时设计接口，后面接手的同事就少踩一个坑，自己以后少填一个技术债。这就是为什么我一直说：写代码是门手艺，设计API是门艺术。

下次当你准备随手写一个/getData的时候，停一秒钟，想一想：这个名字，三个月后自己看了会不会懵？