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 |
最佳实践
在启动时配置全局日志:使用
createLogger函数在应用初始化时配置日志系统,确保所有日志都能被正确捕获。使用不同的日志级别:根据信息的重要程度选择合适的日志级别,如调试信息使用 debug,错误信息使用 error 等。
区分环境配置:
- 开发环境:启用控制台日志,使用较低的日志级别(如 debug)
- 生产环境:可关闭控制台日志,使用较高的日志级别(如 info 或 warn),启用 SLS 日志
合理设置日志保留期:根据存储空间和审计要求设置合适的
maxDays值。错误处理结合异常过滤器:使用 AllExceptionsFilter 统一处理异常,确保所有异常都被正确记录。
利用阿里云 SLS 进行日志分析:在生产环境中使用阿里云 SLS 进行集中式日志管理和分析,方便问题排查。
合理使用缓存:对频繁访问但不常变化的数据使用缓存,并设置合理的过期时间。
授权与认证安全:
- 使用足够长且复杂的 JWT 密钥
- 设置合理的 Token 过期时间
- 考虑在生产环境中使用非对称加密算法(RS256)
- 实现 Token 刷新机制以提高安全性
雪花算法使用建议:
- 在分布式环境中为不同节点设置不同的 workerId
- 确保各节点的系统时间同步,避免时钟回拨问题
- 根据业务需求选择合适的起始时间(epoch)
- 利用实例缓存特性,避免重复创建相同配置的实例
许可证
ISC