NestJS配置校验Joi学习笔记

# 预期：DB_PORT 应为数字 3306
DB_PORT=abc_def   #  传入了字符串，数据库连接必然报错

pnpm install joi

pnpm install joi@17

import * as Joi from 'joi';

ConfigModule.forRoot({
  validationSchema: Joi.object({
    // 在这里定义校验规则...
  }),
})

import * as Joi from 'joi';

Joi.object({
  // 数字类型
  DB_PORT: Joi.number(),

  // 字符串类型
  NODE_ENV: Joi.string(),

  DB_HOST: Joi.string(),
  DB_URL: Joi.string(),
})

Joi.object({
  DB_PORT: Joi.number().default(3306),
  NODE_ENV: Joi.string().default('development'),
})

# .env 中未定义 DB_PORT
# → 自动使用默认值 3306

Joi.object({
  NODE_ENV: Joi.string().valid('development', 'production'),
  // 或使用 allow（别名）
  // NODE_ENV: Joi.string().allow('development', 'production'),
})

NODE_ENV=staging
#  报错："NODE_ENV" must be one of [development, production]

Joi.object({
  // IP 地址格式
  DB_HOST: Joi.string().ip(),

  // 域名格式
  DB_URL: Joi.string().domain(),

  // 邮箱格式
  EMAIL: Joi.string().email(),

  // URI 格式
  API_URL: Joi.string().uri(),

  // 日期格式
  CREATE_DATE: Joi.string().date(),
})

Joi.object({
  DB_PORT: Joi.number().min(1024).max(65535),
})

Joi.object({
  DB_PASSWORD: Joi.string().min(8).max(32),
  API_KEY: Joi.string().length(64),
})

Joi.object({
  // 自定义正则：只允许字母和数字
  USERNAME: Joi.string().pattern(/^[a-zA-Z0-9]+$/),

  // API Key 格式：32位十六进制
  API_KEY: Joi.string().pattern(/^[0-9a-f]{32}$/),
})

Joi.object({
  DB_PORT: Joi.number().custom((value, helpers) => {
    if (value < 1024 || value > 65535) {
      return helpers.error('any.invalid');
    }
    return value;
  }),
})

DB_HOST=127.0.0.1
DB_PORT=3306
DB_USERNAME=root
DB_URL=https://3w.mock.com

DB=mysql_dev

DB=mysql_pro

// app.module.ts
import { ConfigModule } from '@nestjs/config';
import { Module } from '@nestjs/common';
import * as Joi from 'joi';

@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true,
      envFilePath: ['.env.development', '.env'],
      validationSchema: Joi.object({
        // 数据库类型
        DB: Joi.string().valid('mysql_dev', 'mysql_pro'),

        // 数据库端口：数字类型，默认 3306
        DB_PORT: Joi.number().default(3306).valid(3306, 3307, 3308),

        // 运行环境
        NODE_ENV: Joi.string()
          .valid('development', 'production')
          .default('development'),

        // 数据库地址：IP 格式
        DB_HOST: Joi.string().ip(),

        // 数据库 URL：域名格式
        DB_URL: Joi.string().domain(),
      }),
    }),
  ],
})
export class AppModule {}

# .env.development
DB=mysql_dev
DB_PORT=9999        #  不在 valid 范围 [3306, 3307, 3308] 内
DB_HOST=127.0.0.1AA #  不是合法 IP 地址

Error: "DB_PORT" must be one of [3306, 3307, 3308]
Error: "DB_HOST" must be a valid ip address

//  load 加载的配置可能绕过 validationSchema 校验
ConfigModule.forRoot({
  envFilePath: '.env.development',
  load: [
    () => dotenv.config({ path: '.env' }),  // load 加载的 .env 不被校验！
  ],
  validationSchema: Joi.object({
    DB_HOST: Joi.string().ip(),
  }),
})

//  使用数组形式，两个文件都受 validationSchema 校验
ConfigModule.forRoot({
  envFilePath: [
    '.env.development',  // 优先级高：环境专属配置
    '.env',              // 优先级低：公共共享配置
  ],
  validationSchema: Joi.object({
    DB_HOST: Joi.string().ip(),
  }),
})

.env.development  >  .env
（高优先级）          （低优先级）

pnpm install @nestjs/config joi cross-env -D

DB_HOST=127.0.0.1
DB_PORT=3306
DB_USERNAME=root
DB_PASSWORD=123456
DB_URL=https://api.mock.com

DB=mysql_dev

DB=mysql_pro

// app.module.ts
import { ConfigModule } from '@nestjs/config';
import { Module } from '@nestjs/common';
import * as Joi from 'joi';
import { UserModule } from './user/user.module';

@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true,
      // 数组形式：.env.development 优先级高于 .env
      envFilePath: [`.env.${process.env.NODE_ENV || 'development'}`, '.env'],
      // Joi 校验规则
      validationSchema: Joi.object({
        // 数据库类型：限定可选值
        DB: Joi.string().valid('mysql_dev', 'mysql_pro'),

        // 数据库端口：数字 + 默认值 + 枚举范围
        DB_PORT: Joi.number().default(3306).valid(3306, 3307, 3308),

        // 运行环境：字符串 + 枚举 + 默认值
        NODE_ENV: Joi.string()
          .valid('development', 'production')
          .default('development'),

        // 数据库地址：IP 格式
        DB_HOST: Joi.string().ip(),

        // 数据库 URL：域名格式
        DB_URL: Joi.string().domain(),
      }),
    }),
    UserModule,
  ],
})
export class AppModule {}

// user.controller.ts
import { Controller, Get } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import { ConfigEnum } from '../enum/config.enum';

@Controller('user')
export class UserController {
  constructor(private configService: ConfigService) {}

  @Get()
  getUsers() {
    return {
      db: this.configService.get(ConfigEnum.DB),
      host: this.configService.get(ConfigEnum.DB_HOST),
      port: this.configService.get<number>(ConfigEnum.DB_PORT),
      url: this.configService.get(ConfigEnum.DB_URL),
    };
  }
}

{
  "scripts": {
    "start:dev": "cross-env NODE_ENV=development nest start --watch",
    "start:pro": "cross-env NODE_ENV=production node dist/main"
  }
}

#  正常启动
pnpm start:dev

#  在 .env 中将 DB_HOST 改为 127.0.0.1AAA 后启动
# Error: "DB_HOST" must be a valid ip address

#  在 .env 中将 DB_PORT 改为 9999 后启动
# Error: "DB_PORT" must be one of [3306, 3307, 3308]

#  将 NODE_ENV 改为 staging 后启动
# Error: "NODE_ENV" must be one of [development, production]

配置校验三件套：
1. 类型校验（number / string）→ 防止类型错误
2. 格式校验（ip / domain / email）→ 防止格式错误
3. 枚举/范围校验（valid / min / max）→ 防止值越界