计算机网络 / 系统课时
设计一组 REST 接口
设计一组 REST 接口
这篇用“任务 Task”资源设计一组可直接落地的 REST 接口,覆盖查询、创建、更新和删除。完成后,你应能根据资源语义选择 HTTP 方法、路径与状态码,并把成功响应、错误响应和幂等边界写成一份可联调的接口契约。
学习目标
- 用资源名设计集合路径与单资源路径,避免把动作塞进 URL。
- 为查询、创建、更新、删除选择合适的方法与成功状态码。
- 定义请求体、响应体、分页字段和常见错误,使前后端可以独立联调。
从资源而不是动作命名路径
假设业务对象是任务,统一前缀使用 /api/v1。集合路径写成 /api/v1/tasks,单个任务写成 /api/v1/tasks/{id}。不要设计 /createTask、/deleteTask?id=... 这类把动作重复写进路径的接口。
| 操作 | 方法与路径 | 成功状态码 | 关键语义 |
|---|---|---|---|
| 查询列表 | GET /api/v1/tasks |
200 | 不修改资源,可带过滤和分页参数 |
| 查询单条 | GET /api/v1/tasks/{id} |
200 | 找不到资源返回 404 |
| 创建任务 | POST /api/v1/tasks |
201 | 服务器生成新资源标识 |
| 部分更新 | PATCH /api/v1/tasks/{id} |
200 | 只提交需要变化的字段 |
| 删除任务 | DELETE /api/v1/tasks/{id} |
204 | 成功后不返回响应正文 |
列表过滤直接放查询参数,例如 GET /api/v1/tasks?status=open&priority=high&limit=20。limit 可以限制为 1~100,超过上限返回 400,避免一次请求拖出过大的结果集。
选择方法与状态码
GET 只读取数据;POST 用于在集合下创建新资源;PATCH 适合修改少量字段;DELETE 删除指定资源。若客户端需要完整替换资源,可以另行支持 PUT /api/v1/tasks/{id},但不要同时把 PUT 和 PATCH 都定义成“随便更新”。
创建成功返回 201,并在 Location 头中给出新资源路径。更新后若返回最新资源,使用 200;若明确不返回正文,可以使用 204。删除不存在的任务返回 404,而不是为了“方便”始终返回 200,否则客户端无法区分目标是否真的存在。
定义创建与列表契约
下面给出一组完整 HTTP 消息示例。这里的域名和 <ID> 是接口契约占位值,需由实际服务替换;示例重点是方法、头部、字段与状态码之间的对应关系。
POST /api/v1/tasks HTTP/1.1
Host: api.example.com
Content-Type: application/json
{"title":"修复登录页","priority":"high"}预期结果:
HTTP/1.1 201 Created
Location: /api/v1/tasks/<ID>
Content-Type: application/json
{"id":"<ID>","title":"修复登录页","priority":"high","status":"open"}列表接口建议固定分页结构,不要有时返回数组、有时又包对象。下面的 nextCursor 为 null 表示已经到最后一页;若仍有下一页,则返回服务器生成的游标字符串。
GET /api/v1/tasks?status=open&limit=20 HTTP/1.1
Host: api.example.com
Accept: application/json预期结果:
{"items":[{"id":"<ID>","title":"修复登录页","priority":"high","status":"open"}],"nextCursor":null}处理更新、删除与错误
部分更新时只允许可修改字段,例如 title、priority、status。若任务不存在返回 404;JSON 结构错误返回 400;若当前资源状态不允许操作,例如已归档任务禁止重新打开,可以返回 409 表示与当前资源状态冲突。
PATCH /api/v1/tasks/<ID> HTTP/1.1
Host: api.example.com
Content-Type: application/json
{"status":"done"}预期结果:
{"id":"<ID>","title":"修复登录页","priority":"high","status":"done"}错误响应要保持稳定结构,例如 code 供程序判断,message 供人阅读。不要让某些接口返回纯字符串、另一些接口又返回完全不同的 JSON 形状。
{"code":"TASK_NOT_FOUND","message":"Task does not exist"}删除成功采用 204 No Content 时,响应正文必须为空;客户端不应继续尝试解析 JSON。若业务要求保留软删除状态,也应在接口文档中明确删除后再次 GET 是返回 404,还是返回带 deletedAt 的资源。
用检查表验收接口设计
交付前逐项检查:同一类资源是否使用一致的复数名词;路径里是否没有 create、update、delete 等多余动作词;创建是否返回 201 和 Location;删除 204 是否确实无正文;404、400、409 的触发条件是否能被测试复现。
再检查请求与响应格式:JSON 接口是否统一使用 Content-Type: application/json;列表分页是否有固定上限;错误响应是否有稳定的机器可读 code;对可能被自动重试的写操作,是否明确其幂等性。做到这些,接口联调时就能依靠协议判断结果,而不是依赖口头约定。