Go / 系统课时

定义服务 API 与错误契约

定义服务 API 与错误契约

综合服务动手编码前,先固定客户端可以发送什么、服务端成功时返回什么,以及失败后客户端如何判断原因。本节以任务资源为例,定义一组可直接实现和测试的 HTTP 契约,并把幂等行为纳入接口约束。

学习目标

  • 定义资源端点、请求字段和成功响应的稳定边界
  • 设计可由客户端程序化处理的错误码与错误响应
  • 明确创建接口的幂等键语义和冲突规则

先固定资源与端点

示例服务管理 task 资源。综合演练先保留两个端点,避免在实现阶段一边写处理器一边改变协议。

方法 路径 作用 成功状态码
POST /v1/tasks 创建任务 201 Created
GET /v1/tasks/{id} 查询单个任务 200 OK

创建接口接收 title 和 priority。其中 title 去除首尾空白后必须为 1~120 个字符,priority 只允许 low、normal、high。创建请求还必须携带 Idempotency-Key 请求头,使客户端在超时重试时不会意外创建多个资源。

定义成功响应

请求体只包含客户端能够决定的字段;id 和 status 由服务端产生。下面是创建请求的数据结构示例。

json
{"title":"ship report","priority":"high"}

成功后返回 201 Created,同时用 Location 指向新资源。响应体固定包含资源当前状态,后续处理器和客户端都应围绕这一结构实现。

json
{"id":"<ID>","title":"ship report","priority":"high","status":"pending"}

<ID> 代表服务端生成的实际资源 ID,每次运行可能不同。字段一旦作为公开契约发布,就不应因为内部结构调整而随意改名或改变类型。

统一错误契约

HTTP 状态码负责描述失败类别,业务错误码负责让客户端稳定判断具体原因。错误响应统一采用 error 对象,不把数据库异常、堆栈或内部实现细节直接返回给调用方。

json
{"error":{"code":"INVALID_ARGUMENT","message":"priority must be low, normal, or high","requestId":"<ID>","details":{"field":"priority"}}}

建议为本服务固定以下最小错误集合:400 INVALID_ARGUMENT 表示请求无法解析或字段无效,404 TASK_NOT_FOUND 表示资源不存在,409 IDEMPOTENCY_CONFLICT 表示同一幂等键对应了不同请求,500 INTERNAL 表示未向客户端暴露细节的服务端故障。

约定幂等行为

对 POST /v1/tasks,服务端把 Idempotency-Key 与请求的规范化内容关联保存。同一个键再次收到相同请求时,应返回第一次创建得到的同一资源;如果同一个键被用于不同请求,则返回 409 IDEMPOTENCY_CONFLICT,而不是悄悄创建第二个资源。

幂等记录通常只需保存有限时间,但保留时长也属于服务约定。客户端只有在请求语义没有改变时才能复用原键;用户主动发起新的创建动作时,应使用新的幂等键。

用一次请求验证契约

在后续服务已经监听 8080 端口后,可以直接发送创建请求。这里的 demo-001 是演示用幂等键。

bash
curl -i -X POST http://localhost:8080/v1/tasks -H 'Content-Type: application/json' -H 'Idempotency-Key: demo-001' -d '{"title":"ship report","priority":"high"}'

预期输出

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

{"id":"<ID>","title":"ship report","priority":"high","status":"pending"}

实际响应还可能包含 Date、Content-Length 等由 HTTP 服务器生成的头部。验收重点是状态码、Location、响应字段以及重复使用同一幂等键时是否仍指向同一资源。这样先锁定契约,后续路由、处理器、服务层和测试就有了共同且可验证的边界。

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

目录与阅读设置

阅读设置

17

记录一个想法

定义服务 API 与错误契约

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

登录哪都通