TOML配置文件

作者：马育民 • • 阅读：10078

介绍

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）

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

# 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 的字典），支持单层表和嵌套表。

# 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 要求强类型，不允许混合类型）。

# 字符串数组
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. 注释

用 # 开头，单行注释，支持在键值对后追加注释。

# 这是全局注释（配置文件说明）
[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），涵盖上述所有语法：

# 应用基础配置
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"]  # 需日志记录的模块

原文出处：/show_1GW1lZnjqH1e.html

吉ICP备15003043号