📚 课程目录第3章参数文件结构

第3章参数文件结构：配置格式、路径与加载顺序

咱们开始聊参数文件的结构。嗯，说实话，刚接触 THS-PREPARE 的时候，我打开它的配置文件目录，第一反应是——怎么这么多文件？后来跑了几轮调度，踩了几个坑，才明白这些文件其实各司其职，结构清清楚楚。

这一章，我就把配置文件格式、存放路径、加载顺序这几个核心点掰开讲。你读完就能知道：到底用 YAML 还是 JSON？文件该放哪儿？系统按什么顺序读它们？

THS-PREPARE 支持三种主流格式：YAML、JSON 和 INI。我个人最常用 YAML，因为可读性好，适合写注释。不过项目里也见过混合使用的场景——核心参数用 JSON，自定义覆盖用 INI。

一个小技巧：新项目我建议用 YAML，团队交接时看一眼就能懂。如果是需要被其他脚本频繁解析的参数，用 JSON 更友好。

文件放哪儿？我见过有人把所有配置堆在根目录，结果版本迭代后自己都找不着。THS-PREPARE 采用分层路径设计，目的就是避免混乱。

举个例子，我曾在某个项目中把 THS_PREPARE_CONFIG 指向 /data/prod/prepare/override.yaml，专门用来覆盖生产环境的连接池大小。这样流水线部署时不用动默认配置，安全又灵活。

注意：我曾经把自定义配置放在当前目录却忘了加 ./，结果系统一直读的是系统级参数，排查半天。路径一定要写全或使用路径。

搞清楚了格式和路径，那系统怎么决定用哪个参数？这就涉及到加载顺序。你可以理解成“后加载的覆盖先加载的”。

为什么会设计四步？我猜设计者希望兼顾“默认可用”和“灵活覆盖”。举个例子，系统级定义超时时间为30秒，项目级想改成60秒，那就直接在项目配置里写 timeout: 60，它会覆盖系统级。如果某次紧急调试需要改成120秒，又不想修改配置文件，设个环境变量就搞定了。

核心原则：参数覆盖链为 系统级 < 项目级 < 用户自定义 < 环境变量。数字越大，优先级越高。

下面这张图把刚才说的格式、路径、加载顺序梳理成一张流程图，你看完应该能对整体框架有印象。

你看，最上面是三种文件格式，中间是三种路径层级，下面是四步加载顺序。箭头方向就是覆盖方向。记住这张图，以后配参数就有章可循了。

光说不练假把式。咱们拿一个实际例子串一遍。假设你要配置 THS-PREPARE 连接 MySQL，参数包括主机、端口、超时时间。

# prepare.yaml
database:
  host: "192.168.1.100"
  port: 3306
  timeout: 30  # 单位秒
  pool_size: 10

{
  "database": {
    "host": "192.168.1.100",
    "port": 3306,
    "timeout": 30,
    "pool_size": 10
  }
}

[database]
host = 192.168.1.100
port = 3306
timeout = 30
pool_size = 10

我的习惯：核心参数用 YAML 写，保留注释。INI 只用来做少量覆盖，比如在内网测试环境增加 pool_size=5。JSON 一般不用手写，除非是 CI/CD 脚本自动生成。

坑一：YAML 缩进不一致 —— 我曾在复制粘贴时把空格的缩进混成了 Tab，系统直接报解析错误。后来我都用编辑器自动格式化 YAML 文件。
坑二：文件路径拼写错误 —— 把 ./conf/ 写成了 ./config/，结果系统没加载到，用了默认参数。生产环境出问题才查出来。
坑三：环境变量覆盖规则不清楚 —— 当初以为只有项目级加载，设了一个环境变量 THS_PREPARE_OVERRIDE=timeout=150，结果所有节点都受影响。切记环境变量优先级最高，应用范围是整个进程。

第3章 参数文件结构：配置格式、路径与加载顺序