OauthModel

OAuth 提供商与账号关联模型，用于注册第三方登录提供商、查找关联账号以及管理平台到用户的映射。

与大多数模型不同，OauthModel 继承自 Service，通过 ctx.oauth 访问而非使用静态方法。

---

类型导出

OauthMap

interface OauthMap {
    platform: string;  // OAuth 平台名称（如 'github'、'google'、'mail'）
    id: string;        // 来自提供商的 openId
    uid: number;       // 目标 Hydro 用户 ID
}

OAuthProvider

interface OAuthProvider {
    text: string;              // 显示标签
    name: string;              // 提供商标识符
    icon?: string;             // 图标 URL 或标识符
    hidden?: boolean;          // 若为 true，不在登录界面显示
    get: (this: Handler) => Promise<void>;                         // 发起 OAuth 流程
    callback: (this: Handler, args: Record<string, any>) => Promise<OAuthUserResponse>;  // 处理 OAuth 回调
    canRegister?: boolean;     // 该提供商是否允许新用户注册
    lockUsername?: boolean;    // 关联后用户名是否锁定
}

OAuthUserResponse

interface OAuthUserResponse {
    _id: string;                           // 外部用户 ID
    email: string;                         // 用户邮箱
    avatar?: string;                       // 头像 URL
    bio?: string;                          // 用户简介
    uname?: string[];                      // 用户名候选列表
    viewLang?: string;                     // 首选语言
    set?: Record<string, any>;             // 需设置到用户文档的字段
    setInDomain?: Record<string, any>;     // 需设置到域用户文档的字段
}

---

方法

查找

get(platform: string, id: string): Promise<number | null>

查找与平台+openId 对关联的 Hydro 用户 ID。返回关联的 uid，若无映射则返回 null。

参数	类型	默认值	说明
platform	string	—	OAuth 平台名称（如 'github'）
id	string	—	来自提供商的 openId
返回值	Promise<number | null>		关联的用户 UID，或 null

账号关联

set(platform: string, id: string, uid: number): Promise<number>

创建或更新 OAuth 账号映射。使用 upsert 操作。返回 upsert 文档的 uid。

参数	类型	默认值	说明
platform	string	—	OAuth 平台名称
id	string	—	来自提供商的 openId
uid	number	—	Hydro 用户 UID
返回值	Promise<number>		关联的用户 UID

unbind(platform: string, uid: number): Promise<void>

按平台和用户 ID 移除 OAuth 账号映射。

参数	类型	默认值	说明
platform	string	—	OAuth 平台名称
uid	number	—	Hydro 用户 UID
返回值	Promise<void>

list(uid: number): Promise<OauthMap[]>

列出用户的所有 OAuth 账号映射。

参数	类型	默认值	说明
uid	number	—	Hydro 用户 UID
返回值	Promise<OauthMap[]>

提供商注册

provide(name: string, provider: OAuthProvider): Promise<void>

注册一个 OAuth 提供商。若同名提供商已存在则抛出异常。当服务上下文销毁时，提供商会自动清理。使用 ctx.effect() 注册并附带清理逻辑——上下文销毁时自动移除提供商。

参数	类型	默认值	说明
name	string	—	提供商标识符
provider	OAuthProvider	—	提供商配置对象
返回值	Promise<void>

// 注册自定义 OAuth 提供商
ctx.oauth.provide('github', {
    text: 'GitHub',
    name: 'github',
    icon: 'github',
    async get() { /* 重定向到 GitHub OAuth */ },
    async callback(args) {
        // 用 code 换取用户信息
        return { _id: '...', email: '...', uname: ['...'] };
    },
});

// 查找关联用户
const uid = await ctx.oauth.get('github', openId);

// 关联账号
await ctx.oauth.set('github', openId, uid);

// 列出用户的关联账号
const links = await ctx.oauth.list(uid);

// 解除关联
await ctx.oauth.unbind('github', uid);

---

属性

属性	类型	说明
coll	Collection<OauthMap>	MongoDB oauth 集合
providers	Record<string, OAuthProvider>	已注册的 OAuth 提供商，按名称索引

---

备注

• 索引：在启动时通过 [Context.init] 创建——{ platform: 1, id: 1 }（唯一索引，每个 platform+openId 仅一条映射）、{ uid: 1, platform: 1 }（列出用户的关联账号）。