RESTful API设计的十个常见错误（襄阳后端工程师总结）

错误一：用GET做状态修改

GET请求应该是幂等的(多次调用结果相同)和安全的(不改变服务端状态)。见过太多用GET做删除操作的API了——/user/delete?id=123。这不仅违反HTTP语义，还可能被搜索引擎爬虫或预加载器意外触发。

正确做法：DELETE /users/123

错误二：URL中没有用名词复数

/getUser /listProduct /createOrder ——这些都是反模式。URL应该代表资源，用名词复数形式。

正确做法：GET /users POST /orders GET /products

错误三：状态码乱用

不管什么情况都返回200，然后在body里放个code字段表示错误。这完全浪费了HTTP状态码的语义。

常用状态码速查：200 OK(成功)、201 Created(创建成功)、204 No Content(删除成功无返回体)、400 Bad Request(参数错误)、401 Unauthorized(未认证)、403 Forbidden(无权限)、404 Not Found(不存在)、500 Internal Server Error(服务端内部错误)。

错误四：返回数据不做分页

GET /users 返回全部用户数据？当数据量大了之后这个接口就废了。

正确做法：GET /users?page=1&size=20 返回体中包含 total/page/size/data 字段。还可以加上 next_page_token 支持游标分页。

错误五：版本号放在URL里

/api/v1/users /api/v2/users ——URL中出现版本号看起来直观但其实不好。v1和v2的资源含义一样为什么要换URL？

更好的做法是把版本号放在请求头 Accept: application/vnd.myapi.v2+json 中。URL保持干净：/api/users

当然如果团队觉得放在URL里更方便也不是不行，保持一致就好。

错误六：没有统一的错误格式

有的接口返回 {code: 400, msg: "error"} 有的返回 {error: "not found"} 还有的返回 {success: false, data: null}。前端同学要为每种格式写不同的解析逻辑。

推荐统一格式：{"code": 1001, "message": "参数错误", "details": {"field": "email", "reason": "格式不正确"}} code区分错误类型，message给人看，details给程序用。

错误七：缺少接口文档

"代码就是文档"？别逗了。没有文档的接口就是坑——前端猜参数、联调靠问、后期没人敢动。

最低要求：用Swagger/OpenAPI自动生成文档。代码里写好注解，文档自动更新。成本很低但收益很大。

错误八：不做鉴权

所有接口裸奔？任何人都能调用？这在内网系统也许还行，一旦暴露到互联网就是灾难。

最小要求：JWT Token鉴权 + 接口级别的权限校验。敏感操作还要加上二次验证(短信/邮箱/TOTP)。

错误九：不支持排序和过滤

GET /articles 只能按固定顺序返回？客户端想按时间倒序/阅读量排序/筛选某个分类怎么办？

支持通用查询参数：?sort=-created_at&status=published&category_id=5 后端解析这些参数动态构建查询。既灵活又不复杂。

错误十：嵌套层级过深

/users/123/orders/456/items/789 ——五层嵌套的URL看着就头大。通常超过三层就该考虑简化了。

可以用查询参数替代路径嵌套：/orders?user_id=123 或者直接用ID定位资源：/order-items/789

总结

好的API设计原则其实很简单：遵循HTTP语义、URL表达资源、状态码表达结果、统一数据格式、提供充分文档。做到这几点就已经超越80%的API了。