nestjs-authnpaas

nestjs-authnpaas 是一个轻量级的 NestJS 模块，用于处理身份验证检查。它提供了一个全局守卫，以确保用户在访问端点之前已经登录。

目录

• 功能
• 安装
• 快速开始
• 装饰器
  • @NeedLogin()
• 服务
  • AuthNPaasService
• 工作原理

功能

• 身份验证检查: 确保用户在访问受保护端点之前已经登录。
• 登录重定向: 自动将未经身份验证的用户重定向到登录 URL。
• 用户 ID 转换: 支持妙搭用户 ID 与飞书用户 ID 互转。

安装

npm install @lark-apaas/nestjs-authnpaas
# 或者
yarn add @lark-apaas/nestjs-authnpaas

快速开始

在您的根模块 app.module.ts 中导入并配置 AuthNPaasModule。

import { Module } from '@nestjs/common';
import { AuthNPaasModule } from '@lark-apaas/nestjs-authnpaas';

@Module({
  imports: [
    AuthNPaasModule.forRoot(),
  ],
  controllers: [/* ... */],
  providers: [/* ... */],
})
export class AppModule {}

装饰器

@NeedLogin()

使用 @NeedLogin() 装饰器在特定端点上强制执行身份验证。

控制器级别

import { Controller, Get } from '@nestjs/common';
import { NeedLogin } from '@lark-apaas/nestjs-authnpaas';

@Controller('dashboard')
@NeedLogin() // 此控制器中的所有路由都需要登录
export class DashboardController {
  @Get()
  getDashboard() {
    return '您的个人仪表板';
  }
}

方法级别

import { Controller, Get } from '@nestjs/common';
import { NeedLogin } from '@lark-apaas/nestjs-authnpaas';

@Controller('api')
export class ApiController {
  @Get('public-data')
  getPublicData() {
    // 此端点不需要身份验证
    return '一些公共数据';
  }

  @Get('private-data')
  @NeedLogin() // 此端点需要身份验证
  getPrivateData() {
    return '一些秘密数据';
  }
}

服务

AuthNPaasService

AuthNPaasService 提供妙搭用户 ID 与飞书用户 ID 的转换能力。模块注册后即可通过依赖注入使用。

import { Injectable } from '@nestjs/common';
import { AuthNPaasService } from '@lark-apaas/nestjs-authnpaas';

@Injectable()
export class MyService {
  constructor(private readonly authn: AuthNPaasService) {}

  async example() {
    // 获取当前登录用户的飞书 user_id
    const larkUserId = await this.authn.getCurrentUserLarkUserId();
    // => 'xxx' | null

    // 批量转换妙搭 userId → 飞书 user_id（最多 100 个）
    const larkUserIds = await this.authn.getBatchLarkUserIds(['uid1', 'uid2']);
    // => ['lark_id_1', 'lark_id_2']  顺序与输入对应，找不到的为 null
  }
}

getCurrentUserLarkUserId

从请求上下文获取当前妙搭 userId，调用平台接口转换为飞书 user_id。

• 返回值: Promise<string | null> — 飞书 user_id，未登录或转换失败返回 null

getBatchLarkUserIds

批量将妙搭 userId 转换为飞书 user_id。

• 参数: userIds: string[] — 妙搭用户 ID 列表，最多 100 个
• 返回值: Promise<(string | null)[]> — 飞书 user_id 数组，与输入顺序一一对应，转换失败的项为 null
• 异常: 当 userIds 超过 100 个时抛出错误

工作原理

AuthNPaasGuard

此模块将 AuthNPaasGuard 注册为全局守卫。在每个传入的请求上，守卫会执行以下步骤：

1. 检查 @NeedLogin(): 它首先检查端点是否需要登录。
2. 确认身份验证状态: 如果端点需要登录，守卫会确认 request.userContext 对象上的 userId 是否存在。
3. 如果未通过身份验证则重定向: 如果端点标有 @NeedLogin() 且缺少 userId，它会将用户重定向到 request.userContext 上的 loginUrl。