Go 命令行 flag 参数缺失时怎么返回可读帮助而不是 panic

如果 Go 命令行工具把必填参数直接交给默认的 flag.CommandLine，参数缺失或格式错误时，程序往往会打印一段信息后直接结束；如果后面又对空字符串做了不安全处理，还可能出现 panic。更稳妥的做法是创建 flag.NewFlagSet(name, flag.ContinueOnError)，让解析错误返回给调用方，再由 main 统一输出 Usage 和决定退出码。

把“参数没传”和“程序内部出错”分开：flag 负责识别命令行错误，业务代码负责校验必填值，main 负责把结果映射成可读输出与稳定退出码。

先把 flag 的错误处理从默认退出改成可观察的返回值

默认 FlagSet 适合很小的工具，但它把错误处理策略绑定得比较紧。需要被脚本调用、需要自定义提示，或者希望测试解析函数时，应该单独创建 FlagSet，并把输出重定向到同一个缓冲区。这样解析函数不负责退出进程，调用方也能看到实际返回的错误类型。

package main

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

func parseArgs(args []string, out io.Writer) (string, error) {
	fs := flag.NewFlagSet("report", flag.ContinueOnError)
	fs.SetOutput(out) // 解析错误和帮助信息都写到调用方指定的输出
	fs.Usage = func() {
		fmt.Fprintln(out, "用法：report -input 文件") // 先给用户最短可执行提示
		fs.PrintDefaults() // 保留每个 flag 的默认说明
	}
	input := fs.String("input", "", "待读取的输入文件")
	if err := fs.Parse(args); err != nil {
		return "", err // 不在这里 os.Exit，让 main 决定退出码
	}
	if *input == "" {
		return "", errors.New("缺少必填参数 -input") // 业务必填校验放在 Parse 之后
	}
	return *input, nil
}

func main() {
	input, err := parseArgs(os.Args[1:], os.Stderr)
	if err != nil {
		fmt.Fprintln(os.Stderr, "参数错误：", err)
		os.Exit(2) // 2 表示调用方式不正确，便于脚本识别
	}
	fmt.Println("准备读取：", input)
}

这里的关键不是把所有错误包装成新字符串，而是保留“解析层”和“业务层”的边界。未知 flag、整数格式错误等会在 Parse 阶段返回；-input 没有传值则由业务校验返回。两者都可以使用同一份 Usage，但后续如果要记录日志或做测试，仍然能知道错误来自哪一层。

参数缺失、未知参数和 -h 应该分别怎么处理

ContinueOnError 的价值在于把控制权交回调用方。未知参数或值格式不对属于用法错误，通常返回非 nil error；用户输入 -h 或 -help 时，如果没有自定义同名 flag，标准库会返回 flag.ErrHelp。这类请求应该展示帮助并以成功状态结束，不要把它记录成故障。

可以在 main 中显式区分帮助分支：

input, err := parseArgs(os.Args[1:], os.Stderr)
if err != nil {
	if errors.Is(err, flag.ErrHelp) {
		return // 帮助是用户主动请求，不把它当作失败
	}
	fmt.Fprintln(os.Stderr, "参数错误：", err) // 其他解析或必填校验错误写到错误输出
	os.Exit(2) // 保持用法错误的退出码稳定
}
_ = input // 解析成功后再进入真正的业务逻辑

如果希望帮助信息使用退出码 0，而参数错误使用退出码 2，就要让 main 拥有最终决策权。不要在 Usage 函数里调用 os.Exit，否则调用方无法复用解析逻辑，也难以在测试中检查错误输出。

把 Usage、错误信息和退出码组合成稳定契约

命令行工具的可读性来自三件事：用户知道正确写法，错误信息指出当前问题，进程退出码能被脚本识别。可以按下面的契约整理：

还要注意解析顺序：标准 flag 在遇到第一个非 flag 参数后会停止继续解析，因此位置参数和选项参数混用时，要先确定自己的命令格式。多子命令场景可以为每个子命令创建独立的 FlagSet，不要让全局 flag 的 Usage 和错误码规则互相覆盖。

常见误区：为什么只判断 err 还不够

• 把所有非 nil error 都当成故障：flag.ErrHelp 是帮助请求，应单独处理。
• 只依赖默认 Usage：它能列出 flag，但不一定能说明必填业务条件，缺少参数时仍应补充具体提示。
• Parse 前就读取参数：此时变量还只有默认值，必填校验应该放在 Parse 成功之后。
• 在解析函数内退出：库函数调用 os.Exit 会让上层失去重试、测试和自定义退出码的机会。

相关问题

为什么不直接使用 flag.Parse？小工具可以直接用；当需要复用解析逻辑、测试错误输出或控制退出码时，独立 FlagSet 更合适。

缺失参数应该返回 ErrHelp 吗？不应该。ErrHelp 表示用户主动请求帮助；缺失必填值是用法错误，应返回普通错误并配合非零退出码。

官方 flag 包文档说明了 FlagSet、Usage 和 ErrHelp 的职责；实际项目只要坚持“解析返回、业务校验、main 决策”三层分工，参数没传时就能得到可读帮助，而不是不可控的 panic。