搜索用户完整信息

1. 接口定位

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

2. 请求定义

• Method: POST
• Path: /user/search/full
• 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	分页参数（pageNumber、showNumber）
normal	否	int32	用户范围：0 表示所有用户

分页参数结构

字段	类型	说明
pageNumber	int32	页码（从 1 开始）
showNumber	int32	每页返回的记录数

字段约束

• keyword 不能为空。
• 若不指定分页参数，使用默认分页（pageNumber=1, showNumber=10）。

4. 响应结构

通用响应包裹

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

data 字段结构

字段	类型	说明
total	int64	查询结果总数
users	array	用户完整信息列表
userID	string	用户 ID
nickname	string	昵称
account	string	账户
email	string	邮箱
phoneNumber	string	手机号
areaCode	string	区号
faceURL	string	头像 URL
gender	int32	性别
createTime	int64	创建时间

5. 业务规则

• 根据关键字在用户名、昵称等字段进行模糊搜索。
• 支持性别过滤，可同时指定多个性别。
• 返回完整用户信息（包含邮箱、手机号等）。
• 支持分页查询，默认每页 10 条记录。
• normal 字段控制搜索范围（0 表示所有用户）。

6. 错误码与失败场景

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

7. 示例

fetch 请求示例

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

请求示例（JSON）

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

成功响应示例

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "total": 5,
    "users": [
      {
        "userID": "user001",
        "nickname": "老李",
        "account": "lili",
        "email": "lili@example.com",
        "phoneNumber": "13800138000",
        "areaCode": "+86",
        "faceURL": "https://example.com/avatar1.jpg",
        "gender": 1,
        "createTime": 1704067200
      }
    ]
  }
}

失败响应示例

{
  "errCode": 1001,
  "errMsg": "ArgsError",
  "errDlt": "search parameter validation failed"
}

8. 时序流程

1. 验证令牌。
2. 校验 keyword 参数不为空。
3. 根据关键字和过滤条件在数据库中搜索。
4. 应用分页参数，返回指定范围的结果。
5. 返回搜索结果和总数。

9. 变更记录

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