快速开始

架构概览

HTTP Request
  │
  ├─ AuthGuard          ← JWT 认证
  ├─ ZodPipe            ← 参数验证
  ├─ TransformInterceptor ← 响应转换
  └─ AllExceptionsFilter  ← 异常过滤器
        │
 ┌──────┴──────────────────────────────┐
 │            功能模块                   │
 │                                      │
 │  AuthModule         (JWT 认证授权)    │
 │  CacheModule        (Redis 缓存)     │
 │  PrismaModule       (数据库 ORM)     │
 │  OperationModule    (操作日志)        │
 │  LoggerModule       (Winston 日志)   │
 │  HealthModule       (健康检查)        │
 │  MultipartModule    (文件上传)        │
 └──────────────────────────────────────┘
        │
 ┌──────┴──────────────────────────────┐
 │            工具层                     │
 │                                      │
 │  Zod 预设    zVarChar / zEnumInt     │
 │  加密工具    AES-256-GCM             │
 │  雪花 ID     分布式唯一 ID            │
 │  环境校验    validateEnv             │
 └──────────────────────────────────────┘
        │
 ┌──────┴──────────────────────────────┐
 │          基础设施                     │
 │  MySQL / PostgreSQL    Redis         │
 └──────────────────────────────────────┘

安装

npm install @maxtan/nest-core
# 或
pnpm add @maxtan/nest-core

对等依赖

包名	版本	是否必选
@nestjs/common	^11.0.0	必选
@nestjs/core	^11.0.0	必选
reflect-metadata	^0.2.0	必选
fastify	^5.0.0	可选（文件上传、XML 解析）
@prisma/client	^7.0.0	可选（数据库）

最小化示例

main.ts

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

async function bootstrap() {
  // 1. 初始化日志
  createLogger({ useConsole: true })

  // 2. 创建 Fastify 应用
  const app = await NestFactory.create<NestFastifyApplication>(
    AppModule,
    new FastifyAdapter(),
    { logger: new WinstonLoggerService() }
  )

  await app.listen(3000)
}
bootstrap()

app.module.ts

import { Module } from '@nestjs/common'
import { APP_FILTER, APP_PIPE } from '@nestjs/core'
import {
  AuthModule,
  CacheModule,
  OperationModule,
  TransformModule,
  AllExceptionsFilter,
  ZodPipe
} from '@maxtan/nest-core'

@Module({
  imports: [
    // JWT 认证
    AuthModule.register({ secret: process.env.JWT_SECRET! }),

    // Redis 缓存
    CacheModule.forRoot({ host: 'localhost', port: 6379 }),

    // 操作日志
    OperationModule.forRoot(),

    // 统一响应格式
    TransformModule.forRoot()
  ],
  providers: [
    // 全局异常过滤器
    { provide: APP_FILTER, useClass: AllExceptionsFilter },

    // 全局 Zod 验证管道（可选，也可在参数级使用）
    { provide: APP_PIPE, useClass: ZodPipe }
  ]
})
export class AppModule {}

按需引入

所有模块都是可选的，按需导入即可：

// 只用日志 + 异常过滤器
import { createLogger, WinstonLoggerService, AllExceptionsFilter } from '@maxtan/nest-core'

// 只用 Zod 验证
import { Zod, ZodPipe, zPage } from '@maxtan/nest-core'

// 只用工具函数
import { encryptAES, decryptAES, generateSnowflakeId, formatDate } from '@maxtan/nest-core'

模块注册顺序

模块注册有推荐顺序，确保依赖关系正确：

@Module({
  imports: [
    // 1️⃣ 日志（最先初始化，其他模块依赖日志输出）
    LoggerModule.forRoot({ useConsole: true }),

    // 2️⃣ 缓存（认证模块可能依赖 Redis 存 Token 黑名单）
    CacheModule.forRoot({ host: 'localhost', port: 6379 }),

    // 3️⃣ 数据库（业务模块的核心依赖）
    PrismaModule.forRoot({ service: PrismaService }),

    // 4️⃣ 认证（依赖数据库查询用户，内置 ClsModule 请求上下文）
    AuthModule.register({ secret: process.env.JWT_SECRET! }),

    // 5️⃣ 操作日志（依赖数据库写入日志）
    OperationModule.forRoot(),

    // 6️⃣ 响应转换（拦截器，不依赖其他模块）
    TransformModule.forRoot(),

    // 7️⃣ 健康检查（聚合上方已注册的 Prisma / Redis）
    HealthModule.forRoot(),
  ],
  providers: [
    { provide: APP_FILTER, useClass: AllExceptionsFilter },
    { provide: APP_PIPE, useClass: ZodPipe },
  ],
})
export class AppModule {}

关键规则

• LoggerModule 应最先注册，确保后续模块初始化时的日志正常输出
• PrismaModule 必须在 AuthModule 之前注册（认证需要查库验证用户）
• HealthModule 应最后注册，以便自动检测已注册的 Prisma 和 Redis 服务
• 全局 Filter 和 Pipe 通过 providers 注册，顺序不敏感

下一步

• 环境变量校验 — 启动时配置校验（推荐首先阅读）
• 验证管道 (Zod) — 请求参数验证
• 日志系统 — Winston 日志配置
• 授权模块 — JWT 认证授权
• Prisma 模块 — 数据库集成
• 最佳实践 — 分层开发全链路规范