IM/docs/📘 接口响应 Code 设计文档.md

📘 接口响应 Code 设计文档

1. 响应数据结构

统一使用 JSON 格式：

{
  "code": 0,
  "message": "请求成功",
  "data": {}
}

• code：数字型，业务状态码
• message：字符串，错误或提示信息
• data：对象/数组，返回的数据内容（可选）

---

2. Code 设计原则

1. 统一性：所有接口返回结构一致。
2. 分级设计：分为系统级错误（1xxx）、业务错误（2xxx+）。
3. 可扩展性：预留范围，避免混乱。

---

3. Code 约定规范

3.1 成功类

code	message	说明
0	成功	通用成功响应

---

3.2 系统级错误（1000 ~ 1999）

code	message	说明
1000	系统错误	未知异常
1001	服务不可用	服务器维护中或宕机
1002	请求超时	后端超时
1003	参数错误	缺少或参数不合法
1004	数据库错误	数据库读写失败
1005	权限不足	无权限访问
1006	认证失败	Token 无效/过期

---

3.3 用户相关错误（2000 ~ 2099）

code	message	说明
2000	用户不存在	查询不到用户
2001	用户已存在	注册时用户已存在
2002	密码错误	登录密码错误
2003	用户被禁用	被管理员封禁
2004	登录过期	需重新登录

---

3.4 好友相关错误（2100 ~ 2199）

code	message	说明
2100	好友申请已存在	重复申请
2101	好友关系不存在	不是好友
2102	已经是好友	重复添加
2103	好友请求被拒绝	被对方拒绝
2104	无法申请加好友	被对方拉黑

---

3.5 群聊相关错误（2200 ~ 2299）

code	message	说明
2200	群不存在	查询不到群
2201	已在群中	不能重复加入
2202	群成员已满	超出限制
2203	无加群权限	需要邀请/验证
2204	群邀请已过期	邀请链接过期

---

3.6 消息相关错误（2300 ~ 2399）

code	message	说明
2300	消息发送失败	发送时异常
2301	消息不存在	查询不到
2302	消息撤回失败	超过时间限制
2303	不支持的消息类型	message_type 不合法

---

3.7 文件相关错误（2400 ~ 2499）

code	message	说明
2400	文件上传失败	存储服务错误
2401	文件不存在	下载时未找到
2402	文件大小超限	超过配置限制
2403	文件类型不支持	格式不允许

---

3.8 管理后台相关错误（3000 ~ 3099）

code	message	说明
3000	管理员不存在	账号错误
3001	密码错误	后台登录失败
3002	角色不存在	角色未找到
3003	权限不足	无操作权限
3004	操作记录失败	后台日志写入失败

---

4. 响应示例

成功示例

{
  "code": 0,
  "message": "好友申请成功",
  "data": {
    "requestId": 12345
  }
}

失败示例

{
  "code": 2100,
  "message": "好友申请已存在",
  "data": null
}