Go flag.FlagSet 怎么为子命令分别定义参数

Go 的多子命令程序，最稳妥的做法不是把所有选项都挂到全局 flag.CommandLine，而是让每个子命令拥有自己的 flag.FlagSet。先取出 os.Args[1] 作为命令名，再把剩余参数交给对应的 FlagSet 解析，参数定义、默认值、帮助文本和错误输出就能保持在同一条边界内。

核心写法是“一条子命令一个 FlagSet”：用 flag.NewFlagSet 创建解析器，用 Parse(args) 只解析该命令的参数；需要让上层决定如何退出时，选择 flag.ContinueOnError。

先按子命令切开参数边界

FlagSet 的价值是提供一组独立的 flag。下面的示例把 serve 和 export 分开：前者只认识 -port，后者只认识 -out。路由层只负责找出子命令，不把后续参数提前注册到全局集合里。

package main

import (
    "errors"
    "flag"
    "fmt"
    "os"
)

func main() {
    if err := run(os.Args[1:]); err != nil {
        fmt.Fprintln(os.Stderr, err)
        os.Exit(1)
    }
}

func run(args []string) error {
    if len(args) == 0 {
        return errors.New("缺少子命令：serve 或 export")
    }

    // 子命令只取第一个位置参数，避免把后续选项误当成路由信息。
    command, rest := args[0], args[1:]
    switch command {
    case "serve":
        fs := flag.NewFlagSet("serve", flag.ContinueOnError)
        port := fs.Int("port", 8080, "监听端口")
        // 只解析 serve 的参数，未知选项不会进入 export 的解析器。
        if err := fs.Parse(rest); err != nil {
            return fmt.Errorf("serve 参数错误：%w", err)
        }
        if *port  65535 {
            return fmt.Errorf("serve 端口超出范围：%d", *port)
        }
        fmt.Printf("serve port=%d\n", *port)
        return nil
    case "export":
        fs := flag.NewFlagSet("export", flag.ContinueOnError)
        out := fs.String("out", "result.json", "导出文件")
        if err := fs.Parse(rest); err != nil {
            return fmt.Errorf("export 参数错误：%w", err)
        }
        if *out == "" {
            return errors.New("export 输出文件不能为空")
        }
        fmt.Printf("export out=%s\n", *out)
        return nil
    default:
        return fmt.Errorf("未知子命令：%s", command)
    }
}

这里的关键不是 switch 本身，而是每个分支都创建了新的 FlagSet。fs.Parse(rest) 接收的是去掉子命令后的切片，因此 serve -port 9090 不会让 export 看到 -port。如果命令还带位置参数，可在解析后用 fs.Args() 读取；不要把位置参数再混回全局路由。

把错误输出和输入校验放在同一条防线

默认的错误处理策略可能在解析失败时直接退出，这对库代码、测试或需要统一返回错误的 CLI 不够灵活。创建 FlagSet 时使用 flag.ContinueOnError，再用 SetOutput 和自定义 Usage 指定帮助及错误的出口，调用方就能记录、包装或决定退出时机。

func newServeFlags(out io.Writer) (*flag.FlagSet, *int) {
    fs := flag.NewFlagSet("serve", flag.ContinueOnError)
    fs.SetOutput(out)
    fs.Usage = func() {
        // 帮助只描述参数，不打印令牌、密码等运行时值。
        fmt.Fprintln(out, "用法：tool serve -port 8080")
        fs.PrintDefaults()
    }
    port := fs.Int("port", 8080, "监听端口")
    return fs, port
}

func parseServe(args []string, out io.Writer) (int, error) {
    fs, port := newServeFlags(out)
    // ContinueOnError 让语法错误回到调用方，而不是在这里退出进程。
    if err := fs.Parse(args); err != nil {
        return 0, fmt.Errorf("serve 参数无法解析：%w", err)
    }
    if fs.NArg() != 0 {
        return 0, fmt.Errorf("serve 不接受多余位置参数：%s", fs.Arg(0))
    }
    if *port  65535 {
        return 0, fmt.Errorf("serve 端口必须在 1 到 65535 之间")
    }
    return *port, nil
}

示例中的 out 需要引入 io。把输出目标作为参数传入，测试时可以使用 bytes.Buffer，正式运行时传 os.Stderr。还要注意：Parse 成功只表示参数格式正确，不表示业务值合理，所以端口范围、路径是否为空、文件是否可写等检查应紧跟其后。

常见误区与复查清单

• 不要在包级变量初始化时为所有子命令注册同名 flag，否则测试和多命令组合容易共享状态。
• 不要把 ContinueOnError 当成业务校验器，它只改变解析失败的处理方式。
• 若允许位置参数，明确记录 fs.NArg() 和 fs.Args() 的预期，不要静默忽略尾部输入。
• 日志只记录参数名和错误类别；路径、令牌或连接串可能包含敏感信息，不能原样回显。

落地时可以按“命令路由是否唯一、FlagSet 是否独立、Parse 是否只吃当前切片、错误是否可返回、业务值是否复查”五项检查。这样即使未来增加 migrate 或 inspect，也只需新增一条局部参数边界，不会改动已有命令的注册状态。

相关问题

FlagSet.Parse 会解析子命令之后的所有参数吗？

不会自动读取全局参数；它只解析传给它的 []string。通常应把 os.Args[2:] 或路由层得到的剩余切片传入。

什么时候应该使用 flag.ExitOnError？

只有当当前命令允许解析失败立即结束进程，并且不需要由上层统一处理错误时才适合。可复用函数和测试通常更适合 ContinueOnError。

为什么 Parse 成功后还要检查 NArg？

因为非 flag 参数会保留在 Args() 中。检查 NArg() 可以阻止拼写错误或未预期的尾部输入被静默忽略。