获取用户完整信息

1. 接口定位

• 接口名称: 获取用户完整信息
• 所属域: client/user
• 业务目标: 批量查询指定用户的完整信息（包含所有可见字段），通常用于管理员或用户自己查看

2. 请求定义

• Method: POST
• Path: /user/find/full
• Content-Type: 推荐 application/json
• operationID: 必填，请通过 Header operationID 传入
• 鉴权: 必填，需要通过 Header token 传入有效的登录令牌
• 幂等性: 幂等（只读操作）

3. 请求参数

Header 参数

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

Body 参数

字段	必填	类型	说明
userIDs	是	[]string	目标用户 ID 列表

字段约束

• userIDs 不能为空，至少包含一个用户 ID。

4. 响应结构

通用响应包裹

字段	类型	说明
errCode	int	错误码，0 表示成功
errMsg	string	错误简述
errDlt	string	错误详情
data	any	业务数据

data 字段结构

字段	类型	说明
users	array	用户完整信息列表
userID	string	用户 ID
nickname	string	用户昵称
faceURL	string	头像 URL
account	string	账户名
phoneNumber	string	手机号
areaCode	string	手机区号
email	string	邮箱
gender	int32	性别
birth	string	出生日期
createTime	int64	创建时间（UNIX 时间戳）
appMerchantID	string	应用商户 ID
registerType	int32	注册类型

5. 业务规则

• 返回的是完整信息，包含所有用户字段（包括邮箱、手机号等私密信息）。
• 用户不存在时不返回该用户。
• 返回列表顺序与请求 userIDs 顺序一致；不存在的 ID 自动过滤。
• 本接口通常由管理员或用户自己使用（建议按需控制访问权限）。

6. 错误码与失败场景

错误码	场景	典型报错
1001	userIDs 为空或未提供	userIDs is empty

7. 示例

fetch 请求示例

fetch("http://localhost:10008/user/find/full", {
  method: "POST",
  headers: {
    operationID: "550e8400-e29b-41d4-a716-446655440001",
    token: "eyJhbGciOiJIUzI1NiIs...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    userIDs: ["user001", "user002"],
  }),
})
  .then((res) => res.json())
  .then((data) => console.log(data));

请求示例（JSON）

{
  "userIDs": ["user001", "user002"]
}

成功响应示例

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "users": [
      {
        "userID": "user001",
        "nickname": "老李",
        "account": "lili",
        "phoneNumber": "13800138000",
        "areaCode": "+86",
        "email": "lili@example.com",
        "gender": 1,
        "faceURL": "https://example.com/avatar1.jpg",
        "birth": "1990-01-15",
        "createTime": 1704067200,
        "appMerchantID": "merchant001",
        "registerType": 1
      }
    ]
  }
}

失败响应示例

{
  "errCode": 1001,
  "errMsg": "ArgsError",
  "errDlt": "userIDs is empty"
}

8. 时序流程

1. 验证令牌。
2. 校验 userIDs 不为空。
3. 查询用户属性表获取完整信息。
4. 返回查询结果。

9. 变更记录

• 2026-03-31: 首版发布，包含批量查询完整信息的定义和示例。