Go go-flags 的 optional 与 optional-value 有什么区别

给 Go 命令行增加一个“可选值”选项时，我最容易先想到的是把两个标签都当成“参数可有可无”。但在 github.com/jessevdk/go-flags 里，它们分工很明确：optional 决定值能不能省略，optional-value 决定值省略后实际写入什么。前者是语法边界，后者是裸参数的业务值。

官方地址：https://pkg.go.dev/github.com/jessevdk/go-flags

最短结论是：没有参数时看 default；写成 --mode 时看 optional-value；写成 --mode=fast 时使用用户显式传入的 fast。如果只设置 optional-value 而没有让参数可选，设计意图就不完整。

先把三种输入放到同一张表里

我们用一个字符串选项表示运行模式。为了让“参数缺省”和“参数值缺省”可以被观察出来，给它同时设置 default、optional 和 optional-value：

package main

import (
    "fmt"

    "github.com/jessevdk/go-flags"
)

type options struct {
    // 没有 --mode 时使用 off；裸写 --mode 时使用 auto。
    Mode string `long:"mode" description:"运行模式" default:"off" optional:"true" optional-value:"auto"`
}

func parse(args []string) error {
    var opts options

    // ParseArgs 只解析传入的参数，便于把三种输入分别交给解析器。
    _, err := flags.ParseArgs(&opts, args)
    if err != nil {
        return err
    }
    fmt.Printf("mode=%q\n", opts.Mode)
    return nil
}

在这个定义下，三个命令行状态可以这样理解：

optional 控制的是参数语法，不是默认业务值

官方字段标签说明里，optional 的含义是：该选项的参数可以省略；一旦要传入显式值，只能使用 --option=argument 这种写法。也就是说，设置它以后，--mode=fast 是显式值，--mode 则进入“没有跟随值”的分支。

这里有一个很容易误读的地方：optional:"true" 不会自动决定裸参数应该变成什么字符串。它只是允许裸参数通过解析。至于最终字段里得到什么，需要由 optional-value 提供，或者由类型本身的解析规则决定。对字符串选项来说，显式给出一个清楚的 optional-value 更容易维护。

type options struct {
    // 显式值必须写成 --format=json，不能依赖下一个独立参数。
    Format string `long:"format" optional:"true" optional-value:"text" default:"plain"`
}

// 这三种调用分别表达“未启用”“启用默认格式”和“启用指定格式”。
var examples = [][]string{
    {},
    {"--format"},
    {"--format=json"},
}

因此，不要把 optional 理解成“允许 --format json 和 --format=json 两种写法”。这个标签的边界恰恰是：可选值只能通过等号跟在同一个长选项后面，裸选项和下一个位置参数不会自动组成一对。

optional-value 只处理“裸参数出现”的那一刻

optional-value 是另一层：当一个允许省略值的选项被写出来，却没有携带显式值时，解析器把这个标签的内容当作该次出现的值。它不是字段的初始值，也不会覆盖用户已经写出的等号值。

这也是它和 default 的分界：

• default：选项完全没有出现时使用。
• optional-value：选项出现了，但没有显式参数时使用。
• 显式值：用户写出的 --mode=value 优先表达本次选择。

对于切换型命令行设计，这种组合很实用。例如 --color 可以表示启用并使用 auto，--color=never 又能把策略写死；而用户不写该选项时，则保持 default:"never"。关键是把三种状态写进帮助文案和文档，而不是只给结构体贴标签。

一个可以直接套用的配置方式

如果命令需要“未指定、启用默认、指定模式”三态，我会按下面的顺序设计：

package main

import (
    "fmt"

    "github.com/jessevdk/go-flags"
)

type options struct {
    // default 是选项未出现时的状态；optional-value 是裸参数的状态。
    Mode string `long:"mode" description:"运行模式：off、auto 或指定名称" default:"off" optional:"true" optional-value:"auto"`
}

func main() {
    var opts options

    // ParseArgs 返回未被选项消费的剩余参数，错误必须在业务逻辑前处理。
    rest, err := flags.ParseArgs(&opts, []string{"--mode=fast", "input.txt"})
    if err != nil {
        panic(err)
    }
    fmt.Printf("mode=%s rest=%v\n", opts.Mode, rest)
}

实践中再补三点：

1. 如果值域有限，解析后再对 off、auto 和自定义值做业务校验，不要把“参数可省略”误当成“任何值都合法”。
2. 如果是切片或 map，官方文档允许重复指定 optional-value；要先想清楚裸参数每出现一次是追加一个值，还是会造成覆盖。
3. 短选项与长选项不要混淆测试重点：文档对可选参数的等号约束主要针对长选项表达式，发布帮助时应把真实可用写法展示出来。

常见疑问

只设置 optional-value，不设置 optional 可以吗？

不建议这样设计。optional-value 描述的是“可选参数在没有显式值时的值”，而 optional 才明确打开参数值可省略的语法。两者应根据同一个交互意图配套使用。

为什么裸写 --mode 后没有拿到 default？

因为选项已经出现了。default 只覆盖选项完全缺席的情况；裸参数的缺省值属于 optional-value 的职责。

记住一句话就够了：optional 解决“能不能不写值”，optional-value 解决“不写值时写入什么”，default 解决“选项根本没出现时保留什么”。