tyapi-server/internal/config/README.md

# 🔧 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

-   实现基础的分层配置策略
-   支持多环境配置
-   添加配置验证机制
-   实现环境变量覆盖功能

---

**注意**: 本配置系统遵循中文规范，所有面向用户的错误信息和日志都使用中文。