获取用户列表

v1.1.23+

User API 允许获取你当前租户下的用户列表。

版本要求

此功能从 SDK v1.1.23 版本开始支持。

API 签名

client.api.user.getList(): Promise<User[]>

⚠️ 注意：client.api.user.getList() 不支持分页。默认情况下此方法会一次性返回当前租户下匹配条件的用户，但为防止一次性返回过多数据，SDK 会最多返回 1000 条记录（即"全量"但有上限）。

返回类型示例

（实际类型以 SDK 源码为准）

type User = {
  code: string; // 用户唯一编码
  userName: string; // 系统用户名
  nickName?: string | null;
  mobile: string;
  email?: string | null;
  avatar?: string | null;
};

快速开始

下面示例演示在项目中如何安全地调用 user.getList()：

const users = await client.api.user.getList();
console.log(`返回 ${users.length} 个用户`);

// 注意：SDK 在内部已经对请求异常做了处理。在出现异常时，client.api.user.getList() 会返回空数组（[]）作为降级结果。

使用示例

只获取昵称和用户名（快速映射）

const users = await client.api.user.getList();
const mapped = users
  .filter((u) => !!u.nickName)
  .map((u) => ({ username: u.userName, nickName: u.nickName }));

console.log(mapped);

获取单个用户（先获取全量数据再过滤）

下面示例演示先通过 client.api.user.getList() 获取当前租户的用户全量（最多 1000 条），然后在客户端用 filter 取出单个用户（按 username 或其他字段匹配）。注意这是内存级别过滤，适合小量数据或下拉场景；若用户量大请改用服务端分页/过滤接口。

// 先获取列表（SDK 内部会做短期缓存与异常降级）
const users = await client.api.user.getList();

// 使用 filter 获取匹配的用户，然后取第一个（返回 null 表示未找到）
const matches = users.filter((u) => u.userName === "alice");
// 或者按用户编码筛选： users.filter(u => u.code === "user-001")

const user = matches.length ? matches[0] : null;
console.log(user);

注意事项与最佳实践

• 返回结果的范围：该方法默认会返回当前租户下所有的用户，但会对返回条数做上限限制（最多 1000 条）。因此建议仅在小规模列表或一次性加载场景（如下拉选择器）使用。当租户用户量较大或需完整遍历所有用户时，请改用 filter()、服务端分页接口或分批加载策略以避免性能和内存问题。
• 错误处理：SDK 在内部会捕获请求异常并在出错时返回空数组（[]）作为安全降级结果。调用方可以直接以返回的空数组作为降级策略；若需区分错误原因、上报或做特定重试逻辑。
• 缓存行为：短期缓存列表以提升性能。由于用户信息调整频率较低，SDK 在内部默认对列表数据进行短期缓存，缓存时长为 30 秒，以在兼顾时效性的同时提升性能。

常见问题

返回的数据是否包含敏感信息？

返回字段为常规展示字段（用户名、昵称、头像等），不会包含密码或安全凭证。

相关文档

• 快速开始

---

最后更新：2025-12-01