数字参数：整数、浮点数参数传递与类型校验

参数传对了，管道跑得顺；参数传错了，半夜爬起来改 bug。咱们今天聊聊 Nextflow 里最常见的两种数字参数——整数和浮点数。

很多人觉得数字参数嘛，不就是 --count 10 或者 --rate 3.14 嘛，有啥好讲的？其实坑都在细节里。我自己刚开始用 Nextflow 的时候，就因为在浮点数精度上踩过一脚，浪费了好几天调试结果。

整数参数：看上去简单，但类型校验容易漏

先看整数。在 Nextflow 里声明一个整数参数，最直接的方式就是写在 params 里：

params.num_samples = 100
params.threads = 4

不过，这样写有个隐患——如果你在命令行传了个 --num_samples 12.5，Nextflow 不会报错，它会自动把 12.5 当成浮点数存起来。等你后面用它当索引或者循环次数时，直接崩溃。

if (! (params.num_samples instanceof Integer) ) {
    error "参数 'num_samples' 必须为整数，当前类型: ${params.num_samples.getClass().getSimpleName()}"
}

如果你用 Nextflow DSL2，还可以在 process 的 input 块里明确声明类型：

process prepare_data {
    input:
    val num from params.num_samples as Integer
    
    script:
    """
    python split.py --count ${num}
    """
}

这样写，传递时会自动校验。如果传进来的是字符串 "100"，也会被尝试转成整数。但要是传了 "abc"，就会抛异常。

有一天在线上跑批量任务，同事传了个 --num_samples 1e2，Nextflow 居然把它当浮点数 100.0 处理了。我当时在日志里看到 "100.0 samples" 才意识到不对——后面的 Python 脚本直接报错。从那之后，我就在所有管道入口加了严格的数字校验。

浮点数参数：精度和科学计数法的坑

浮点数比整数麻烦。在 Nextflow 里声明：

params.learning_rate = 0.001
params.tolerance = 1e-6

嗯，这里就有一个隐藏问题——1e-6 传给下游时，如果被序列化成 JSON 再读回来，精度可能会变。Nextflow 内部用 Double 存浮点，但命令行参数传进来的是字符串，需要做一次类型转换。

我做深度学习管道时，需要传一个很小的浮点数 1e-8 作为正则化系数。结果在日志里看到 1.0000000000000001e-8，虽然差很小，但跟预期不一致。排查下来发现是 bash 里 1e-8 被当成字符串，Nextflow 解析时做了不精确的转换。

解决办法：在代码里用 Float.valueOf() 或 Double.parseDouble() 明确转换，并且设置一个可接受的精度比较逻辑：

params.regularization = Double.parseDouble(params.regularization as String)
if (params.regularization < 0) {
    error "regularization 不能为负数"
}

另外，别用 == 直接比较浮点数。我曾在条件分支里写过 if (params.rate == 0.1)，结果因为精度问题永远不相等。改成 Math.abs(params.rate - 0.1) < 1e-9 才正常。

类型强制转换与校验实践

说来说去，其实就两件事：明确预期类型，校验+转换一步到位。

我整理了一个常用的参数校验模板：

// 通用校验函数
def assertInt(val, name) {
    if (val instanceof Number && !(val instanceof Integer)) {
        error "'${name}' 是浮点数，需要整数"
    }
    return val.toInteger()
}

def assertFloat(val, name) {
    return val.toDouble()
}

// 使用示例
params.max_iter = assertInt(params.max_iter ?: 100, "max_iter")
params.epsilon   = assertFloat(params.epsilon ?: 1e-5, "epsilon")

把这个函数放在 lib/Validation.groovy 里，所有管道都能复用。别问我为什么还要单独建个文件——我当初把所有校验都写在 main.nf 里，后来管道复制多了，改一处得翻遍十几个文件。

再来个表格对比一下几种校验方式的优缺点：

方式	优点	缺点
手动 instanceof 检查	精确控制类型，可自定义错误消息	代码啰嗦，每个参数都要写
input 块类型声明	简洁，由 Nextflow 自动校验	只在 process 级别生效，不覆盖全局参数
自定义校验函数	可复用，集中管理	需要额外维护 lib 文件
外部 yaml 配置 + 类型 schema	适合大型项目，支持嵌套校验	引入外部依赖（如 yaml 解析）

我个人最推荐“自定义校验函数 + input 块声明”的组合，既保证入口严格，又让 process 里减少重复代码。

避坑指南

• 不要相信命令行传进来的字符串。哪怕看起来是个数字，背后可能是 " 100 "（带空格），或者 "1,000"（千分位分隔符）。我曾经因为用户传了个 --depth 1,000，程序直接拿 "1,000" 当字符串拼接路径，报了一个诡异的文件未找到错误。花了两小时才追踪到原因。
• 注意整数和浮点数的隐式转换。比如 params.threads = 4.0，虽然你用 threads as Integer 可以转过去，但建议直接报错拒绝——因为用户很可能打错了小数点。
• 浮点数比较用误差范围。前面说过，这里再强调一遍——别用 ==。
• 超大整数可能溢出。Nextflow 的整数默认是 Integer（32位），最大约 21 亿。如果你的参数是染色体位置或计数，可能超过这个范围。我有一回传基因组位置 250000000，结果超过了 Integer.MAX_VALUE，自动变成负数，导致索引报错。解决办法：明确声明为 Long 类型：params.position as Long。

流程图：数字参数从输入到使用的完整路径

下面这张图把整个过程串了一遍，从命令行参数进来，到校验、转换、传递给 process 并最终落入计算脚本：

实战：在 nextflow.config 里做类型约束

还有一个容易被忽略的地方——nextflow.config 文件。有些团队习惯把参数默认值写在配置文件里，但这里照样可以做类型约束：

params {
    epochs = 50
    batch_size = 64
    learning_rate = 0.01
    
    // 方式1：用 groovy 的类型断言
    checkType = {
        assert epochs instanceof Integer : "epochs 需为整数"
        assert learning_rate instanceof Double : "learning_rate 需为浮点数"
    }
    checkType()
}

不过要注意，nextflow.config 里的代码执行顺序跟 main.nf 不太一样。我个人更喜欢在 main.nf 的顶部统一做校验，更清晰，也更方便 debug。

结尾我还是那句话：类型校验做得越早，半夜被叫醒的概率越低。把校验写进你的管道模板里，一劳永逸。