TOML配置文件-马育民老师

# 介绍

TOML（Tom's Obvious, Minimal Language）是一种**简洁、易读、强类型**的配置文件格式，设计目标是平衡“人类可读性”和“机器解析性”，避免 JSON 无注释、INI 结构单一的问题，广泛用于 Python（如 `pyproject.toml`）、Rust 等项目的配置场景。

### TOML 与其他配置格式对比

| 格式 | 优点 | 缺点 | 适用场景 |
|------|------|------|----------|
| **TOML** | 1. 易读性强，支持注释2. 强类型，解析后类型明确3. 支持多层结构和数组表4. 无冗余语法（如 JSON 的逗号问题） | 1. 语法细节较多（如嵌套表的 `.` 分隔）2. 低版本 Python 需第三方库 | Python 项目（`pyproject.toml`）、Rust 项目、中小型配置 |
| **JSON** | 1. 通用性极强，所有语言支持2. 结构清晰，适合机器传输 | 1. 不支持注释2. 不允许尾逗号，易出错3. 多层结构可读性差 | API 数据交互、前端配置 |
| **INI** | 1. 语法极简，适合新手2. 原生支持 section 结构 | 1. 不支持嵌套结构（需自定义扩展）2. 数据类型单一（默认字符串） | 简单配置（如旧版软件、Windows 配置） |
| **YAML** | 1. 语法简洁（用缩进表示层级）2. 支持复杂结构和注释 | 1. 缩进敏感，易因空格出错2. 解析速度较慢 | Kubernetes 配置、大型项目复杂配置 |

# 核心语法规则

TOML 语法基于“**键值对**”，支持多层结构、数据类型、注释等，以下是完整语法拆解：

### 1. 基本键值对（Key-Value）

最基础的配置单元，键名可直接写（无特殊字符）或用引号包裹（含特殊字符），值支持多种数据类型。

```toml
# 1. 字符串（单引号/双引号均可，双引号支持转义）
name = "My App"          # 双引号字符串（支持 \n \t 等转义）
description = 'A simple app'  # 单引号字符串（不转义，原样保留）
long_text = """          # 多行字符串（保留换行，无需转义）
This is a multi-line string.
It can span multiple lines.
"""

# 2. 数字（整数、浮点数、科学计数法）
port = 8080              # 整数
timeout = 3.5            # 浮点数
max_size = 1e6           # 科学计数法（等价于 1000000）

# 3. 布尔值（必须小写 true/false）
debug_mode = true
enable_log = false

# 4. 日期时间（支持 RFC 3339 标准格式）
start_time = 2024-05-20T14:30:00Z  # 带时区（UTC）
release_date = 2024-05-20          # 仅日期
```

### 2. 多层结构：表（Table）

用 `[table_name]` 定义“表”（类似 JSON 的嵌套对象、Python 的字典），支持**单层表**和**嵌套表**。
```toml
# 1. 单层表（对应 Python 的 {"database": {...}}）
[database]
host = "localhost"
port = 3306
user = "admin"
password = "secure123"
db_name = "my_db"

# 2. 嵌套表（用 . 分隔层级，对应 {"api": {"auth": {...}}}）
[api.auth]
token = "abc123xyz"
expire_days = 7
refresh_enable = true

# 3. 数组表（用 [[table]] 定义，对应 Python 的列表嵌套字典）
# 场景：多个同类配置（如多个数据库、多个接口）
[[servers]]  # 第一个服务器
ip = "192.168.1.100"
port = 80

[[servers]]  # 第二个服务器
ip = "192.168.1.101"
port = 81

# 解析后对应 Python：servers = [{"ip": "...", "port": 80}, {"ip": "...", "port": 81}]
```

### 3. 数组（Array）
用 `[]` 定义，元素类型需一致（TOML 要求强类型，不允许混合类型）。
```toml
# 字符串数组
allowed_origins = ["http://localhost", "https://example.com"]

# 整数数组
white_list_ports = [80, 443, 8080]

# 嵌套数组（数组元素为数组）
matrix = [[1, 2], [3, 4], [5, 6]]

# 表数组（数组元素为表，与 [[servers]] 等价但写法不同）
features = [
  { name = "login", enable = true },
  { name = "payment", enable = false }
]
```

### 4. 注释
用 `#` 开头，单行注释，支持在键值对后追加注释。
```toml
# 这是全局注释（配置文件说明）
[log]
level = "DEBUG"  # 日志级别：DEBUG/INFO/WARN/ERROR（行尾注释）
file_path = "./logs/app.log"  # 日志存储路径
```

### 最佳实践

1. **命名规范**：表名和键名用 `snake_case`（下划线分隔），如 `db_name`、`api_auth`，避免大小写混用。
2. **结构分层**：按功能模块拆分表（如 `[database]`、`[log]`、`[api]`），避免全局键值对过多。
3. **注释清晰**：对关键配置（如密码、密钥、特殊参数）添加注释，说明用途和取值范围。
4. **避免冗余**：同类配置优先用数组表（`[[...]]`），如多服务器、多模块配置，减少重复键名。
5. **文件命名**：项目配置建议用 `config.toml` 或 `app.toml`，Python 项目的构建配置固定为 `pyproject.toml`（PEP 621 规范）。

TOML 凭借其平衡的设计，已成为现代项目配置的主流选择之一，尤其适合需要兼顾“人类可维护性”和“机器解析效率”的场景。

# 完整 TOML 配置示例

以下是一个贴近实际项目的配置文件（`app_config.toml`），涵盖上述所有语法：

```toml
# 应用基础配置
app_name = "SmartDoc"
version = "1.2.0"
author = "Dev Team"
description = """
A document management system that supports:
- PDF/Word parsing
- Full-text search
- Cloud sync
"""

# 数据库配置
[database]
type = "mysql"
host = "127.0.0.1"
port = 3306
credentials = { user = "root", password = "db_pass123" }  # 内联表（简洁写法）
db_name = "smart_doc"
connect_timeout = 5.0
pool_size = 10

# API 服务配置
[api]
base_url = "https://api.smartdoc.com"
timeout = 30
rate_limit = 100  # 每分钟最大请求数

[api.auth]  # 嵌套表：api 的子配置 auth
jwt_secret = "your-jwt-secret-key"
expire_hours = 24

# 多服务器配置（数组表）
[[servers]]
region = "cn-north"
ip = "10.0.0.1"
port = 8080
services = ["doc-parse", "search"]

[[servers]]
region = "cn-south"
ip = "10.0.1.1"
port = 8080
services = ["sync", "backup"]

# 日志配置
[log]
level = "INFO"
file_path = "./logs/app.log"
rotation = { max_size = 1024, keep_days = 30 }  # 日志轮转配置
modules = ["database", "api", "auth"]  # 需日志记录的模块
```

原文出处：http://malaoshi.top/show_1GW1lZnjqH1e.html