# 配置管理详解

## 配置文件与代码的映射关系

### config.py 中的定义

```python
class Settings(BaseModel):
    """Application settings."""

    app_name: str = Field(default="Agent Center", description="Application name")
    debug: bool = Field(default=False, description="Debug mode")
    log_level: str = Field(default="INFO", description="Logging level")
    api_key: str | None = Field(default=None, description="API key for external services")

    class Config:
        env_file = ".env"
        env_file_encoding = "utf-8"
```

### .env 文件中的配置

```env
APP_NAME=My Custom Agent
DEBUG=true
LOG_LEVEL=DEBUG
API_KEY=sk-1234567890abcdef
```

---

## 映射规则

### 1. 基本映射规则

Pydantic 会自动将 `.env` 中的变量名映射到类字段：

| config.py 字段 | .env 变量名 | 规则 |
|---------------|------------|------|
| `app_name` | `APP_NAME` | 下划线转大写 |
| `debug` | `DEBUG` | 下划线转大写 |
| `log_level` | `LOG_LEVEL` | 下划线转大写 |
| `api_key` | `API_KEY` | 下划线转大写 |

**规则：** Python 字段名的下划线形式 → 大写形式的环境变量名

### 2. 大小写规则

```python
# config.py
class Settings(BaseModel):
    app_name: str = "default"
```

以下 `.env` 配置**都有效**（不区分大小写）：

```env
APP_NAME=value1        # ✓ 推荐
app_name=value2        # ✓ 也可以
App_Name=value3        # ✓ 也可以
```

但**推荐使用大写**，这是环境变量的约定。

---

## 完整示例

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

```bash
# 在项目根目录创建 .env
cat > .env << 'EOF'
APP_NAME=My Agent Center
DEBUG=true
LOG_LEVEL=DEBUG
API_KEY=sk-test-key-12345
EOF
```

### 步骤 2：Python 代码读取配置

```python
from agentcenter.config import get_settings

# 读取配置
settings = get_settings()

# 访问配置值
print(settings.app_name)   # 输出: My Agent Center
print(settings.debug)      # 输出: True
print(settings.log_level)  # 输出: DEBUG
print(settings.api_key)    # 输出: sk-test-key-12345
```

---

## 优先级规则

配置值的加载优先级（从高到低）：

```
1. 环境变量（系统级）
2. .env 文件
3. 默认值（Field 中的 default）
```

### 示例

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

    class Config:
        env_file = ".env"  # 优先级 2
```

```env
# .env 文件
APP_NAME=From DotEnv File
```

```bash
# 系统环境变量
export APP_NAME="From System"  # 优先级 1（最高）
```

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

---

## 数据类型转换

Pydantic 会自动转换数据类型：

### 布尔值

```python
# config.py
debug: bool = Field(default=False)
```

```env
# .env - 以下都会转换为布尔值
DEBUG=true          # → True
DEBUG=True          # → True
DEBUG=1             # → True
DEBUG=yes           # → True
DEBUG=on            # → True

DEBUG=false         # → False
DEBUG=False         # → False
DEBUG=0             # → False
DEBUG=no            # → False
DEBUG=off           # → False
```

### 整数

```python
# config.py
max_retries: int = Field(default=3)
```

```env
# .env
MAX_RETRIES=5       # → 5 (整数)
```

### 字符串

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

```env
# .env
API_KEY=my-secret-key    # → "my-secret-key" (字符串)
```

### 列表

```python
# config.py
allowed_hosts: list[str] = Field(default_factory=list)
```

```env
# .env
ALLOWED_HOSTS=["localhost", "127.0.0.1", "example.com"]
# 或使用逗号分隔（需要自定义解析）
ALLOWED_HOSTS=localhost,127.0.0.1,example.com
```

---

## 当前项目的配置映射

### config.py 定义

```python
class Settings(BaseModel):
    app_name: str = Field(default="Agent Center")
    debug: bool = Field(default=False)
    log_level: str = Field(default="INFO")
    api_key: str | None = Field(default=None)
```

### 对应的 .env 文件

```env
# 应用基本配置
APP_NAME=Agent Center
DEBUG=false
LOG_LEVEL=INFO

# API 密钥
API_KEY=your-api-key-here

# 可选：OpenAI API 密钥（如果需要）
OPENAI_API_KEY=sk-your-openai-key
```

### 映射关系图

```
.env 文件                    config.py
────────────────────────     ──────────────────────
APP_NAME=Agent Center    →   app_name: str
DEBUG=false              →   debug: bool
LOG_LEVEL=INFO           →   log_level: str
API_KEY=your-key         →   api_key: str | None
```

---

## 实际使用示例

### 示例 1：使用默认值

```python
# 不创建 .env 文件
from agentcenter.config import get_settings

settings = get_settings()
print(settings.app_name)   # Agent Center (默认值)
print(settings.debug)      # False (默认值)
print(settings.log_level)  # INFO (默认值)
print(settings.api_key)    # None (默认值)
```

### 示例 2：从 .env 读取

创建 `.env`：
```env
APP_NAME=Production Agent
DEBUG=false
LOG_LEVEL=WARNING
API_KEY=prod-key-123
```

```python
from agentcenter.config import get_settings

settings = get_settings()
print(settings.app_name)   # Production Agent (来自 .env)
print(settings.debug)      # False (来自 .env)
print(settings.log_level)  # WARNING (来自 .env)
print(settings.api_key)    # prod-key-123 (来自 .env)
```

### 示例 3：环境变量覆盖

```bash
# 设置环境变量
export DEBUG=true
export LOG_LEVEL=DEBUG
```

即使 `.env` 中有配置：
```env
DEBUG=false
LOG_LEVEL=INFO
```

```python
settings = get_settings()
print(settings.debug)      # True (环境变量优先)
print(settings.log_level)  # DEBUG (环境变量优先)
```

---

## 进阶：添加自定义配置

### 添加新字段

1. 在 `config.py` 中添加字段：

```python
class Settings(BaseModel):
    app_name: str = Field(default="Agent Center")
    debug: bool = Field(default=False)
    log_level: str = Field(default="INFO")
    api_key: str | None = Field(default=None)

    # 新增字段
    max_retries: int = Field(default=3, description="Maximum retry attempts")
    timeout: int = Field(default=30, description="Request timeout in seconds")
    database_url: str | None = Field(default=None, description="Database connection URL")
```

2. 在 `.env` 中添加对应配置：

```env
APP_NAME=Agent Center
DEBUG=false
LOG_LEVEL=INFO
API_KEY=your-api-key

# 新增配置
MAX_RETRIES=5
TIMEOUT=60
DATABASE_URL=postgresql://user:pass@localhost/dbname
```

3. 使用新配置：

```python
settings = get_settings()
print(settings.max_retries)    # 5
print(settings.timeout)        # 60
print(settings.database_url)   # postgresql://...
```

---

## 进阶：环境前缀

如果想给所有配置添加前缀（如 `AGENTCENTER_`）：

```python
class Settings(BaseModel):
    app_name: str = Field(default="Agent Center")
    debug: bool = Field(default=False)

    class Config:
        env_file = ".env"
        env_prefix = "AGENTCENTER_"  # 添加前缀
```

此时 `.env` 文件应该是：

```env
AGENTCENTER_APP_NAME=My Agent
AGENTCENTER_DEBUG=true
AGENTCENTER_LOG_LEVEL=DEBUG
```

---

## 安全最佳实践

### 1. 不要提交 .env 到 Git

确保 `.gitignore` 包含：
```gitignore
.env
.env.local
.env.*.local
```

### 2. 提供 .env.example

创建示例文件：
```env
# .env.example
APP_NAME=Agent Center
DEBUG=false
LOG_LEVEL=INFO
API_KEY=your-api-key-here
```

### 3. 文档化所有配置项

在 README 或文档中说明每个配置项的作用。

---

## 故障排除

### 问题 1：.env 文件不生效

**原因：** .env 文件位置不对

**解决：**
```python
from pathlib import Path

class Settings(BaseModel):
    # ...

    class Config:
        env_file = Path(__file__).parent.parent.parent / ".env"
        # 或指定绝对路径
        env_file = "/path/to/your/.env"
```

### 问题 2：配置值类型错误

**错误示例：**
```env
DEBUG=yes  # 期望 true/false
```

**正确示例：**
```env
DEBUG=true
# 或
DEBUG=false
```

### 问题 3：环境变量未读取

**检查：**
```python
import os
print(os.getenv("APP_NAME"))  # 查看环境变量是否存在

from agentcenter.config import get_settings
settings = get_settings()
print(settings.model_dump())  # 查看所有配置值
```

---

## 快速参考

| Python 字段 | .env 变量 | 类型 | 示例值 |
|------------|----------|------|--------|
| `app_name` | `APP_NAME` | str | `"My App"` |
| `debug` | `DEBUG` | bool | `true` / `false` |
| `log_level` | `LOG_LEVEL` | str | `"DEBUG"` / `"INFO"` |
| `api_key` | `API_KEY` | str \| None | `"sk-..."` |

**命名规则：** `snake_case` (Python) ↔ `UPPER_CASE` (环境变量)

**优先级：** 系统环境变量 > .env 文件 > 默认值
