brkpt-auth

每种方案都有代价

托管服务

云端的黑盒。定制能力有限，且存在供应商锁定。

自托管库

本地的黑盒。厚重的抽象让定制变得困难。

样板项目

完整的源代码，但带有强烈的架构主张，往往需要大量返工。

自行开发

完全的控制权，但每个新项目都要从同样的起点重新开始。

为什么选择 brkpt-auth

brkpt-auth 不是样板项目，也不是库。它围绕你自己实现的接口构建，而不是一个直接可用、带有预设主张的默认实现。

透明

完整源代码直接安装进你的项目。没有编译产物，没有隐藏行为。

可组合

功能相互独立。只添加你需要的部分。

非侵入

不对你的数据库结构、用户模型或 JWT payload 做任何假设。

可移植

业务逻辑与适配器相互独立。迁移到新项目只需替换适配器。

原生适配 NestJS

从一开始就围绕 NestJS 的模块、依赖注入、守卫、装饰器和 provider 构建。

六边形架构

服务持有业务逻辑，端口（port）定义契约，适配器（adapter）完全由你掌控。没有层层嵌套的 domain/infrastructure 分层需要翻找。

工作原理

服务依赖一个抽象接口，也就是端口（port），你通过实现它来编写适配器（adapter）。这是你的基础设施唯一接触认证逻辑的地方。除了 core 之外，各个功能之间互不依赖，所以你只需添加需要的部分，不必触碰其余代码。BrkptAuthModule 只需在 AppModule 中注册一次，就会自动完成所有装配，不需要你手动注册和拼接 provider。

这正是它不会像样板项目那样变得臃肿的原因。你能获得清晰的定制入口，同时保持容易上手。

brkpt-cli 会将源代码安装进你的项目。你实现适配器并在 features.ts 中列出它们；大多数适配器方法只是简单的字段映射或对你现有代码的直接调用。

如何使用

每个功能都遵循同样的接入流程：添加功能、实现它的适配器、注册它。

1. 添加功能

   使用 brkpt-cli 将功能源代码添加到你的项目中。

   添加 credentials

   brkpt auth add credentials

2. 实现适配器

   将功能端口连接到你已有的应用代码。大多数适配器方法只是简单的字段映射或直接的服务调用。

   credentials.adapter.ts

   @Injectable()
   export class CredentialsAdapter implements CredentialsPort<User> {
     constructor(private readonly prisma: PrismaService) {}
   
     findUserByDto(dto: SignInDto | SignUpDto): Promise<User | null> {
       return this.prisma.user.findUnique({ where: { email: dto.email } });
     }
   
     validatePassword(user: User, dto: SignInDto): Promise<boolean> {
       return bcrypt.compare(dto.password, user.password);
     }
   
     async createUser(dto: SignUpDto): Promise<User> {
       const password = await bcrypt.hash(dto.password, 10);
       return this.prisma.user.create({
         data: { email: dto.email, password },
       });
     }
   
     extractUserIdFromUser(user: User): number {
       return user.id;
     }
   }

3. 注册功能

   brkpt-cli 会为你更新 features.ts。实现适配器后，将它传给生成的功能列表中对应的功能。

   src/brkpt-auth/features.ts

   export const features: FeatureConfig[] = [
     coreFeature(CoreAdapter),
     credentialsFeature(CredentialsAdapter),
   ];

就是这样。一旦 BrkptAuthModule 在你的 AppModule 中注册完成，添加的功能就会成为同一套 NestJS 认证流程的一部分。

根据功能的不同，你可能仍需要完成一些常规的项目配置，比如依赖、环境变量、DTO 或基础设施模块。

可用功能

brkpt-auth 将常见的认证能力组织成相互独立的功能。从 core 开始，再按需添加你的应用所需要的功能。

基础

• core（核心）

登录方式

• credentials（账号密码）
• oauth（第三方登录）
• otp（一次性密码）
• magic-link（魔术链接）

会话管理

• session（会话）
• blacklist（黑名单）

账户安全

• verify-email（邮箱验证）
• change-password（修改密码）
• reset-password（重置密码）

事件处理

• audit（审计）

brkpt-auth 适合谁

brkpt-auth 为需要能够自主掌控、调整并长期演进的认证代码的 NestJS 应用而生。

MVP 开发者

快速搭建一套可用的认证基础，再随着产品演进逐步添加会话管理、OAuth、OTP、审计等功能。

已有的 NestJS 应用

已经拥有自己的用户模型、数据库、服务和基础设施的项目。

长期维护的产品

希望拥有可检查、可维护、可长期调整的认证代码的团队。

可组合的认证体系

需要从简单起步、逐步添加认证能力、且不必重写已有功能的应用。

多项目开发者

希望在多个 NestJS 项目间复用认证逻辑，同时让每个项目自由使用各自数据库、用户模型和基础设施的开发者。

注重架构的团队

希望在认证逻辑、应用基础设施和项目特定实现之间保持清晰边界的团队。