模块化设计：规则组织与模块边界

说实话，我刚接触 Snakemake 那会儿，觉得这东西不就是把脚本串起来嘛。规则写在一个文件里，一条接一条跑，挺顺的。直到有一天，我的工作流从 10 条规则涨到了 50 条，那个 Snakefile 变得又臭又长。改一个参数要翻三屏，出了问题也不好排查。嗯，那时候我才意识到——模块化不是花架子，是真能救命的。

这一章我们聊的核心就两个问题：规则怎么组织，模块边界怎么划。说白了，就是帮你把一团乱麻理成几根清晰的绳子。

为什么非要划模块

我见过不少项目，一个 Snakefile 里堆了几百行。跑是能跑，但你要修改某个分析步骤，得在全局里找变量定义、找输入输出，稍不注意就改串了。更头疼的是，你想复用某个分析流程，只能复制粘贴——然后维护两套代码。

模块化能解决三个实际问题：

• 隔离变化 —— 某个模块改了，不影响其他模块
• 复用逻辑 —— 同样的分析流程，换套参数就能用在另一个项目
• 分而治之 —— 团队协作时每个人负责一个模块，互不干扰

规则组织的三条原则

先说说我踩过的坑。最早我把所有规则按字母排序，觉得这样好找。结果发现，逻辑上关联的规则被拆得到处都是，读起来非常痛苦。后来我总结了三原则，你可以试试看。

原则一：按功能聚合，不按工具聚合

很多人会这样：把所有的 Python 脚本调用写在一起，所有的 R 脚本写在一起。这是按工具分，不是按功能分。更好的做法是按分析步骤分：数据预处理一个模块，质控一个模块，差异分析一个模块，可视化一个模块。每个模块里，不管用什么工具，都放在一起。

# 不好的组织方式
rule run_fastqc:
    input: "data/{sample}.fastq"
    output: "qc/{sample}_fastqc.html"
    shell: "fastqc {input} -o qc/"

rule run_trimmomatic:
    input: "data/{sample}.fastq"
    output: "trimmed/{sample}.fastq"
    shell: "trimmomatic SE {input} {output} ..."

# 更好的组织方式 —— 按功能模块分
# 文件：modules/quality_control.smk
rule fastqc:
    input: "data/{sample}.fastq"
    output: "qc/{sample}_fastqc.html"
    shell: "fastqc {input} -o qc/"

rule multiqc:
    input: expand("qc/{sample}_fastqc.html", sample=SAMPLES)
    output: "qc/multiqc_report.html"
    shell: "multiqc qc/ -o qc/"

原则二：显式声明输入输出，不依赖全局变量

这个我吃过亏。以前我喜欢在 Snakefile 顶部定义一堆全局路径，规则里直接用。后来别人想复用我某个模块，得先搞清楚所有全局变量是啥，特别烦。

我现在的做法是：每个模块的输入输出都在规则里显式写清楚，模块之间通过文件传递，不共享变量。这样每个模块都可以独立跑，也方便测试。

# 不好的做法 —— 依赖全局变量
SAMPLES = ["A", "B", "C"]
OUTDIR = "results"

rule align:
    input: "data/{sample}.fastq"
    output: f"{OUTDIR}/aligned/{sample}.bam"
    shell: "bwa mem ref.fa {input} > {output}"

# 好的做法 —— 模块内部自包含
# modules/alignment.smk
rule align:
    input:
        fastq="data/{sample}.fastq",
        reference="refs/genome.fa"
    output: "results/aligned/{sample}.bam"
    shell: "bwa mem {input.reference} {input.fastq} > {output}"

原则三：模块间用配置文件通信，不用硬编码

每个模块需要的参数（比如阈值、参考基因组路径、样本列表），都通过一个独立的配置文件传入。模块内部不去读全局配置，只读自己声明需要的参数。这样模块的依赖关系就干净了。

模块边界怎么划

划边界这事，没有标准答案。但有个经验法则：如果两个规则之间经常要一起修改，它们应该在一个模块里；如果它们各自独立演化，就该分开。

我一般按数据流的自然断点来划：

数据阶段	典型规则	是否独立成模块
原始数据	下载、校验、重命名	是，数据接入模块
预处理	质控、去接头、过滤	是，质控模块
核心分析	比对、定量、差异分析	是，分析模块
结果处理	可视化、报告生成	是，报告模块

每个模块的边界由 输入文件约定 和 输出文件约定 来定义。比如质控模块的输出目录固定是 qc/，分析模块就从 qc/ 读数据。只要目录结构和文件命名约定不变，模块内部怎么改都行。

一个完整的模块化目录结构

下面是我现在常用的项目布局，你可以参考：

project/
├── Snakefile                 # 主入口，只做 include 和全局配置
├── config.yaml               # 全局配置
├── samples.tsv               # 样本表
├── modules/
│   ├── qc/
│   │   ├── Snakefile         # 模块规则
│   │   └── config.yaml       # 模块参数
│   ├── alignment/
│   │   ├── Snakefile
│   │   └── config.yaml
│   └── report/
│       ├── Snakefile
│       └── config.yaml
├── scripts/
│   ├── qc_utils.py
│   └── plotter.R
└── results/                  # 所有输出都在这里，按模块分子目录

主 Snakefile 里只需要这样写：

configfile: "config.yaml"
include: "modules/qc/Snakefile"
include: "modules/alignment/Snakefile"
include: "modules/report/Snakefile"

你看，主文件只有几行。每个模块独立维护，想加新的分析流程，加一个目录和一行 include 就行。

避坑指南

我过去两年在多个项目里实践这套方法，踩过一些坑，分享几个典型的：

• 别过早拆分 —— 规则少于 30 条时，先别急着模块化。等你觉得一个文件翻着费劲了再拆，那个时机刚刚好。
• 模块之间不要循环依赖 —— A 模块输出给 B，B 又输出给 A，这种设计会让 Snakemake 的 DAG 解析直接报错。如果出现循环依赖，说明边界划错了，需要重新设计。
• 测试每个模块的独立性 —— 我每次建完一个模块，都会单独跑一下 snakemake --snakefile modules/xxx/Snakefile，确保它不依赖外部变量就能运行。
• 统一命名约定 —— 所有模块的输出目录、文件后缀、日志格式都要提前约定好。我吃过亏：质控模块输出 .html，报告模块却等 .htm，排查了半天才发现是后缀不一致。

好了，这一章的内容就这些。模块化设计的核心其实就是三件事：按功能聚规则、显式声明接口、用文件通信。把这些想明白，你的工作流就能从一团乱麻变成搭积木。