From 20e92dc82f95115019a389e6e035598e546e5b1b Mon Sep 17 00:00:00 2001
From: xchou <programmerbugsbunny@gmail.com>
Date: Sun, 9 Aug 2026 01:13:58 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E8=A1=A5=E5=85=85=E4=B8=9A=E5=8A=A1?=
 =?UTF-8?q?=E5=93=8D=E5=BA=94=E7=A0=81=E7=BA=A6=E5=AE=9A?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)

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