二、工作流参数定义与类型归纳总结

参数是工作流的“入口”。我见过不少新手写 Nextflow 流程时，把所有硬编码值都塞在脚本里，结果换一个样本就得改代码。说实话，这违背了流程复用的初衷。这一章我们专门聊聊参数该怎么定义、归到什么类型，以及我在实践中踩过的坑。

2.1 参数定义三要素

Nextflow 的参数定义其实就三件事：位置、默认值、覆盖方式。你可以在 nextflow.config 里给 params 设默认值，也可以在命令行用 --param_name 覆盖，还可以通过 params.yml 文件批量注入。我习惯把“实验无关”的配置（比如参考基因组路径）放在配置文件的 params 作用域里，而把每次运行会变的（比如样本 ID）放到命令行参数上。

一个标准的参数声明长这样：

// nextflow.config
params {
    outdir = "./results"
    reads  = "/data/samples/raw/*.fastq"
    genome = "GRCh38"
    skip_qc = false
    threads = 8
}

然后在命令行使用时：

nextflow run main.nf --reads '/data/new_set/*.fastq' --skip_qc true

嗯，这里要注意：命令行指定的值会覆盖配置文件里的默认值。但如果你在同一个参数上用 -params-file 又同时给了 --，后者的优先级更高。我曾经在一个 CI 流水线里同时混用了两种方式，结果调试了半天才发现是参数冲突。

2.2 参数类型面面观

Nextflow 的参数类型虽然动态解析，但实际工作中你最好心里有数。下面这张表是我根据自己的经验整理的常见类型和典型场景：

类型	示例值	典型用途	注意点
字符串	"GRCh38"	参考基因组、样本前缀	路径中含空格要用引号包裹
数字	8、0.85	线程数、质控阈值	Nextflow 会按 Groovy 动态类型处理，但别依赖自动转换
布尔	true / false	开关型功能（是否跳过某步）	命令行传 --flag 会被解析为 true
列表	["A","B","C"]	多个样本、多个BAM文件	用逗号分隔，也可以从文件或Glob读取
文件路径	"/data/ref.fa"	输入文件、索引、数据库	建议用 file() 构建路径，确保跨平台兼容
Map / 字典	"""{"s1":"A","s2":"B"}"""	样本分组、元数据映射	JSON 格式，注意引号转义

2.3 参数解析的完整链路

你可能以为参数定义就是写个 params.x = ... 就完了。但实际在运行过程中，Nextflow 会经历一个完整的解析链路。下面这张图是我画的工作流参数从“外部输入”到“内部使用”的全流程：

你看，整个链路就像个漏斗——外部输入先按优先级叠加，再统一做类型推断。Nextflow 在合并参数时，会自动把字符串 "true" 转成布尔，把数字字符串转成整数。但万一你传了个 --threads "8GB"，它只会当成字符串，不会报错。所以运行时检查非常有必要。

2.4 类型推断与隐式转换

说到类型推断，我踩过一个挺典型的坑：

所以我的建议是：对于关键参数，在流程开头做一次显式类型转换，比如：

params {
    skip_qc = false   // 注意默认值就是布尔
}

workflow {
    skip_qc = params.skip_qc as Boolean
    // 或者用更安全的方式
    skip_qc = params.skip_qc.toString() in ['true','1','yes']
}

另外，文件路径参数建议用 file() 构造，而不是直接拼接字符串。比如：

params {
    ref = "/data/GRCh38.fa"
    sample_dir = "/home/user/samples"
}

// 正确用法
ref_path = file(params.ref)
sample_files = file(params.sample_dir + "/*.fastq").collect()

2.5 参数校验与错误处理

一个好的工作流应该对参数做校验。我这几年逐渐养成了习惯：在 workflow 块开始之前，用 log.info 打印所有参数摘要，这样运行时一眼就能看出有没有传错：

workflow {
    log.info """
        ==================================
        Pipeline Parameter Summary
        ==================================
        genome   : ${params.genome}
        reads    : ${params.reads}
        skip_qc  : ${params.skip_qc}
        threads  : ${params.threads}
        outdir   : ${params.outdir}
        ==================================
    """
    
    // 简单校验
    assert params.outdir != null : "outdir must be provided"
    assert file(params.reads).exists() : "reads path does not exist: ${params.reads}"
    
    // 主流程
    FASTQC(params.reads)
    // ...
}

嗯，这里要注意：assert 在 Nextflow 里默认是启用的，但如果用户用 -disable-assertions 启动就失效了。我建议用 exit 1 替代 assert，更可靠：

if (!file(params.reads).exists()) {
    log.error "Error: reads file not found: ${params.reads}"
    exit 1
}

2.6 参数文档化

最后，别忘了把参数的含义写进 README 或者帮助信息。Nextflow 支持在 main.nf 顶部加 nextflow.enable.dsl=2 和注释。我习惯在 nextflow.config 里为每个参数写一段简洁的说明：

// nextflow.config
manifest {
    name        = "my-pipeline"
    description = "RNA-seq quantification"
    version     = "1.0.0"
}

params {
    // 参考基因组路径（FASTA格式）
    genome = ""

    // 输入fastq文件的Glob模式
    reads  = ""

    // 输出目录，默认当前目录下的results
    outdir = "$PWD/results"
    
    // 是否跳过质控步骤
    skip_qc = false
}

这样做的好处有两个：一是自己半年后回来看能快速回忆，二是其他人拿到你的流程也能直接上手。我觉得这算是一种“面向未来的参数定义”吧。