计算机网络 / 系统课时

设计一组 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> 是接口契约占位值,需由实际服务替换;示例重点是方法、头部、字段与状态码之间的对应关系。

text
POST /api/v1/tasks HTTP/1.1
Host: api.example.com
Content-Type: application/json

{"title":"修复登录页","priority":"high"}

预期结果:

text
HTTP/1.1 201 Created
Location: /api/v1/tasks/<ID>
Content-Type: application/json

{"id":"<ID>","title":"修复登录页","priority":"high","status":"open"}

列表接口建议固定分页结构,不要有时返回数组、有时又包对象。下面的 nextCursor 为 null 表示已经到最后一页;若仍有下一页,则返回服务器生成的游标字符串。

text
GET /api/v1/tasks?status=open&limit=20 HTTP/1.1
Host: api.example.com
Accept: application/json

预期结果:

json
{"items":[{"id":"<ID>","title":"修复登录页","priority":"high","status":"open"}],"nextCursor":null}

处理更新、删除与错误

部分更新时只允许可修改字段,例如 title、priority、status。若任务不存在返回 404;JSON 结构错误返回 400;若当前资源状态不允许操作,例如已归档任务禁止重新打开,可以返回 409 表示与当前资源状态冲突。

text
PATCH /api/v1/tasks/<ID> HTTP/1.1
Host: api.example.com
Content-Type: application/json

{"status":"done"}

预期结果:

json
{"id":"<ID>","title":"修复登录页","priority":"high","status":"done"}

错误响应要保持稳定结构,例如 code 供程序判断,message 供人阅读。不要让某些接口返回纯字符串、另一些接口又返回完全不同的 JSON 形状。

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;对可能被自动重试的写操作,是否明确其幂等性。做到这些,接口联调时就能依靠协议判断结果,而不是依赖口头约定。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

设计一组 REST 接口

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通