# 配置映射可视化指南

## 快速理解：.env 文件如何映射到 Python 代码

### 映射流程图

```
┌─────────────────────┐
│   .env 文件         │
│                     │
│  APP_NAME=My Agent  │ ──────┐
│  DEBUG=true         │ ──────┤
│  LOG_LEVEL=DEBUG    │ ──────┤    Pydantic Settings
│  API_KEY=sk-123     │ ──────┤    自动读取和转换
└─────────────────────┘       │
                              │
                              ▼
┌──────────────────────────────────────┐
│   config.py                          │
│                                      │
│   class Settings(BaseSettings):     │
│       app_name: str  ◄───────────── APP_NAME
│       debug: bool    ◄───────────── DEBUG (转换为布尔值)
│       log_level: str ◄───────────── LOG_LEVEL
│       api_key: str   ◄───────────── API_KEY
│                                      │
└──────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────┐
│   使用配置                          │
│                                     │
│   settings = get_settings()        │
│   print(settings.app_name)         │
│   # 输出: "My Agent"                │
└─────────────────────────────────────┘
```

---

## 详细映射表

### 当前项目的映射关系

| .env 文件 | config.py | Python 类型 | 实际值示例 | 说明 |
|-----------|-----------|------------|-----------|------|
| `APP_NAME=My Agent` | `app_name: str` | `str` | `"My Agent"` | 字符串直接映射 |
| `DEBUG=true` | `debug: bool` | `bool` | `True` | 字符串转布尔值 |
| `LOG_LEVEL=DEBUG` | `log_level: str` | `str` | `"DEBUG"` | 字符串直接映射 |
| `API_KEY=sk-123` | `api_key: str \| None` | `str` | `"sk-123"` | 可选字符串 |

---

## 实际示例

### 示例 1：完整流程

**步骤 1：创建 .env 文件**

```bash
# .env
APP_NAME=My Custom Agent Center
DEBUG=true
LOG_LEVEL=DEBUG
API_KEY=sk-test-1234567890abcdef
```

**步骤 2：Python 代码自动读取**

```python
from agentcenter.config import get_settings

settings = get_settings()
```

**步骤 3：访问配置值**

```python
print(settings.app_name)   # My Custom Agent Center
print(settings.debug)      # True (注意：是布尔值，不是字符串)
print(settings.log_level)  # DEBUG
print(settings.api_key)    # sk-test-1234567890abcdef
```

---

## 命名转换规则

### Python → 环境变量

```python
# config.py 中的 Python 字段名
app_name      →  APP_NAME       # 转大写
debug         →  DEBUG          # 转大写
log_level     →  LOG_LEVEL      # 下划线保留，转大写
api_key       →  API_KEY        # 下划线保留，转大写
```

### 规则总结

1. **Python 字段**：小写，使用下划线（`snake_case`）
2. **环境变量**：大写，使用下划线（`UPPER_CASE`）
3. **自动映射**：Pydantic 自动处理大小写转换

---

## 类型转换详解

### 1. 布尔值转换

.env 文件中的字符串会自动转换为 Python 布尔值：

```env
# .env 文件
DEBUG=true       # → Python: True
DEBUG=false      # → Python: False
DEBUG=1          # → Python: True
DEBUG=0          # → Python: False
DEBUG=yes        # → Python: True
DEBUG=no         # → Python: False
```

### 2. 字符串转换

```env
# .env 文件
APP_NAME=My Agent        # → Python: "My Agent"
LOG_LEVEL=DEBUG          # → Python: "DEBUG"
```

### 3. 可选值（None）

```python
# config.py
api_key: str | None = Field(default=None)
```

```env
# 如果 .env 中没有 API_KEY
# Python: None

# 如果 .env 中有 API_KEY
API_KEY=sk-123
# Python: "sk-123"
```

---

## 配置优先级（从高到低）

```
┌────────────────────────────────┐
│ 1. 系统环境变量（最高优先级）   │ ← export APP_NAME="System"
├────────────────────────────────┤
│ 2. .env 文件                   │ ← APP_NAME=From DotEnv
├────────────────────────────────┤
│ 3. 默认值（最低优先级）         │ ← Field(default="Default")
└────────────────────────────────┘
```

### 实际示例

```python
# config.py
app_name: str = Field(default="Default Name")  # 优先级 3
```

```env
# .env
APP_NAME=From DotEnv File  # 优先级 2
```

```bash
# 终端
export APP_NAME="From System"  # 优先级 1（最高）
```

**结果：**
```python
settings = get_settings()
print(settings.app_name)  # 输出: "From System"
```

---

## 实际运行演示

### 运行演示程序

```bash
# 运行配置演示
uv run python examples/config_demo.py
```

### 输出示例

```
基本用法演示
============================================================
应用名称: My Custom Agent Center
调试模式: True
日志级别: DEBUG
API 密钥: sk-test-1234567890abcdef

字段映射关系
============================================================
Python 字段: app_name        → 环境变量: APP_NAME
  Python 值: My Custom Agent Center
  .env 值:   My Custom Agent Center

Python 字段: debug           → 环境变量: DEBUG
  Python 值: True
  .env 值:   true

类型转换演示
============================================================
字符串类型:
  app_name: 'My Custom Agent Center' (type: str)

布尔类型:
  debug: True (type: bool)
  .env 中的 'true'/'false' 自动转换为 Python 的 True/False
```

---

## 常见问题

### Q1: 为什么我的 .env 文件不生效？

**检查清单：**
1. ✓ .env 文件在项目根目录
2. ✓ 文件名正确（`.env`，不是 `env` 或 `.env.txt`）
3. ✓ 使用了 `pydantic-settings` 包
4. ✓ 继承了 `BaseSettings`（不是 `BaseModel`）
5. ✓ 设置了 `model_config` 中的 `env_file`

### Q2: 如何验证配置是否正确？

```python
from agentcenter.config import get_settings

settings = get_settings()
print(settings.model_dump())  # 查看所有配置
```

### Q3: 可以使用不同的 .env 文件吗？

```python
class Settings(BaseSettings):
    # ...

    model_config = {
        "env_file": ".env.production",  # 使用不同文件
        "env_file_encoding": "utf-8",
    }
```

---

## 总结

### 核心要点

1. **命名规则**: `python_field` ↔ `ENV_VAR` (自动转换)
2. **类型转换**: 自动处理（字符串、布尔值等）
3. **优先级**: 系统环境变量 > .env 文件 > 默认值
4. **必需包**: `pydantic-settings` 和 `python-dotenv`

### 最佳实践

- ✓ 使用 `.env.example` 作为模板
- ✓ 不要将 `.env` 提交到 Git（添加到 `.gitignore`）
- ✓ 使用类型注解确保类型安全
- ✓ 为所有字段提供合理的默认值
- ✓ 使用 `Field` 添加描述信息

### 快速参考

```bash
# 查看当前配置
uv run python -c "from agentcenter.config import get_settings; print(get_settings().model_dump())"

# 运行演示
uv run python examples/config_demo.py
```
