Go os.Args 与 flag.FlagSet 怎样隔离子命令参数

入口先用 os.Args[1:] 去掉程序名，从剩余切片取出子命令名，再给每个子命令创建独立 flag.FlagSet，只把子命令后面的参数交给它的 Parse。这样不同子命令可以定义同名选项、不同默认值和独立帮助文本，不会混进全局 flag 状态。

官方文档：https://pkg.go.dev/flag#FlagSet

问题：两个子命令不能共用一份参数状态

假设一个小工具既有 pack，又有 inspect。pack 的 out 表示输出文件名，inspect 的 out 表示展示格式。如果把两者都注册到包级 flag 集合，就会遇到同名定义冲突，帮助文本也难以按任务区分。

我更倾向于让入口只负责选择任务，各个任务自己解释参数。这里借用一个最小配方展开：先给出完整可用的分派结构，再解释切片和帮助的边界。示例只打印解析后的计划，不实际打包或读取文件，也不声称是亲历运行记录。

最小配方：入口分派与独立 FlagSet

package main

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

func run(args []string, out, diagnostic io.Writer) error {
    // args 已去掉程序名，先检查再读取子命令。
    if len(args) == 0 {
        return fmt.Errorf("用法：app pack|inspect [参数]")
    }
    switch args[0] {
    case "help", "-h", "-help":
        fmt.Fprintln(out, "用法：app pack|inspect [参数]")
        return nil
    case "pack":
        fs := flag.NewFlagSet("pack", flag.ContinueOnError)
        fs.SetOutput(diagnostic)
        output := fs.String("out", "bundle.zip", "输出文件")
        fs.Usage = func() {
            fmt.Fprintln(diagnostic, "用法：app pack [选项] 文件")
            fs.PrintDefaults()
        }
        // 子命令名不进入 Parse，字段定义也仅属于 pack。
        if err := fs.Parse(args[1:]); err != nil {
            return err
        }
        if fs.NArg() != 1 {
            return fmt.Errorf("pack 需要一个位置参数")
        }
        fmt.Fprintf(out, "pack 输入=%s 输出=%s\n", fs.Arg(0), *output)
        return nil

    case "inspect":
        fs := flag.NewFlagSet("inspect", flag.ContinueOnError)
        fs.SetOutput(diagnostic)
        output := fs.String("out", "text", "展示格式")
        fs.Usage = func() {
            fmt.Fprintln(diagnostic, "用法：app inspect [选项] 文件")
            fs.PrintDefaults()
        }
        // 同名 out 在另一个集合中独立定义，默认值不串用。
        if err := fs.Parse(args[1:]); err != nil {
            return err
        }
        if fs.NArg() != 1 {
            return fmt.Errorf("inspect 需要一个位置参数")
        }
        fmt.Fprintf(out, "inspect 输入=%s 格式=%s\n", fs.Arg(0), *output)
        return nil
    default:
        return fmt.Errorf("未知子命令：%s", args[0])
    }
}

func main() {
    // 程序名由入口去掉，帮助请求按正常结束处理。
    err := run(os.Args[1:], os.Stdout, os.Stderr)
    if err == nil || errors.Is(err, flag.ErrHelp) {
        return
    }
    fmt.Fprintln(os.Stderr, err)
    os.Exit(2)
}

两个分支分别创建新 FlagSet，因此 out 可以各有含义。ContinueOnError 使解析错误返回给调用方，不会由子命令解析器直接退出进程；退出策略放在 main，后续也方便将解析逻辑用于测试或其他入口。

示例为了保持直观，两个分支保留少量重复代码。我会在子命令增多后再抽取共同的帮助格式，而不是一开始就用大量框架隐藏参数归属。当前关键点是每次调用都创建新的解析集合和参数变量。

关键边界：Parse 只接收子命令后面的切片

os.Args[0] 是程序名；main 传入 os.Args[1:] 后，run 的 args[0] 才是子命令。因此分支里的 fs.Parse(args[1:]) 再去掉子命令。两次切片分别发生在不同层，不能把 run 内的 args 和原始 os.Args 混为一谈。

标准 flag 在第一个非选项参数之前停止，或在遇到 -- 后停止。若把子命令名也传进它，解析通常会立即停在这个名字上，后面的选项就不会按预期生效。这是切片范围错误，不是需要再调用一次全局 flag.Parse。

# 假设已将示例编译为 app；选项放在位置参数前。
./app pack -out archive.zip notes.txt
./app inspect -out json notes.txt

# 使用 --，把以减号开头的文件名作为位置参数。
./app pack -- -draft.txt

# 子命令帮助只列出自己的参数。
./app inspect -h

这些命令供读者按需尝试，本文没有执行它们。pack 和 inspect 的 out 应分别得到文件名和格式值；-- -draft.txt 应保留减号开头的文件名。若写成 pack notes.txt -out archive.zip，flag 会停在 notes.txt，后面的内容仍是余项，本例的位置参数数量检查会拒绝它。

变体：全局参数与子命令帮助

需要全局选项时，可以先解析全局前缀，再用全局 FlagSet 的 Args 获取包含子命令的剩余参数。下面是函数内部片段，args、out 和 diagnostic 与前述入口含义一致：

// 函数内部片段：先解析全局前缀，再把剩余参数交给子命令。
global := flag.NewFlagSet("app", flag.ContinueOnError)
global.SetOutput(diagnostic)
verbose := global.Bool("verbose", false, "详细信息")
if err := global.Parse(args); err != nil {
    return err
}
// 全局解析在子命令这个非选项参数前停止，剩余切片仍包含子命令名。
_ = verbose
return run(global.Args(), out, diagnostic)

这种配方对应 app -verbose pack ... 的布局。全局解析在 pack 前停止，因此全局选项应写在子命令前。若产品要求全局选项能出现在任意位置，需要专门设计解析规则，不能假定标准 flag 会自动穿插扫描所有位置。

每个集合使用自己的 Usage 和 PrintDefaults。未自行定义 h 或 help 时，帮助请求会触发帮助并返回 ErrHelp；main 将它视为正常结束，避免帮助输出之后再显示“执行失败”。本例全局 help 只展示入口用法，子命令 -h 才展示该命令的详细选项。

常见坑和采用建议

同一个 FlagSet 内重复定义名字会 panic，不同 FlagSet 之间则允许同名。不要通过修改全局 flag.CommandLine 来反复切换子命令，这会让参数归属与帮助行为更难理解。并行或重复调用解析函数时，新建局部集合也能避免复用旧值造成误判。

ContinueOnError 并不表示默认完全静默：解析器仍可能向它的输出目标写诊断信息。示例通过 SetOutput 指定目标，再由 main 补充返回错误；如果希望避免重复诊断，可在自己的封装里统一错误显示责任，不要把“返回错误”和“没有打印”当成一回事。

当只有几个子命令、选项规则简单时，这个方案足够直接。若需要深层命令、别名、补全或复杂的选项继承，再考虑额外框架。无论用什么工具，都应明确哪一层拥有参数、帮助和退出码。

相关问题

为什么选项放在文件名后面就不生效？

标准 flag 遇到第一个非选项参数会停止解析。把选项写在位置参数前，或明确采用支持其他布局的解析方案。

两个子命令都叫 out 会冲突吗？

在不同 FlagSet 中不会；如果重复注册在同一集合中则会 panic。

为什么函数要接收 args，而不是自己读取 os.Args？

显式参数能让入口层负责切分，解析函数只处理自己的输入，也更便于用固定切片复用与测试。

原始参数说明：https://pkg.go.dev/os#Args