用途
nestjs-personal-conventions 用于在编写或审查 NestJS 代码时套用该开发者的一套个人约定,适用对象包括服务、控制器、DTO,以及任何数据库或外部 HTTP API 集成。它是一层建立在通用 NestJS 最佳实践之上的补充规则:通用指南不强制仓储层、不要求 DTO 实现共享接口、也不规定外部 HTTP 集成的形态,本技能正是为填补这些空白。技能声明必须先用 nestjs-best-practices 子技能,覆盖通用架构、依赖注入与安全。
主要能力(约定清单)
- 数据库/ORM 访问:只能通过专用的 *.repository.ts 类进行,服务中绝不直接调用 ORM 客户端(Prisma/TypeORM 等)。
- 仓储方法命名:get* 在缺失时抛异常,find* 在缺失时返回 null/undefined。
- DTO 与共享契约:每个 DTO 类实现项目共享契约包/目录中的接口。
- 单一外部 API 出站调用:放在专用的 *.api.service.ts 中,async,返回 Promise<T>。
- 整套外部系统集成:建立自己的 <domain>-http/ 模块,使用 forRootAsync(),只注册一次,global: true。
- M2M 认证(无 OAuth):使用 Bearer 令牌守卫,与配置的密钥比较,注册为 APP_GUARD。
- 错误日志:使用 PinoLogger.error(err, message),错误在前、消息在后;该调用形态不使用 @nestjs/common 的 Logger。
- 分支日志:在每个有意义的分支/守卫/跳过路径上写 logger.debug(...)。
- 跨字段校验:不要在被 @IsOptional()/@ValidateIf() 守卫的属性上再叠加跨字段装饰器。
使用方式
- 仓储层(强制):服务不直接接触 ORM,而是注入 @Injectable() 的仓储类;仓储注入 ORM 客户端。示例中服务直接调用 prisma.user.findUnique 属于违规,正确做法是 UsersRepository 封装查询并在缺失时抛 NotFoundException,UsersService 仅做编排。例外:控制器在处理器只做零业务逻辑的透传时可直接注入仓储;一旦需要鉴权、映射或组合调用等逻辑,就要回到服务层。仓储的行映射输入应使用 ORM 自己生成的模型类型(如 import type { users } from '@prisma/client'),不要手写重复 schema 的结构接口。
- DTO 实现共享接口:DTO 字段不应脱离契约独立声明,示例中 CreateUserDto implements CreateUserRequest。非空断言 ! 仅在此处可接受,用于抑制 ValidationPipe 在运行时初始化字段带来的 TS 报错。
- 外部 HTTP 调用:单个调用放入专用 *.api.service.ts,使用 HttpService(基于 Axios)。有错误处理时,map 必须与 catchError 在同一管道内:firstValueFrom(this.http.post<T>(url, body).pipe(map(({ data }) => data), catchError(...)))。无错误处理时,await 后取 response.data 可以。两种形态不可混用:管道中已有 catchError 却又在 await 后取 response.data,会静默吞掉映射结果。
- 整套外部系统集成:建立 <domain>-http/ 模块,包含 .token.ts(注入令牌)、.types.ts(XxxHttpConfig/XxxHttpModuleAsyncOptions),静态 forRootAsync(options) 返回 DynamicModule(配置 provider + HttpService provider,在 useFactory 内通过 Axios 请求拦截器实现认证)。标记 global: true,在根应用模块中只调用一次 forRootAsync,其它模块仅 @Inject() 令牌。
- Cron 计划:始终使用 @nestjs/schedule 的 CronExpression 枚举(如 CronExpression.EVERY_5_MINUTES),不使用原始 cron 字符串。
- 日志:日志消息与和用户沟通的语言一致(该开发者默认为俄语)。错误日志使用 nestjs-pino 的 PinoLogger,通过 @InjectPinoLogger(ClassName.name) 在构造函数参数注入,调用 this.logger.error(err, '可读错误消息')。不要用格式化错误字符串作为尾参:@nestjs/common 的 Logger 会把尾串当作上下文并静默丢弃不匹配 %s 的额外参数。.warn/.debug 保持单字符串签名;PinoLogger 没有 .log(),级别为 trace/debug/info/warn/error/fatal,logger.log('text') 应改为 logger.info('text')。同时在每个有意义分支(守卫子句、if/else、条件提前返回、跳过路径)写 logger.debug,便于仅凭日志定位分支相关缺陷。
- M2M Bearer 守卫:用 bearer.replace('Bearer ', '') 提取令牌,与 config.getOrThrow<string>(...) 比较,注册为 APP_GUARD。
- AppModule DI 测试模式:在 beforeAll 设置 process.env,在 it() 体内动态 await import('./app.module'),确保模块在环境变量设置后加载;用 Test.createTestingModule({ imports: [AppModule] }).compile().resolves.toBeDefined() 验证真实 DI 图可解析,不用 overrideProvider 或 useMocker。
- 跨字段校验陷阱:@IsOptional() 和 @ValidateIf() 条件为假时会抑制该属性上的所有装饰器,而非仅自身检查;因此叠加跨字段装饰器会导致需要捕获的空值场景恰好不运行。修复方式是归一化而非门控:用 @Transform(({ value }) => value ?? '')(class-transformer 先于 class-validator 运行),使字段在校验时永不为 undefined。
适用场景
适用于 NestJS 项目中编写或审查服务、控制器、DTO、数据库访问与外部 API 集成代码;也适用于让 AI 代理在无技能加载时避免直接调用 ORM、无契约 DTO、临时服务内联外部调用等基线违规。
限制
资料未提供安装方式、版本兼容范围、许可证或性能数据;技能本身不替代 nestjs-best-practices,需先调用该子技能。文中部分具体规则(如默认日志语言为俄语)是该开发者的个人偏好,非通用 NestJS 要求。