[ PROMPT_NODE_23758 ]
配置管理
[ SKILL_DOCUMENTATION ]
# 配置管理 - UnifiedConfig 模式
后端微服务配置管理的完整指南。
## 目录
- [UnifiedConfig 概述](#unifiedconfig-概述)
- [严禁直接使用 process.env](#严禁直接使用-processenv)
- [配置结构](#配置结构)
- [环境特定配置](#环境特定配置)
- [密钥管理](#密钥管理)
- [迁移指南](#迁移指南)
---
## UnifiedConfig 概述
### 为什么使用 UnifiedConfig？
**直接使用 process.env 的问题：**
- ❌ 无类型安全
- ❌ 无验证
- ❌ 难以测试
- ❌ 分散在代码各处
- ❌ 无默认值
- ❌ 拼写错误导致运行时异常
**unifiedConfig 的优势：**
- ✅ 类型安全配置
- ✅ 单一事实来源
- ✅ 启动时验证
- ✅ 易于使用 Mock 进行测试
- ✅ 清晰的结构
- ✅ 自动回退到环境变量
---
## 严禁直接使用 process.env
### 规则
typescript
// ❌ 严禁这样做
const timeout = parseInt(process.env.TIMEOUT_MS || '5000');
const dbHost = process.env.DB_HOST || 'localhost';
// ✅ 始终这样做
import { config } from './config/unifiedConfig';
const timeout = config.timeouts.default;
const dbHost = config.database.host;
### 为什么这很重要
**问题示例：**
typescript
// 环境变量名拼写错误
const host = process.env.DB_HSOT; // undefined! 不会报错！
// 类型安全
const port = process.env.PORT; // string! 需要 parseInt
const timeout = parseInt(process.env.TIMEOUT); // 如果未设置则为 NaN!
**使用 unifiedConfig：**
typescript
const port = config.server.port; // number, 有保障
const timeout = config.timeouts.default; // number, 带有回退值
---
## 配置结构
### UnifiedConfig 接口
typescript
export interface UnifiedConfig {
database: {
host: string;
port: number;
username: string;
password: string;
database: string;
};
server: {
port: number;
sessionSecret: string;
};
tokens: {
jwt: string;
inactivity: string;
internal: string;
};
keycloak: {
realm: string;
client: string;
baseUrl: string;
secret: string;
};
aws: {
region: string;
emailQueueUrl: string;
accessKeyId: string;
secretAccessKey: string;
};
sentry: {
dsn: string;
environment: string;
tracesSampleRate: number;
};
// ... 更多配置
粤公网安备44030002003366号