JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 1032
  • Score
    100M100P100Q94197F
  • License ISC

nestjs boot core

Package Exports

  • @maxtan/nest-core
  • @maxtan/nest-core/decorators/auth.decorator.d.ts
  • @maxtan/nest-core/decorators/auth.decorator.js
  • @maxtan/nest-core/decorators/auth.decorator.js.map
  • @maxtan/nest-core/decorators/index.d.ts
  • @maxtan/nest-core/decorators/index.js
  • @maxtan/nest-core/decorators/index.js.map
  • @maxtan/nest-core/decorators/xml.decorator.d.ts
  • @maxtan/nest-core/decorators/xml.decorator.js
  • @maxtan/nest-core/decorators/xml.decorator.js.map
  • @maxtan/nest-core/filters/exceptions.filter.d.ts
  • @maxtan/nest-core/filters/exceptions.filter.js
  • @maxtan/nest-core/filters/exceptions.filter.js.map
  • @maxtan/nest-core/filters/index.d.ts
  • @maxtan/nest-core/filters/index.js
  • @maxtan/nest-core/filters/index.js.map
  • @maxtan/nest-core/index.d.ts
  • @maxtan/nest-core/index.js
  • @maxtan/nest-core/index.js.map
  • @maxtan/nest-core/modules/auth/auth.guard.d.ts
  • @maxtan/nest-core/modules/auth/auth.guard.js
  • @maxtan/nest-core/modules/auth/auth.guard.js.map
  • @maxtan/nest-core/modules/auth/auth.module.d.ts
  • @maxtan/nest-core/modules/auth/auth.module.js
  • @maxtan/nest-core/modules/auth/auth.module.js.map
  • @maxtan/nest-core/modules/auth/auth.strategy.d.ts
  • @maxtan/nest-core/modules/auth/auth.strategy.js
  • @maxtan/nest-core/modules/auth/auth.strategy.js.map
  • @maxtan/nest-core/modules/cache/cache.module.d.ts
  • @maxtan/nest-core/modules/cache/cache.module.js
  • @maxtan/nest-core/modules/cache/cache.module.js.map
  • @maxtan/nest-core/modules/cache/cache.service.d.ts
  • @maxtan/nest-core/modules/cache/cache.service.js
  • @maxtan/nest-core/modules/cache/cache.service.js.map
  • @maxtan/nest-core/modules/common/common.module.d.ts
  • @maxtan/nest-core/modules/common/common.module.js
  • @maxtan/nest-core/modules/common/common.module.js.map
  • @maxtan/nest-core/modules/common/common.service.d.ts
  • @maxtan/nest-core/modules/common/common.service.js
  • @maxtan/nest-core/modules/common/common.service.js.map
  • @maxtan/nest-core/modules/index.d.ts
  • @maxtan/nest-core/modules/index.js
  • @maxtan/nest-core/modules/index.js.map
  • @maxtan/nest-core/pipes/index.d.ts
  • @maxtan/nest-core/pipes/index.js
  • @maxtan/nest-core/pipes/index.js.map
  • @maxtan/nest-core/pipes/validation.pipe.d.ts
  • @maxtan/nest-core/pipes/validation.pipe.js
  • @maxtan/nest-core/pipes/validation.pipe.js.map
  • @maxtan/nest-core/tsconfig.tsbuildinfo
  • @maxtan/nest-core/types/auth.d.ts
  • @maxtan/nest-core/types/auth.js
  • @maxtan/nest-core/types/auth.js.map
  • @maxtan/nest-core/types/boot.d.ts
  • @maxtan/nest-core/types/boot.js
  • @maxtan/nest-core/types/boot.js.map
  • @maxtan/nest-core/types/index.d.ts
  • @maxtan/nest-core/types/index.js
  • @maxtan/nest-core/types/index.js.map
  • @maxtan/nest-core/types/logger.d.ts
  • @maxtan/nest-core/types/logger.js
  • @maxtan/nest-core/types/logger.js.map
  • @maxtan/nest-core/utils/common.d.ts
  • @maxtan/nest-core/utils/common.js
  • @maxtan/nest-core/utils/common.js.map
  • @maxtan/nest-core/utils/dto.d.ts
  • @maxtan/nest-core/utils/dto.js
  • @maxtan/nest-core/utils/dto.js.map
  • @maxtan/nest-core/utils/entries.d.ts
  • @maxtan/nest-core/utils/entries.js
  • @maxtan/nest-core/utils/entries.js.map
  • @maxtan/nest-core/utils/index.d.ts
  • @maxtan/nest-core/utils/index.js
  • @maxtan/nest-core/utils/index.js.map
  • @maxtan/nest-core/utils/logger.d.ts
  • @maxtan/nest-core/utils/logger.js
  • @maxtan/nest-core/utils/logger.js.map
  • @maxtan/nest-core/utils/snowflake.d.ts
  • @maxtan/nest-core/utils/snowflake.js
  • @maxtan/nest-core/utils/snowflake.js.map

Readme

@maxtan/nest-core

NestJS 增强工具包,提供了一系列开箱即用的模块和工具,帮助您快速构建高效、规范的 NestJS 应用。

功能特性

  • 日志系统: 基于 winston 的灵活日志系统,支持控制台、文件、阿里云 SLS 等多种输出方式
  • 缓存模块: 基于 Redis 的高性能缓存解决方案
  • 异常过滤器: 统一的异常处理机制,自动记录异常日志
  • 工具函数库: 常用辅助函数集合
  • 授权模块: 基于 JWT 的认证和授权系统,支持灵活配置
  • 雪花算法: 基于 @sapphire/snowflake 的唯一 ID 生成器

安装

npm install @maxtan/nest-core

# 或使用 pnpm
pnpm add @maxtan/nest-core

使用指南

日志模块

基础配置

import { createLogger } from '@maxtan/nest-core'

// 在应用启动时配置日志
createLogger() // 默认配置,日志输出到控制台和文件

使用日志工具

import { logger } from '@maxtan/nest-core'

// 使用默认logger记录不同级别的日志
logger.debug('调试信息')
logger.info('普通信息')
logger.warn('警告信息')
logger.error('错误信息')

自定义配置选项

import { createLogger } from '@maxtan/nest-core'

// 自定义配置
createLogger({
  useConsole: true, // 是否输出到控制台,默认 true
  maxDays: 30, // 日志文件保留天数,默认 7 天
  sls: {
    // 阿里云 SLS 配置(可选)
    accessKeyId: 'your-ak',
    accessKeySecret: 'your-sk',
    projectName: 'your-project',
    logStoreName: 'your-logstore',
    // 可选配置
    endpoint: 'cn-hangzhou.log.aliyuncs.com',
    topic: 'nest-boot',
    source: 'source',
    env: 'production'
  }
})

在 NestJS 应用中使用

import { NestFactory } from '@nestjs/core'
import { createLogger, WinstonLoggerService } from '@maxtan/nest-core'
import { AppModule } from './app.module'

async function bootstrap() {
  // 配置日志系统
  createLogger({
    useConsole: true,
    maxDays: 30,
    sls: {
      // SLS 配置...
    }
  })

  const app = await NestFactory.create(AppModule, {
    logger: new WinstonLoggerService() // 使用 Winston 作为 NestJS 日志服务
  })

  await app.listen(3000)
}
bootstrap()

缓存模块

import { CacheModule } from '@maxtan/nest-core'

@Module({
  imports: [
    CacheModule.register(
      {
        url: 'redis://localhost:6379'
        // 其他 Redis 客户端选项
      },
      true
    ) // 第二个参数表示是否全局注册模块
  ]
})
export class AppModule {}

在服务中使用:

import { Injectable } from '@nestjs/common'
import { CacheService } from '@maxtan/nest-core'

@Injectable()
export class YourService {
  constructor(private readonly cacheService: CacheService) {}

  async getData(key: string) {
    // 从缓存获取数据,cacheService.get 会自动解析 JSON
    const cached = await this.cacheService.get(key)
    if (cached) return cached // 直接返回解析后的数据

    // 获取数据并缓存
    const data = await this.fetchData()
    await this.cacheService.set(key, data, 3600) // 缓存1小时,如果是json 需要手动序列号
    return data
  }
}

授权模块

授权模块提供了基于 JWT 的认证和授权功能,可以轻松集成到您的 NestJS 应用中。

基本使用

import { AuthModule } from '@maxtan/nest-core'

@Module({
  imports: [
    AuthModule.register({
      secret: 'your-jwt-secret-key'
    })
  ]
})
export class AppModule {}

自定义配置

您可以自定义 JWT 签名选项:

import { AuthModule } from '@maxtan/nest-core'

@Module({
  imports: [
    AuthModule.register({
      secret: 'your-jwt-secret-key',
      signOptions: {
        expiresIn: '7d', // Token有效期7天
        issuer: 'your-app', // 发行方
        audience: 'your-users' // 目标用户
      }
    })
  ]
})
export class AppModule {}

保护路由

使用 AuthGuard 保护您的路由:

import { Controller, Get, UseGuards } from '@nestjs/common'
import { AuthGuard } from '@maxtan/nest-core'

@Controller('protected')
@UseGuards(AuthGuard)
export class ProtectedController {
  @Get()
  getProtectedData() {
    return { message: '这是受保护的数据' }
  }
}

全局应用 AuthGuard

您可以在应用级别全局应用 AuthGuard,这样所有路由默认都会受到保护:

import { Module } from '@nestjs/common'
import { APP_GUARD } from '@nestjs/core'
import { AuthGuard, AuthModule } from '@maxtan/nest-core'

@Module({
  imports: [
    AuthModule.register({
      secret: 'your-jwt-secret-key'
    })
    // 其他模块...
  ],
  providers: [
    {
      provide: APP_GUARD,
      useClass: AuthGuard
    }
  ]
})
export class AppModule {}

当启用全局 AuthGuard 后,可以使用 @AuthPublic() 装饰器来标记不需要认证的公开路由:

import { Controller, Get } from '@nestjs/common'
import { AuthPublic } from '@maxtan/nest-core'

@Controller('public')
export class PublicController {
  @Get()
  @AuthPublic()
  getPublicData() {
    return { message: '这是公开数据,无需认证' }
  }
}

获取当前用户

从请求中获取当前认证用户:

import { Controller, Get, Request, UseGuards } from '@nestjs/common'
import { AuthGuard } from '@maxtan/nest-core'

@Controller('profile')
@UseGuards(AuthGuard)
export class ProfileController {
  @Get()
  getProfile(@Request() req) {
    // req.user 包含了 JWT payload 中的信息
    return req.user
  }
}

使用 AuthDecorator 获取用户信息

更简洁的方式是使用 AuthDecorator 装饰器来直接获取认证用户信息:

import { Controller, Get, UseGuards } from '@nestjs/common'
import { AuthGuard, AuthDecorator } from '@maxtan/nest-core'

@Controller('profile')
@UseGuards(AuthGuard)
export class ProfileController {
  @Get()
  getProfile(@AuthDecorator() auth) {
    // auth 包含完整的认证用户信息
    return auth
  }

  @Get('username')
  getUsername(@AuthDecorator('username') username: string) {
    // 直接获取指定字段
    return { username }
  }

  @Get('data')
  getData(@AuthDecorator('data') data: any) {
    // 获取自定义数据字段
    return data
  }
}

AuthDecorator 可以接受一个可选的参数,用于指定要获取的 JWT payload 中的字段名。如果不提供参数,将返回整个认证对象。

雪花算法

雪花算法用于生成全局唯一的分布式 ID,基于 @sapphire/snowflake 实现:

基础使用

import { createSnowflake } from '@maxtan/nest-core'

// 创建默认雪花算法实例
const snowflake = createSnowflake()

// 生成唯一ID
const id = snowflake.generateSnowflakeId()
console.log(id) // 输出类似: "1234567890123456789"

自定义配置

import { createSnowflake } from '@maxtan/nest-core'

// 自定义工作节点ID和起始时间
const snowflake = createSnowflake({
  workerId: 1, // 工作节点ID
  epoch: new Date('2024-01-01T00:00:00.000Z') // 自定义起始时间
})

const id = snowflake.generateSnowflakeId()

支持的配置选项

interface SnowflakeOptions {
  workerId?: number // 工作节点ID,默认为1
  epoch?: number | string | Date // 起始时间,默认为2024-01-01 00:00:00 UTC
}

实例缓存

相同配置参数的实例会被自动缓存,避免重复创建:

// 这两个调用会返回同一个实例
const snowflake1 = createSnowflake({ workerId: 1 })
const snowflake2 = createSnowflake({ workerId: 1 })

console.log(snowflake1 === snowflake2) // true

异常过滤器

异常过滤器会捕获应用中的所有异常,并以统一的格式返回响应,同时记录详细的错误日志:

import { APP_FILTER } from '@nestjs/core'
import { AllExceptionsFilter } from '@maxtan/nest-core'

@Module({
  providers: [
    {
      provide: APP_FILTER,
      useClass: AllExceptionsFilter
    }
  ]
})
export class AppModule {}

配置参考

AllLoggerOptions

参数 类型 描述
useConsole boolean 是否输出到控制台,默认 true
maxDays number 日志文件保留天数,默认 7 天
sls SlsAppenderOptions 阿里云 SLS 配置(可选)

SlsAppenderOptions

参数 类型 描述
accessKeyId string 阿里云访问密钥ID
accessKeySecret string 阿里云访问密钥密码
endpoint string SLS服务端点,默认'cn-hangzhou.log.aliyuncs.com'
projectName string SLS项目名称
logStoreName string SLS日志存储名称
topic string 日志主题,默认'nest-boot'
source string 日志来源,默认'source'
env string 环境标识,默认'production'

AuthModuleOptions

参数 类型 描述
secret string 用于签名 JWT 的密钥
signOptions JwtSignOptions JWT 签名选项,包含过期时间、发行方等配置

SnowflakeOptions

参数 类型 描述
workerId number 工作节点ID,用于分布式环境中区分不同节点
epoch number | string | Date 起始时间,默认为2025-01-01 00:00:00 UTC

最佳实践

  1. 在启动时配置全局日志:使用 createLogger 函数在应用初始化时配置日志系统,确保所有日志都能被正确捕获。

  2. 使用不同的日志级别:根据信息的重要程度选择合适的日志级别,如调试信息使用 debug,错误信息使用 error 等。

  3. 区分环境配置

    • 开发环境:启用控制台日志,使用较低的日志级别(如 debug)
    • 生产环境:可关闭控制台日志,使用较高的日志级别(如 info 或 warn),启用 SLS 日志
  4. 合理设置日志保留期:根据存储空间和审计要求设置合适的 maxDays 值。

  5. 错误处理结合异常过滤器:使用 AllExceptionsFilter 统一处理异常,确保所有异常都被正确记录。

  6. 利用阿里云 SLS 进行日志分析:在生产环境中使用阿里云 SLS 进行集中式日志管理和分析,方便问题排查。

  7. 合理使用缓存:对频繁访问但不常变化的数据使用缓存,并设置合理的过期时间。

  8. 授权与认证安全

    • 使用足够长且复杂的 JWT 密钥
    • 设置合理的 Token 过期时间
    • 考虑在生产环境中使用非对称加密算法(RS256)
    • 实现 Token 刷新机制以提高安全性
  9. 雪花算法使用建议

    • 在分布式环境中为不同节点设置不同的 workerId
    • 确保各节点的系统时间同步,避免时钟回拨问题
    • 根据业务需求选择合适的起始时间(epoch)
    • 利用实例缓存特性,避免重复创建相同配置的实例

许可证

ISC