📚 课程目录第3章工作流定义文件（main.nf）的版本管理

3、工作流定义文件（main.nf）的版本管理：脚本结构、模块化拆分、版本记录

好，这一章我们聊点实际的。main.nf 是 Nextflow 工作流的入口，也是整个流程的骨架。你想想看，随着流程越来越复杂，如果所有代码都堆在一个文件里，那维护起来有多痛苦？我见过不少项目，一个 main.nf 就写了两三千行，各种 process 嵌套、逻辑混杂，回头看自己写的代码都得靠猜。

今天我就把多年积累的经验拆开来讲。main.nf 的版本管理，说白了就三件事：脚本结构要清晰、功能要模块化、版本要记录。这三件事做好了，版本回溯和代码复用就会变得非常省心。

3.1 脚本结构：从混乱到有序

很多新手喜欢把所有 process 和 workflow 都塞进 main.nf。这样做在最开始确实方便，但项目一旦超过 10 个 process，文件就会变得像一团乱麻。

我建议你采用这样的标准结构：

main.nf
lib/
  └── Utils.groovy
modules/
  ├── QC/
  │   ├── fastqc.nf
  │   └── multiqc.nf
  └── Alignment/
      ├── star.nf
      └── bwa.nf
conf/
  ├── base.config
  ├── cluster.config
  └── test.config
nextflow.config

这个结构有几个好处：main.nf 只负责流程编排，不包含具体 process 定义；lib/ 目录放通用工具函数；modules/ 按功能模块拆分工具体 process；conf/ 目录放不同环境的配置。

  我的经验：main.nf 本身要保持在 200 行以内。如果超过这个数，你就该考虑拆分了。我不喜欢写注释特别多的代码，但我会确保文件名和模块名能自解释。

3.2 模块化拆分：让每个文件各司其职

模块化拆分的核心原则是单一职责。每个 .nf 文件只做一件事，并且只暴露必要的组件给外部。

举个例子，我处理 RNA-seq 数据时，会这样拆分：

// main.nf
nextflow.enable.dsl=2

include { FASTQC } from './modules/QC/fastqc'
include { MULTIQC } from './modules/QC/multiqc'
include { STAR_ALIGN } from './modules/Alignment/star'

workflow {
    FASTQC(read_files)
    MULTIQC(FASTQC.out)
    STAR_ALIGN(read_files)
}

你看，main.nf 只负责引入模块并定义流程顺序。每个模块内部怎么做，main.nf 完全不关心。这样做的最大好处是：哪天你想换比对工具，只需要改 ./modules/Alignment/star.nf，其他部分完全不用动。

技巧：模块化拆分后，记得在 lib/ 目录下放一个 Utils.groovy，把常用的路径拼接、样本信息提取等函数放进去。这样可以避免不同模块之间重复写相同的逻辑。

3.3 模块的版本记录

只拆分还不够，每个模块还要能追溯到它的版本。我踩过最深的一个坑是：项目跑到一半，发现某个模块被不小心改错了，但完全不知道它什么时候变的。

我的做法是：在每个模块文件头部，用注释块记录版本信息。

// modules/QC/fastqc.nf
// =============================================
// Module     : FASTQC
// Version    : 1.2.0
// Author     : your_name
// Date       : 2024-03-15
// Changes    : 1.2.0 - 添加多线程支持
//              1.1.0 - 修复内存溢出问题
//              1.0.0 - 初始版本
// =============================================

process FASTQC {
    tag "FastQC: ${sample_id}"
    publishDir "${params.outdir}/QC", mode: 'copy'

    input:
    tuple val(sample_id), path(reads)

    output:
    path "fastqc_*"

    script:
    """
    fastqc -t ${task.cpus} $reads
    """
}

这看起来很简单，但效果非常好。当我要回退到某个稳定版本时，我只需要看看这个版本号，然后去 Git 仓库找出对应的 commit。

3.4 版本号命名规范

模块的版本号怎么定？我个人习惯用语义化版本号（Semantic Versioning）：

版本号示例	含义	什么时候改
1.0.0	初始稳定版本	模块首次发布时
1.1.0	新增功能	添加新参数或新功能时
1.1.1	修复 Bug	修复不兼容的功能时
2.0.0	重大变更	接口或输入输出格式变更时

注意：版本号不只是在文件头部写一行注释就完事了。你还得把这个版本号真正用到代码里，比如在 process 的输出文件名中加入版本号，或者在日志里显式输出。否则，你写再漂亮的版本号，实际上还是没法追溯。

3.5 模块版本管理的核心逻辑

下面这张图展示了我推荐的模块化版本管理流程。你从原始 main.nf 开始，先做模块化拆分，然后为每个模块记录版本，最后通过 Git 标签和版本号锚定稳定版本。

你可能会问，为什么不用 Git 提交记录直接代替模块的版本号？原因很简单：Git 是整个仓库的版本，而模块版本只关注模块自身的变更。把两者结合使用，才能做到精细化管理。

3.6 避坑指南：模块化常见问题

我见过不少团队在模块化时踩坑，这里总结几个最常见的：

模块过度拆分：每个模块只包含一个 process 是没必要的。我一般以「功能组」为单位，比如比对、质控、定量，一个模块放 2-3 个相关的 process。
版本号不同步：某个模块改了，但没更新头部注释的版本号。我曾因为这个问题浪费了一周时间排查。现在我会在 CI/CD 流程里加个检查脚本，发现版本号没更新就直接报错。
模块依赖混乱：模块 A 依赖模块 B 的输出，但两个模块的版本号没有关联。我的建议是：在 main.nf 的版本记录中，明确写出当前流程依赖的模块版本组合。

我的做法：在项目根目录放一个 MANIFEST.md 文件，记录每个稳定版本对应的模块版本组合。这样即使半年后再回来看，也能马上知道当时用了哪些模块、什么版本。

3.7 版本记录与 Git Tag 结合

模块的版本号写进文件里只是第一步，更重要的是把版本和 Git 的 tag 关联起来。我推荐这样操作：

# 制作稳定版本后，打上 Git tag
git tag -a v1.2.0 -m "Release v1.2.0: 更新 FASTQC 模块至 1.2.0"

# 查看某次 release 的模块版本
git show v1.2.0:modules/QC/fastqc.nf | head -20

这样，你任何时候都能通过 git show 命令，直接查看某个 release 版本中任意模块的源码。有了这个机制，版本管理才算真正闭环。