获取用户公开资料

1. 接口定位

• 接口名称: 获取用户公开资料
• 所属域: client/user
• 业务目标: 批量查询指定用户的公开信息（如昵称、头像、性别等），用于陌生人查看用户资料

2. 请求定义

• Method: POST
• Path: /user/find/public
• Content-Type: 推荐 application/json（服务端按 JSON body 解析，当前未对该请求头做强校验）
• operationID: 必填，请通过 Header operationID 传入
• 鉴权: 必填，需要通过 Header token 传入有效的登录令牌
• 幂等性: 幂等（只读操作）

3. 请求参数

Header 参数

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

Body 参数

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

字段约束

• userIDs 不能为空，至少包含一个用户 ID。
• 单次查询建议不超过 100 个用户 ID。

4. 响应结构

通用响应包裹

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

data 字段结构

字段	类型	说明
users	array	用户公开信息列表
userID	string	用户 ID
nickname	string	用户昵称
faceURL	string	头像 URL
gender	int32	性别：0 未设置，1 男，2 女
createTime	int64	创建时间（UNIX 时间戳）
appMerchantID	string	应用商户 ID

5. 业务规则

• 返回的是公开信息，不包含隐私字段（邮箱、手机号等）。
• 用户不存在时不返回该用户，但不报错。
• 返回列表顺序与请求 userIDs 顺序一致；不存在的 ID 自动过滤。
• 本接口需要认证用户调用。

6. 错误码与失败场景

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

7. 示例

fetch 请求示例

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

请求示例（JSON）

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

成功响应示例

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "users": [
      {
        "userID": "user001",
        "nickname": "老李",
        "faceURL": "https://example.com/avatar1.jpg",
        "gender": 1,
        "createTime": 1704067200,
        "appMerchantID": "merchant001"
      },
      {
        "userID": "user002",
        "nickname": "小王",
        "faceURL": "https://example.com/avatar2.jpg",
        "gender": 2,
        "createTime": 1704153600,
        "appMerchantID": "merchant001"
      }
    ]
  }
}

失败响应示例

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

8. 时序流程

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

9. 变更记录

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