diff --git a/README.md b/README.md index 8bfb70d..37c2557 100644 --- a/README.md +++ b/README.md @@ -208,6 +208,34 @@ export SKELETON_CONFIG=config/app.yaml 完整请求和响应模型请查看 Swagger UI。 +### 响应约定 + +业务接口统一使用 HTTP 200 返回结果,业务状态通过响应体中的 `code` 字段表达,不使用 HTTP 状态码传递业务成功或失败状态。 + +```json +{ + "code": 401, + "message": "用户名或密码错误", + "data": null +} +``` + +统一响应结构: + +| 字段 | 说明 | +| --- | --- | +| `code` | 业务状态码,例如 `200`、`400`、`401`、`409`、`500` | +| `message` | 面向调用方的结果说明 | +| `data` | 业务数据;失败时通常为 `null` | + +新增业务接口时必须遵守以下约定: + +- HTTP 响应状态固定为 `200 OK`。 +- 成功使用响应体 `code: 200`。 +- 参数、认证、权限和业务冲突等错误写入响应体 `code`。 +- 调用方应判断响应体中的 `code`,不能依赖 HTTP 状态码判断业务结果。 +- WebSocket 握手、协议升级失败以及基础设施健康检查不属于普通业务响应,可以使用对应的 HTTP 状态码。 + ### 认证示例 ```bash