配置说明

FastQTools 的配置哲学很简单：把默认值、环境变量和命令行参数保持在一条明确的覆盖链上，让使用者知道“最后到底是谁说了算”。

配置优先级

从低到高依次为：

默认值 → 配置文件 / 环境注入 → 环境变量 → 命令行参数

在实际使用中，可以把它理解为：

• 默认值负责给出安全起点；
• 环境变量负责在某个运行环境里提供稳定默认；
• 命令行参数负责当前任务的最终决策。

命令行配置

最显式、也最容易审计的方式，是把关键参数直接写在命令里：

FastQTools stat -i reads.fastq.gz -o stats.txt -t 8
FastQTools filter -i reads.fastq.gz -o clean.fastq.gz --min-quality 20 --min-length 50

当脚本需要长期维护时，建议把真正影响结果的关键阈值保留在命令行，而不是隐藏在外部环境里。

环境变量配置

当多个任务共享同一运行环境时，环境变量适合作为“环境级默认值”：

export FASTQTOOLS_THREADS=8
export FASTQTOOLS_BATCH_SIZE=100000
FastQTools stat -i reads.fastq.gz -o stats.txt

如果同一个命令中又显式传入 --threads 16，那么命令行应覆盖环境变量。这一点对于 CI 与容器环境特别重要。

维护者视角下的配置边界

维护者需要同时关注两个问题：

1. 行为可解释：用户看到一条命令，就能推断出主要运行参数；
2. 默认值可维护：新增参数时，不要破坏既有覆盖链，也不要让不同入口出现互相矛盾的默认值。

如果你正在设计新的选项或调参入口，请对照开发者架构设计与核心设计理解参数落点，而不是只补一段 CLI 文案。

推荐实践

• 把影响结果的关键阈值写进命令行；
• 把线程数、批大小等环境相关默认放入环境变量；
• 让容器、CI 与本地脚本共用同一套命名与覆盖规则；
• 在团队环境中，把“哪一层负责什么”写进脚本注释或运行手册。