308 lines
6.7 KiB
Markdown
308 lines
6.7 KiB
Markdown
# 🔧 TYAPI 配置系统文档
|
||
|
||
## 📋 目录
|
||
|
||
- [配置策略概述](#配置策略概述)
|
||
- [文件结构](#文件结构)
|
||
- [配置加载流程](#配置加载流程)
|
||
- [环境配置](#环境配置)
|
||
- [配置验证](#配置验证)
|
||
- [使用指南](#使用指南)
|
||
- [最佳实践](#最佳实践)
|
||
- [故障排除](#故障排除)
|
||
|
||
## 🎯 配置策略概述
|
||
|
||
TYAPI 采用**分层配置策略**，支持多环境部署和灵活的配置管理：
|
||
|
||
```
|
||
📁 配置层次结构
|
||
├── 📄 config.yaml (基础配置模板)
|
||
└── 📁 configs/
|
||
├── 📄 env.development.yaml (开发环境覆盖)
|
||
├── 📄 env.production.yaml (生产环境覆盖)
|
||
└── 📄 env.testing.yaml (测试环境覆盖)
|
||
```
|
||
|
||
### 配置加载优先级（从高到低）
|
||
|
||
1. **环境变量** - 用于敏感信息和运行时覆盖
|
||
2. **环境特定配置文件** - `configs/env.{environment}.yaml`
|
||
3. **基础配置文件** - `config.yaml`
|
||
4. **默认值** - 代码中的默认配置
|
||
|
||
## 📁 文件结构
|
||
|
||
### 基础配置文件
|
||
|
||
- **位置**: `config.yaml`
|
||
- **作用**: 包含所有默认配置值，作为配置模板
|
||
- **特点**:
|
||
- 包含完整的配置结构
|
||
- 提供合理的默认值
|
||
- 作为所有环境的基础配置
|
||
|
||
### 环境配置文件
|
||
|
||
- **位置**: `configs/env.{environment}.yaml`
|
||
- **支持的环境**: `development`, `production`, `testing`
|
||
- **特点**:
|
||
- 只包含需要覆盖的配置项
|
||
- 继承基础配置的所有默认值
|
||
- 支持嵌套配置的深度合并
|
||
|
||
## 🔄 配置加载流程
|
||
|
||
### 1. 环境检测
|
||
|
||
```go
|
||
// 环境变量检测优先级
|
||
CONFIG_ENV > ENV > APP_ENV > 默认值(development)
|
||
```
|
||
|
||
### 2. 配置文件加载顺序
|
||
|
||
1. 读取基础配置文件 `config.yaml`
|
||
2. 查找环境配置文件 `configs/env.{environment}.yaml`
|
||
3. 合并环境配置到基础配置
|
||
4. 应用环境变量覆盖
|
||
5. 验证配置完整性
|
||
6. 输出配置摘要
|
||
|
||
### 3. 配置合并策略
|
||
|
||
- **递归合并**: 支持嵌套配置的深度合并
|
||
- **覆盖机制**: 环境配置覆盖基础配置
|
||
- **环境变量**: 最终覆盖任何配置项
|
||
|
||
## 🌍 环境配置
|
||
|
||
### 开发环境 (development)
|
||
|
||
```yaml
|
||
# configs/env.development.yaml
|
||
app:
|
||
env: development
|
||
|
||
database:
|
||
password: Pg9mX4kL8nW2rT5y
|
||
|
||
jwt:
|
||
secret: JwT8xR4mN9vP2sL7kH3oB6yC1zA5uF0qE9tW
|
||
```
|
||
|
||
### 生产环境 (production)
|
||
|
||
```yaml
|
||
# configs/env.production.yaml
|
||
app:
|
||
env: production
|
||
|
||
server:
|
||
mode: release
|
||
|
||
database:
|
||
sslmode: require
|
||
|
||
logger:
|
||
level: warn
|
||
format: json
|
||
```
|
||
|
||
### 测试环境 (testing)
|
||
|
||
```yaml
|
||
# configs/env.testing.yaml
|
||
app:
|
||
env: testing
|
||
|
||
server:
|
||
mode: test
|
||
|
||
database:
|
||
password: test_password
|
||
name: tyapi_test
|
||
|
||
redis:
|
||
db: 15
|
||
|
||
logger:
|
||
level: debug
|
||
|
||
jwt:
|
||
secret: test-jwt-secret-key-for-testing-only
|
||
```
|
||
|
||
## ✅ 配置验证
|
||
|
||
### 验证项目
|
||
|
||
- **数据库配置**: 主机、用户名、数据库名不能为空
|
||
- **JWT 配置**: 生产环境必须设置安全的 JWT 密钥
|
||
- **服务器配置**: 超时时间必须大于 0
|
||
- **连接池配置**: 最大空闲连接数不能大于最大连接数
|
||
|
||
### 验证失败处理
|
||
|
||
- 配置验证失败时，应用无法启动
|
||
- 提供详细的中文错误信息
|
||
- 帮助快速定位配置问题
|
||
|
||
## 📖 使用指南
|
||
|
||
### 1. 启动应用
|
||
|
||
```bash
|
||
# 使用默认环境 (development)
|
||
go run cmd/api/main.go
|
||
|
||
# 指定环境
|
||
CONFIG_ENV=production go run cmd/api/main.go
|
||
ENV=testing go run cmd/api/main.go
|
||
APP_ENV=production go run cmd/api/main.go
|
||
```
|
||
|
||
### 2. 添加新的配置项
|
||
|
||
1. 在 `config.yaml` 中添加默认值
|
||
2. 在 `internal/config/config.go` 中定义对应的结构体字段
|
||
3. 在环境配置文件中覆盖特定值（如需要）
|
||
|
||
### 3. 环境变量覆盖
|
||
|
||
```bash
|
||
# 覆盖数据库密码
|
||
export DATABASE_PASSWORD="your-secure-password"
|
||
|
||
# 覆盖JWT密钥
|
||
export JWT_SECRET="your-super-secret-jwt-key"
|
||
|
||
# 覆盖服务器端口
|
||
export SERVER_PORT="9090"
|
||
```
|
||
|
||
### 4. 添加新的环境
|
||
|
||
1. 创建 `configs/env.{new_env}.yaml` 文件
|
||
2. 在 `getEnvironment()` 函数中添加环境验证
|
||
3. 配置相应的环境特定设置
|
||
|
||
## 🏆 最佳实践
|
||
|
||
### 1. 配置文件管理
|
||
|
||
- ✅ **基础配置**: 在 `config.yaml` 中设置合理的默认值
|
||
- ✅ **环境配置**: 只在环境文件中覆盖必要的配置项
|
||
- ✅ **敏感信息**: 通过环境变量注入，不要写在配置文件中
|
||
- ✅ **版本控制**: 将配置文件纳入版本控制，但排除敏感信息
|
||
|
||
### 2. 环境变量使用
|
||
|
||
- ✅ **生产环境**: 所有敏感信息都通过环境变量注入
|
||
- ✅ **开发环境**: 可以使用配置文件中的默认值
|
||
- ✅ **测试环境**: 使用独立的测试配置
|
||
|
||
### 3. 配置验证
|
||
|
||
- ✅ **启动验证**: 应用启动时验证所有必要配置
|
||
- ✅ **类型检查**: 确保配置值的类型正确
|
||
- ✅ **逻辑验证**: 验证配置项之间的逻辑关系
|
||
|
||
### 4. 日志和监控
|
||
|
||
- ✅ **配置摘要**: 启动时输出关键配置信息
|
||
- ✅ **环境标识**: 明确显示当前运行环境
|
||
- ✅ **配置变更**: 记录重要的配置变更
|
||
|
||
## 🔧 故障排除
|
||
|
||
### 常见问题
|
||
|
||
#### 1. 配置文件未找到
|
||
|
||
```
|
||
❌ 错误: 未找到 config.yaml 文件，请确保配置文件存在
|
||
```
|
||
|
||
**解决方案**: 确保项目根目录下存在 `config.yaml` 文件
|
||
|
||
#### 2. 环境配置文件未找到
|
||
|
||
```
|
||
ℹ️ 未找到环境配置文件 configs/env.development.yaml，将使用基础配置
|
||
```
|
||
|
||
**解决方案**:
|
||
|
||
- 检查环境变量设置是否正确
|
||
- 确认 `configs/env.{environment}.yaml` 文件存在
|
||
|
||
#### 3. 配置验证失败
|
||
|
||
```
|
||
❌ 错误: 配置验证失败: 数据库主机地址不能为空
|
||
```
|
||
|
||
**解决方案**:
|
||
|
||
- 检查 `config.yaml` 中的数据库配置
|
||
- 确认环境配置文件中的覆盖值正确
|
||
|
||
#### 4. JWT 密钥安全问题
|
||
|
||
```
|
||
❌ 错误: 生产环境必须设置安全的JWT密钥
|
||
```
|
||
|
||
**解决方案**:
|
||
|
||
- 通过环境变量设置安全的 JWT 密钥
|
||
- 不要使用默认的测试密钥
|
||
|
||
### 调试技巧
|
||
|
||
#### 1. 查看配置摘要
|
||
|
||
启动时查看配置摘要输出，确认：
|
||
|
||
- 当前运行环境
|
||
- 使用的配置文件
|
||
- 关键配置值
|
||
|
||
#### 2. 环境变量检查
|
||
|
||
```bash
|
||
# 检查环境变量
|
||
echo $CONFIG_ENV
|
||
echo $ENV
|
||
echo $APP_ENV
|
||
```
|
||
|
||
#### 3. 配置文件语法检查
|
||
|
||
```bash
|
||
# 检查YAML语法
|
||
yamllint config.yaml
|
||
yamllint configs/env.development.yaml
|
||
```
|
||
|
||
## 📚 相关文件
|
||
|
||
- `internal/config/config.go` - 配置结构体定义
|
||
- `internal/config/loader.go` - 配置加载逻辑
|
||
- `config.yaml` - 基础配置文件
|
||
- `configs/env.*.yaml` - 环境特定配置文件
|
||
|
||
## 🔄 更新日志
|
||
|
||
### v1.0.0
|
||
|
||
- 实现基础的分层配置策略
|
||
- 支持多环境配置
|
||
- 添加配置验证机制
|
||
- 实现环境变量覆盖功能
|
||
|
||
---
|
||
|
||
**注意**: 本配置系统遵循中文规范，所有面向用户的错误信息和日志都使用中文。
|