@maxtan/nest-core

NestJS 增强工具包，提供了一系列开箱即用的模块、装饰器、管道、过滤器和工具函数，帮助您快速构建高效、规范的 NestJS + Fastify 应用。

功能特性

核心模块

• 🔐 授权模块 — 基于 JWT + Passport 的认证授权，支持 Bearer Token、自定义 Header 提取、AES 加密 Payload
• 📋 日志系统 — 基于 Winston 的日志方案，支持控制台、文件轮转、阿里云 SLS；LoggerModule DI 化
• 💾 缓存模块 — 基于 Redis (ioredis) 的缓存服务，支持健康检查、自动重连、批量操作和对象序列化
• 🗄️ Prisma 模块 — 声明式中间件（软删除 / 审计）、多数据源隔离、Prisma 运行时模型元数据自动发现、PrismaRepository 泛型 CRUD、多 Client 支持
• 💚 健康检查 — 自动检测 Prisma / Redis、自定义指示器、K8s 探针就绪

请求处理

• ✅ 验证管道 — 基于 Zod v4 的请求验证，20+ 预处理器对齐 Prisma，Schema 即类型
• 📦 文件上传 — Fastify Multipart 集成，支持 Zod Schema 验证表单字段、MIME 白名单、扩展名黑名单
• 🔧 XML 解析 — 高性能 XML 解析装饰器，基于 fast-xml-parser，解析器实例缓存

其中查询场景推荐优先使用查询专用 helper，例如 zQueryInt、zQueryId、zQueryEnumInt、zQueryEnumStr：

• 创建、更新、命令式写入：使用 zEnumInt / zEnumStr / zId
• 列表、筛选、统计查询：使用 zQueryInt / zQueryId / zQueryEnumInt / zQueryEnumStr
• 查询 helper 会把 null、空串、空白串视为“未传”，但仍会对其它非法值报错

字符串字段推荐按语义选 helper：

• 空串应视为未传：zStr
• 空串应保留并写入库：zStrEmpty，常见最大长度可直接用 zStrEmpty.max(n)
• 空串应视为清空为 null：zStrNull / zVarCharNull
• 字符串数组逐项 trim：zStrArr

快速区分：

• 查询参数用 zQuery*，因为空串通常表示“不筛选”
• 写入参数用 zStr / zStrEmpty / zStrNull，区别只在空串语义
• 对齐 Prisma @db.VarChar(n) 时，用 zVarChar 或 zVarCharNull

响应与异常

• 🌐 响应转换 — 统一响应格式，自动 Date→时间戳转换，201→200 归一化
• ⚠️ 异常过滤器 — 全局异常处理，Fastify 错误映射，雪花 ID 链路追踪
• 📝 操作日志 — 基于拦截器的全链路操作记录，自动脱敏、异步写入

开发工具

• 🔄 事务装饰器 — @PrismaTransactional 声明式事务，自动嵌套复用、多数据源事务隔离
• 🌱 环境变量校验 — validateEnv + zPort / zBoolEnv，启动即校验
• 🛠️ 工具函数 — 雪花 ID、AES-256-GCM、LRU 缓存、Prisma 查询构建器、对象清理
• 📐 Prisma→Zod — generateZodSuggestions 从 Prisma 运行时模型元数据自动生成 DTO 建议代码

环境要求

• Node.js >= 22.0.0
• NestJS >= 11.0.0
• Fastify >= 5.0.0
• Prisma >= 7.0.0

安装

pnpm add @maxtan/nest-core

对等依赖

| 包名 | 版本 | 是否必选 | | ------------------ | ------- | -------- | | @nestjs/common | ^11.0.0 | ✅ 必选 | | @nestjs/core | ^11.0.0 | ✅ 必选 | | reflect-metadata | ^0.2.0 | ✅ 必选 | | fastify | ^5.0.0 | 可选 | | @prisma/client | ^7.0.0 | 可选 |

快速开始

// main.ts
import { NestFactory } from '@nestjs/core';
import { FastifyAdapter, NestFastifyApplication } from '@nestjs/platform-fastify';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create<NestFastifyApplication>(
    AppModule,
    new FastifyAdapter(),
  );
  await app.listen(3000, '0.0.0.0');
}
bootstrap();

// app.module.ts
import { Module } from '@nestjs/common';
import {
  AuthModule, AuthGuard, ZodPipe, AllExceptionsFilter,
  PrismaModule, CacheModule, OperationModule,
  MultipartModule, TransformModule, getCurrentUserId
} from '@maxtan/nest-core';
import { APP_GUARD, APP_PIPE, APP_FILTER } from '@nestjs/core';
import { PrismaService } from './prisma/prisma.service';

@Module({
  imports: [
    AuthModule.register({ secret: process.env.JWT_SECRET! }),
    PrismaModule.forRoot({
      service: PrismaService,
      middlewares: {
        softDelete: { enabled: true, models: 'auto' }, // 自动发现含 deletedAt 的模型
        audit: { enabled: true, getUserId: getCurrentUserId }
      }
    }),
    CacheModule.register({ host: 'localhost', port: 6379 }),
    OperationModule.forRoot(),
    MultipartModule.forRoot(),
    TransformModule.forRoot(),
  ],
  providers: [
    { provide: APP_GUARD, useClass: AuthGuard },
    { provide: APP_PIPE, useClass: ZodPipe },
    { provide: APP_FILTER, useClass: AllExceptionsFilter },
  ],
})
export class AppModule {}

更多详情请参阅 快速开始文档。

验证管道与查询 helper 的详细说明请参阅 验证文档。

📚 文档

完整文档请访问 线上文档站，主要内容包括：

• 入门 — 快速开始、环境变量校验
• 核心功能 — 验证管道、日志系统、缓存模块、授权模块、操作日志
• 数据库 — Prisma 模块、事务管理、健康检查
• 请求与响应 — 文件上传、响应转换、异常过滤器、XML 解析
• 进阶 — 工具函数、最佳实践、FAQ、AI 编码规则

🤖 AI 编码规则

项目提供了面向 AI 编码助手（Copilot / Cursor / Cline）的 AI 编码规则文档，将其放入业务项目根目录（如 .cursorrules、.github/copilot-instructions.md），即可让 AI 按照框架规范自动生成高质量业务代码。

许可证

ISC