Skip to content

搜索用户完整信息 ​

1. 接口定位 ​

  • 接口名称: 搜索用户完整信息
  • 所属域: chat/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性别过滤:0 全部,1 男,2 女
pagination否RequestPagination分页参数(pageNumber、showNumber)
normal否int32用户范围:0 所有用户,1 普通用户

分页参数结构 ​

字段类型说明
pageNumberint32页码(从 1 开始)
showNumberint32每页返回的记录数

字段约束 ​

  • keyword 不能为空。
  • keyword 会先执行去空白(trim),去空白后不能为空。
  • pagination.showNumber 取值范围为 1-50。
  • 若不指定分页参数,使用默认分页(pageNumber=1, showNumber=10)。

4. 响应结构 ​

通用响应包裹 ​

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

data 字段结构 ​

字段类型说明
totalint64查询结果总数
usersarray用户完整信息列表
userIDstring用户 ID
nicknamestring昵称
accountstring账户
emailstring邮箱
phoneNumberstring手机号
areaCodestring区号
faceURLstring头像 URL
genderint32性别
createTimeint64创建时间

5. 业务规则 ​

  • 普通用户(userType=1)仅支持精确匹配(userID/account/phoneNumber/email/nickname 全等匹配),不支持模糊搜索。
  • 管理员用户(userType=2)保留既有关键字搜索能力。
  • 支持按单个性别过滤:0 不过滤,1 男,2 女。
  • 返回完整用户信息(包含邮箱、手机号等)。
  • 普通用户调用时,响应中的 phoneNumber 为脱敏值;管理员用户调用时保持原值。
  • 支持分页查询,默认每页 10 条记录。
  • normal 字段控制搜索范围:
    • 0:所有用户(包含被封禁账号);
    • 1:普通用户(排除被封禁账号)。
  • 当前实现中,仅管理员用户会按 normal 执行范围控制;普通用户调用该接口时,normal 不改变其“仅精确匹配”约束。

6. 错误码与失败场景 ​

错误码场景典型报错
1001keyword 为空参数验证失败
1001分页参数错误参数验证失败
1001showNumber 超限(>50)参数验证失败

7. 示例 ​

fetch 请求示例 ​

javascript
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: "13800138000",
    genders: 1,
    pagination: {
      pageNumber: 1,
      showNumber: 20,
    },
    normal: 0,
  }),
})
  .then((res) => res.json())
  .then((data) => console.log(data));

请求示例(JSON) ​

json
{
  "keyword": "13800138000",
  "genders": 1,
  "pagination": {
    "pageNumber": 1,
    "showNumber": 20
  }
}

成功响应示例 ​

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

失败响应示例 ​

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

8. 时序流程 ​

  1. 验证令牌。
  2. 校验 keyword 参数(去空白后不可为空)与分页参数(showNumber 不超过 50)。
  3. 根据调用者类型选择搜索策略:普通用户走精确匹配,管理员走既有搜索。
  4. 应用分页参数,返回指定范围的结果。
  5. 对普通用户响应做手机号脱敏后返回。

9. 变更记录 ​

  • 2026-03-31: 首版发布,包含用户完整信息搜索的定义和示例。
  • 2026-04-07: 补充 normal 取值(0/1)与行为说明,并修正 genders 为单值 int32。
  • 2026-10-07: 安全收敛:禁止空 keyword、限制 showNumber<=50、普通用户仅精确匹配、普通用户响应手机号脱敏。