Skip to content

更新用户资料 ​

1. 接口定位 ​

  • 接口名称: 更新用户资料
  • 所属域: chat/user
  • 业务目标: 普通用户仅可更新基础资料与偏好(昵称、头像等),管理员可修改完整用户资料

2. 请求定义 ​

  • Method: POST
  • Path: /user/update
  • Content-Type: 推荐 application/json(服务端按 JSON body 解析,当前未对该请求头做强校验)
  • operationID: 必填,请通过 Header operationID 传入
  • 鉴权: 必填,需要通过 Header token 传入有效的登录令牌
  • 幂等性: 非幂等(会修改用户数据库记录)

3. 请求参数 ​

Header 参数 ​

字段必填类型说明
operationID是string链路追踪 ID
token是string登录令牌

Body 参数 ​

字段必填类型说明
userID是string目标用户 ID
nickname否string用户昵称
faceURL否string头像 URL
gender否int32性别:0 未设置,1 男,2 女
phoneNumber条件必填string手机号;修改时必须与 areaCode 同时提供
areaCode条件必填string手机区号;修改时必须与 phoneNumber 同时提供
email否string邮箱
account否string账户名,只允许字母数字组合

字段约束 ​

  • phoneNumber 和 areaCode 必须同时提供或同时不提供。
  • areaCode 必须以 + 开头且为数字(如 +86);若不带 +,服务端会自动补齐。
  • phoneNumber 必须为纯数字。
  • account 只允许字母数字组合;修改时会检查重复注册。
  • email 修改时会检查格式有效性和重复注册。
  • 至少保留一个登录凭证(Account/Phone/Email),不能全部删除。
  • 普通用户只能修改自己的信息(UserID 必须等于令牌对应的操作者 ID)。
  • 普通用户仅允许修改以下字段:nickname、faceURL、gender、birth、allowAddFriend、allowBeep、allowVibration、globalRecvMsgOpt。
  • 普通用户禁止修改以下字段:level、account、phoneNumber、areaCode、email、registerType。

用户类型与权限 ​

用户类型权限
普通用户只能修改自己的基础资料与偏好字段,不能修改 level 和凭证字段
管理员可以修改任何用户的所有字段,包括 level、凭证字段、registerType

4. 响应结构 ​

通用响应包裹 ​

字段类型说明
errCodeint错误码,0 表示成功
errMsgstring错误简述
errDltstring错误详情
dataany业务数据

data 字段 ​

  • 本接口成功时返回空对象(无业务数据返回)。

5. 业务规则 ​

  • 修改前会校验用户是否存在,不存在则返回账户不存在错误。
  • 管理员修改 phoneNumber 时检查新手机号是否已被其他账户注册。
  • 管理员修改 areaCode 时检查格式(必须以 + 开头且后续为数字)。
  • 管理员修改 account 时检查是否已被其他账户注册。
  • 管理员修改 email 时检查格式和重复注册。
  • 修改后会同时更新本地数据库(chat)和 OpenIM SDK 系统,保持两端数据一致。
  • 普通用户尝试修改他人信息、level 或账号凭证字段时返回无权限错误。

6. 错误码与失败场景 ​

错误码场景典型报错
1001UserID 为空或格式错误user id is empty
1001phoneNumber 和 areaCode 不同时设置phone number and area code must be set at the same time
1001phoneNumber 为空但 areaCode 非空area code is provided but phone number is not
1001areaCode 格式错误(不以 + 开头)area code must start with +
1001areaCode 非数字area code must be number
1001phoneNumber 非数字phone number must be number
1001email 格式非法email must be right
1001account 非字母数字account must be alphanumeric
1001登录凭证全部被删除cannot delete all credentials
1004账户不存在user not found
20003手机号已被其他账户注册PhoneAlreadyRegister
20004账户已被其他账户注册AccountAlreadyRegister
20014邮箱已被其他账户注册EmailAlreadyRegister
1002普通用户尝试修改他人信息no permission
1002普通用户尝试修改 registerTyperegisterType can only be changed by admin
1002普通用户尝试修改 levellevel can only be changed by admin
1002普通用户尝试修改 account/phone/emailaccount credential fields can only be changed by admin

7. 示例 ​

fetch 请求示例 ​

javascript
fetch("http://localhost:10008/user/update", {
  method: "POST",
  headers: {
    operationID: "550e8400-e29b-41d4-a716-446655440001",
    token: "eyJhbGciOiJIUzI1NiIs...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    userID: "user123",
    nickname: "张三",
    faceURL: "https://example.com/avatar.jpg",
    gender: 1,
    areaCode: "+86",
    phoneNumber: "13800138000",
    email: "user@example.com",
  }),
})
  .then((res) => res.json())
  .then((data) => console.log(data));

请求示例(JSON) ​

json
{
  "userID": "user123",
  "nickname": "张三",
  "faceURL": "https://example.com/avatar.jpg",
  "gender": 1,
  "areaCode": "+86",
  "phoneNumber": "13800138000",
  "email": "user@example.com"
}

成功响应示例 ​

json
{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {}
}

失败响应示例(手机号已注册) ​

json
{
  "errCode": 20003,
  "errMsg": "PhoneAlreadyRegister",
  "errDlt": "phone number has been registered by another account"
}

失败响应示例(无权限) ​

json
{
  "errCode": 1002,
  "errMsg": "NoPermission",
  "errDlt": "normal user cannot update other user's information"
}

8. 时序流程 ​

  1. 验证令牌并提取操作者用户身份(普通用户或管理员)。
  2. 校验请求参数(userID、phoneNumber/areaCode 配对、格式等)。
  3. 查询目标用户是否存在。
  4. 检查权限:普通用户只能修改自己的基础资料与偏好字段,不能修改 level、账号凭证字段、registerType。
  5. 检查新凭证(phone/account/email)是否已被其他账户注册。
  6. 更新用户信息到本地数据库。
  7. 同步更新到 OpenIM SDK 系统。
  8. 返回成功响应。

9. 变更记录 ​

  • 2026-03-31: 首版发布,包含完整的字段定义、权限规则、错误场景和 fetch 示例。
  • 2026-10-07: 安全收敛:普通用户字段改为白名单,仅允许基础资料与偏好字段;level 与凭证字段改为仅管理员可修改。