2. RESTful API 设计规范：资源命名、HTTP方法选择、状态码使用、版本控制策略
聊到大屏数据接口设计，我见过太多团队一上来就撸代码，结果接口命名乱七八糟，状态码满天飞。说实话，RESTful 规范不是什么高深理论，它就是一套让前后端能好好沟通的约定。今天我把这几年踩过的坑和积累的经验，一次性说清楚。
2.1 资源命名：别让接口名变成猜谜游戏
资源命名是 API 设计的门面。我个人的习惯是：用名词复数，不用动词。为什么？因为 REST 的核心是「资源」，不是「操作」。
核心原则：
- 使用名词复数：
/users而不是/getUser - 层级关系用斜杠：
/users/123/orders - 查询参数过滤：
/users?status=active - 避免动词：不要出现
/createUser或/deleteOrder
我在项目中遇到过这样一个案例：有个同事把接口写成 /api/getUserInfoByUserId，你想想看，这名字又长又绕。后来我建议改成 /users/{id}，简洁明了。说白了，好的命名应该让新人看一眼就知道是干嘛的。
小技巧：资源名尽量用英文，别用拼音。我曾经见过 /yonghu/list 这种接口，维护起来真的很痛苦。
2.2 HTTP 方法选择：GET 和 POST 不是万能药
很多新手喜欢所有接口都用 POST，省事。但 RESTful 设计里，每个 HTTP 方法都有它的使命。
| 方法 | 用途 | 幂等性 | 示例 |
|---|---|---|---|
| GET | 查询资源 | 是 | GET /users/123 |
| POST | 创建资源 | 否 | POST /users |
| PUT | 全量更新 | 是 | PUT /users/123 |
| PATCH | 部分更新 | 否 | PATCH /users/123 |
| DELETE | 删除资源 | 是 | DELETE /users/123 |
嗯，这里要注意：GET 请求不能修改数据。我见过有人把删除操作写成 GET /deleteUser?id=1，搜索引擎爬虫路过就把数据删了，那场面……你懂的。
避坑指南：我曾经在项目中用 POST 做查询，结果前端传参越来越复杂，最后接口文档写了三页。后来全部改成 GET + 查询参数，清爽多了。记住：查询用 GET，创建用 POST，更新用 PUT/PATCH，删除用 DELETE。
2.3 状态码使用：别让 200 包打天下
状态码是服务器对客户端的「一句话反馈」。我见过最离谱的是：不管成功还是失败，统统返回 200，然后在 body 里塞一个 code 字段。这其实是在「自己造轮子」，完全违背了 HTTP 协议的设计初衷。
常用的状态码其实就这几个：
- 200 OK：请求成功，返回数据
- 201 Created：创建成功，通常配合 POST
- 204 No Content：删除成功，没有返回体
- 400 Bad Request：参数错误，客户端的问题
- 401 Unauthorized：没登录或 token 过期
- 403 Forbidden：没权限，登录了也不让看
- 404 Not Found：资源不存在
- 500 Internal Server Error：服务器炸了
我的经验：大屏接口对错误处理要求更高。因为大屏是 7x24 小时运行的，一旦接口报错，前端可能直接白屏。所以我建议：所有错误都返回统一的 JSON 结构，比如：
{
"code": 400,
"message": "参数 userId 不能为空",
"timestamp": 1700000000000
}你想想看，如果前端能根据 code 字段做统一处理，是不是比解析各种乱七八糟的错误信息要省心得多？
2.4 版本控制策略：给接口留条后路
接口版本控制，说白了就是「别让老客户端挂掉」。我见过太多团队，接口一升级，旧版 App 全部瘫痪，用户骂声一片。
常见的版本控制方式有三种：
| 方式 | 示例 | 优点 | 缺点 |
|---|---|---|---|
| URL 路径 | /v1/users |
直观，容易路由 | URL 不够干净 |
| 请求头 | Accept: application/vnd.myapp.v1+json |
URL 干净 | 调试不方便 |
| 查询参数 | /users?version=1 |
实现简单 | 容易被缓存污染 |
我个人习惯用 URL 路径方式。为什么？因为直观。前端同学调试时，一眼就能看出用的是哪个版本。我曾经在项目中用过请求头方式，结果每次联调都要解释半天「你那个 Accept 头配对了没」，太累了。
版本策略建议：
- 大版本用 URL 路径：
/v1/、/v2/ - 小版本用兼容设计：新增字段不删旧字段
- 每个版本至少维护 6 个月，给客户端留足升级时间
- 废弃接口返回 410 Gone 状态码，明确告知客户端
嗯，最后说一句：版本号不要用时间戳。我见过有人用 /v20240101/ 这种命名，结果一年后接口文档里全是各种日期，根本分不清哪个是最新版。
避坑指南：我曾经接手过一个项目，接口版本号写在数据库里。每次升级都要改数据库配置，还要重启服务。后来我全部改成 URL 路径 + Nginx 路由，升级只需要部署新代码，旧版本自动走老路由。省心多了。
好了，RESTful 设计规范就聊这么多。记住一句话：规范不是束缚，是让团队少吵架的约定。下一章我们聊聊大屏接口的缓存策略，那才是真正考验后端功底的地方。