跨服务批量查询

返回 README

服务到服务（kungal / moyu / galgame_wiki 等）批量拉用户公开资料的端点。这些下游服务不在本地缓存 users.name / users.avatar，渲染时按 user_id 列表回拉。

鉴权：OAuth Client Basic Auth（Authorization: Basic base64(client_id:client_secret)），不是终端用户 JWT。任何已注册的 OAuth Client 都可以调用。

---

GET /users/batch

跨服务批量获取用户公开资料。

查询参数：

成功响应：

{
  "code": 0,
  "message": "成功",
  "data": {
    "users": [
      {
        "id": 1,
        "uuid": "9e00220a-8079-4e81-8e98-49e26ce23edc",
        "name": "kun",
        "avatar": "https://image.kungal.com/avatar/user_1/avatar.webp",
        "avatar_image_hash": "abc123...",
        "bio": "KUN IS THE CUTEST!",
        "status": 0,
        "roles": ["admin"],
        "created_at": "2023-10-29T10:41:34Z"
      }
    ],
    "not_found": [9999]
  }
}

错误响应：

注意：响应中不包含 email、moemoepoint 等隐私字段（created_at 是公开的注册时间，已包含——见上表）。 若调用方需要邮箱（如发邮件通知），应该走专门的 RPC 而不是渲染管线。

客户端实现：OAuth 这边不发布 SDK 代码。每个 consumer 自己实现一个薄客户端（30 行起步，按工作负载需要加 TTL 缓存 / singleflight / 分片）。完整的实现指南、可直接复用的 Go 参考代码、以及决定层级的判断标准，见 docs/migration/user/08-downstream-integration.md §4。

---

GET /users/search

按用户名搜索用户，case-insensitive 子串匹配。结果按相关度排序：精确匹配 > 前缀匹配 > 子串匹配，每一档内按字母升序。

适用场景：@提及自动补全、用户搜索框、管理后台用户检索。

鉴权：与 /users/batch 相同（OAuth Client Basic Auth）。

查询参数：

成功响应：

{
  "code": 0,
  "message": "成功",
  "data": {
    "users": [
      { "id": 2, "uuid": "...", "name": "鲲", "avatar": "...", "bio": "...", "status": 0, "roles": ["admin"], "created_at": "2023-10-29T10:41:34Z" },
      { "id": 79063, "uuid": "...", "name": "鲲1", ... },
      { "id": 38359, "uuid": "...", "name": "鲲114514", ... }
    ]
  }
}

错误响应：

注意：搜索结果不应缓存（query 空间无界、结果随注册/改名漂移，缓存命中率低还容易出脏数据）。前端要做实时自动补全，调用方在前端 debounce（推荐 200–300ms）即可。

---

完整错误码表见 04-tokens-and-errors.md。