Lucia Auth 项目中 DrizzlePostgreSQLAdapter 的 UserId 类型推断问题解析

问题背景

在 Lucia Auth 项目的 PostgreSQL 适配器使用过程中，开发者遇到了一个关于 UserId 类型推断的问题。当尝试将 UserId 类型从默认的字符串(string)更改为数字(number)时，TypeScript 类型检查会报错，导致适配器无法正确识别数字类型的 UserId。

技术细节分析

Lucia Auth 是一个现代化的身份验证解决方案，它提供了灵活的适配器系统来支持不同的数据库后端。在 PostgreSQL 适配器中，默认情况下 UserId 被假定为字符串类型。然而，在实际开发中，许多开发者倾向于使用自增的数字 ID 作为用户标识符。

问题的核心在于适配器内部的类型定义。在早期版本中，PostgreSQLSessionTable 和 PostgreSQLUserTable 的类型定义中，userId 字段的数据类型被硬编码为字符串(string)，这限制了开发者使用数字类型作为 UserId 的能力。

解决方案演进

1. 原始问题表现：

   • 当开发者将 UserId 类型声明为 number 时
   • 同时在数据库模式中使用 integer 或 bigint 类型定义 userId 字段
   • TypeScript 会报告类型不匹配的错误

2. 临时解决方案：

   • 开发者可以通过 @ts-expect-error 注释暂时绕过类型检查
   • 或者回退到使用字符串类型的 userId

3. 官方修复方案：

   • 在较新版本的适配器中，Lucia 团队已经更新了类型定义
   • 现在适配器能够正确推断数字类型的 UserId
   • 支持包括 integer、bigint 等多种数字类型

最佳实践建议

1. 版本选择：

   • 确保使用 @lucia-auth/adapter-drizzle 1.0.4 或更高版本
   • 这些版本已经包含了完整的数字类型支持

2. 类型定义：

   • 在 Lucia 模块声明中明确指定 UserId 类型
   • 保持数据库模式定义与类型声明一致

3. 数据库模式设计：

   • 对于数字 ID，推荐使用 bigserial 类型
   • 设置适当的 mode 参数（'number' 或 'bigint'）

技术实现示例

以下是一个使用数字类型 UserId 的完整示例：

// 数据库模式定义
export const userTable = pgTable('auth_user', {
  id: bigserial('id', { mode: 'number' }).primaryKey(),
  email: varchar('email', { length: 320 }).notNull().unique()
});

export const sessionTable = pgTable('auth_session', {
  id: varchar('id', { length: 128 }).primaryKey(),
  userId: bigint('user_id', { mode: 'number' })
    .notNull()
    .references(() => userTable.id)
});

// Lucia 类型声明
declare module 'lucia' {
  interface Register {
    Lucia: typeof auth;
    UserId: number;
    DatabaseUserAttributes: {
      email: string;
    };
  }
}

总结

Lucia Auth 项目已经解决了 PostgreSQL 适配器中数字类型 UserId 的推断问题。开发者现在可以自由选择使用字符串或数字作为用户标识符，而不会遇到类型检查错误。这一改进增强了框架的灵活性，使其能够更好地适应不同的数据库设计和业务需求。

对于正在使用或考虑使用 Lucia Auth 的开发者，建议及时更新到最新版本以获得最佳的类型支持和开发体验。同时，在设计数据库模式时，应根据实际需求合理选择 ID 类型，并在类型声明中保持一致性。