docs(standards): 补充 Result<T> 统一响应类文档,修正 API 设计规范响应格式

- 新增 Result统一响应类.md 完整文档
- 修正 API设计规范.md 中响应字段与实际代码不一致的问题
- 错误码规范表按实际 ResultCode 枚举对齐
This commit is contained in:
2026-06-08 16:01:03 +08:00
parent d4a3bd5847
commit 1324a52049
2 changed files with 352 additions and 14 deletions
+20 -14
View File
@@ -116,10 +116,12 @@ GET /v1/user/users?username=admin&status=1&createdAt_start=2024-01-01&createdAt_
### 4.1 统一响应格式
> 详细规范见 [Result 统一响应类](Result统一响应类.md)
```json
{
"code": 200,
"msg": "操作成功",
"error": 0,
"message": "操作成功",
"data": {}
}
```
@@ -128,8 +130,8 @@ GET /v1/user/users?username=admin&status=1&createdAt_start=2024-01-01&createdAt_
```json
{
"code": 200,
"msg": "操作成功",
"error": 0,
"message": "操作成功",
"data": {
"records": [],
"total": 100,
@@ -159,19 +161,23 @@ GET /v1/user/users?username=admin&status=1&createdAt_start=2024-01-01&createdAt_
| 区间 | 模块 | 示例 |
|------|------|------|
| 1000-1999 | 通用 | 1001: 参数校验失败, 1002: 资源不存在 |
| 2000-2999 | 用户模块 | 2001: 用户名已存在, 2002: 密码错误 |
| 3000-3999 | 系统模块 | 3001: 字典不存在, 3002: 配置错误 |
| 4000-4999 | 认证模块 | 4001: Token 过期, 4002: 无权访问 |
| 5000-5999 | 文件模块 | 5001: 上传失败, 5002: 文件过大 |
| 6000-6999 | 消息模块 | 6001: 发送失败, 6002: 模板不存在 |
| 0 | 通用成功 | `0: 操作成功` |
| 1 | 通用失败 | `1: 操作失败` |
| 400-499 | HTTP 标准 | `401: 未授权, 404: 资源不存在` |
| 4000-4099 | 认证模块 | `4001: Token 过期, 4002: Token 无效` |
| 4100-4199 | 用户信息 | `4101: 用户不存在, 4102: 用户名已存在` |
| 4200-4299 | 用户等级 | `4201: 等级编码已存在` |
| 5000-5999 | 文件模块(预留) | `5001: 上传失败, 5002: 文件大小超限` |
| 6000-6999 | 消息模块(预留) | `6001: 发送失败, 6002: 模板不存在` |
> 完整枚举值见 [Result 统一响应类 → ResultCode 枚举](Result统一响应类.md#四resultcode-枚举)
**错误响应示例**
```json
{
"code": 2001,
"msg": "用户名已存在",
"data": null
"error": 4102,
"message": "用户名已存在",
"code": "USER_INFO_USERNAME_EXISTS"
}
```
@@ -321,7 +327,7 @@ public class UserRemoteService {
if (result.isSuccess()) {
return result.getData();
}
throw new BizException(result.getCode(), result.getMsg());
throw new BizException(result.getError(), result.getMessage());
}
}
```