koatty_config

Configuration loader for Koatty

Usage

运行环境配置

koatty_config 可以自动识别当前运行环境，并且根据运行环境自动加载相应配置（如果存在）:

const env = process.env.KOATTY_ENV || process.env.NODE_ENV || "";

如果 env = production, koatty_config 会自动加载以 _pro.ts 或 _production.ts 后缀的配置文件。

例如:

// 自动加载 config_dev.ts 或 config_development.ts
NODE_ENV=dev ts-node "test/test.ts"

命令行参数

koatty_config 可以自动识别命令行参数，并且自动填充到相应的配置项:

// 自动填充config.cc.dd.ee的值
NODE_ENV=dev ts-node "test/test.ts" --config.cc.dd.ee=77

占位符变量替换

koatty_config 可以自动将配置文件中使用 ${} 占位符标识的配置项替换为process.env内的同名项的值:

config.ts

export default {
    ...
    ff: "${ff_value}"
    ...
}

// 自动填充ff的值
NODE_ENV=dev ff_value=999 ts-node "test/test.ts"

配置验证

koatty_config 支持通过 Validation Schema 对配置进行验证，确保配置的正确性。

基本用法

import { LoadConfigs, ValidationSchema } from 'koatty_config';

// 定义验证规则
const schema: ValidationSchema = {
  port: {
    type: 'number',
    required: true,
    min: 1,
    max: 65535
  },
  host: {
    type: 'string',
    required: true
  },
  environment: {
    type: 'string',
    enum: ['development', 'production', 'test']
  }
};

// 加载并验证配置
const config = LoadConfigs(['./config'], process.cwd(), undefined, ['*.test.ts'], schema);

Validation Schema

Validation Schema 定义了配置项的验证规则：

interface ValidationSchema {
  [key: string]: {
    type?: 'string' | 'number' | 'boolean' | 'object' | 'array';
    required?: boolean;
    default?: any;
    validator?: (value: any) => boolean | string;
    min?: number;
    max?: number;
    enum?: any[];
  };
}

验证规则

| 规则 | 类型 | 说明 | |------|------|------| | type | string | 验证值的类型：'string', 'number', 'boolean', 'object', 'array' | | required | boolean | 是否必需字段 | | default | any | 默认值（当字段未定义时使用） | | validator | function | 自定义验证函数，返回 true 表示通过，返回 string 表示错误信息 | | min | number | 最小值（仅对 number 类型有效） | | max | number | 最大值（仅对 number 类型有效） | | enum | array | 枚举值，值必须在数组中 |

示例

1. 类型验证

const schema = {
  port: {
    type: 'number',
    required: true
  },
  debug: {
    type: 'boolean'
  }
};

2. 范围验证

const schema = {
  port: {
    type: 'number',
    min: 1024,
    max: 65535
  },
  timeout: {
    type: 'number',
    min: 0
  }
};

3. 枚举验证

const schema = {
  environment: {
    type: 'string',
    enum: ['development', 'production', 'test']
  }
};

4. 自定义验证

const schema = {
  email: {
    type: 'string',
    validator: (value: string) => {
      return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value) || 'Invalid email format';
    }
  }
};

5. 默认值

const schema = {
  port: {
    type: 'number',
    default: 3000
  },
  host: {
    type: 'string',
    default: 'localhost'
  }
};

// 即使配置文件中没有这些字段，也会使用默认值

6. 嵌套对象验证

const schema = {
  database: {
    type: 'object',
    required: true
  }
};

// 验证 database 是否存在且为对象类型

错误处理

当配置验证失败时，会抛出详细的错误信息：

try {
  const config = LoadConfigs(['./config'], process.cwd(), undefined, undefined, schema);
} catch (error) {
  console.error(error.message);
  // 输出:
  // Configuration validation failed:
  //   - port: Property 'port' is required
  //   - environment: Property 'environment' must be one of: development, production, test
}

导出的验证函数

你也可以单独使用验证函数：

import { validateConfig, ValidationSchema, ValidationResult, applyDefaults } from 'koatty_config';

// 验证配置
const result: ValidationResult = validateConfig(config, schema);

if (!result.valid) {
  console.error('Validation failed:');
  result.errors.forEach(error => {
    console.error(`  - ${error.path}: ${error.message}`);
  });
}

// 应用默认值
const configWithDefaults = applyDefaults(config, schema);