搜索用户公开信息

1. 接口定位

• 接口名称: 搜索用户公开信息
• 所属域: client/user
• 业务目标: 根据关键字搜索用户公开信息，支持分页和性别过滤

2. 请求定义

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

3. 请求参数

Header 参数

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

Body 参数

字段	必填	类型	说明
keyword	是	string	搜索关键字（用户名、昵称等）
genders	否	[]int32	性别过滤：1 男，2 女
pagination	否	RequestPagination	分页参数
normal	否	int32	用户范围：0 表示所有用户

字段约束

• keyword 不能为空。

4. 响应结构

通用响应包裹

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

data 字段结构

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

5. 业务规则

• 只返回公开信息（昵称、头像、性别等），不暴露邮箱、手机号等私密字段。
• 支持性别过滤和分页查询。
• 用于所有认证用户搜索其他用户。

6. 错误码与失败场景

错误码	场景	典型报错
1001	keyword 为空	参数验证失败

7. 示例

fetch 请求示例

fetch("http://localhost:10008/user/search/public", {
  method: "POST",
  headers: {
    operationID: "550e8400-e29b-41d4-a716-446655440001",
    token: "eyJhbGciOiJIUzI1NiIs...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    keyword: "王",
    genders: [2],
    pagination: {
      pageNumber: 1,
      showNumber: 20,
    },
  }),
})
  .then((res) => res.json())
  .then((data) => console.log(data));

请求示例（JSON）

{
  "keyword": "王",
  "genders": [2],
  "pagination": {
    "pageNumber": 1,
    "showNumber": 20
  }
}

成功响应示例

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "total": 3,
    "users": [
      {
        "userID": "user002",
        "nickname": "小王",
        "gender": 2,
        "faceURL": "https://example.com/avatar2.jpg",
        "createTime": 1704153600
      }
    ]
  }
}

失败响应示例

{
  "errCode": 1001,
  "errMsg": "ArgsError",
  "errDlt": "keyword cannot be empty"
}

8. 时序流程

1. 验证令牌。
2. 校验 keyword 参数。
3. 搜索用户属性表中的公开字段。
4. 应用分页参数。
5. 返回搜索结果。

9. 变更记录

• 2026-03-31: 首版发布，包含用户公开信息搜索的定义和示例。