Go 的 flag 包默认不支持位置参数（非 flag 参数）的 usage 自动描述；需通过自定义 flag.Usage 函数，结合 flag.PrintDefaults()，才能输出包含必需位置参数说明的完整帮助信息。
go 的 flag 包默认不支持位置参数（非 flag 参数）的 usage 自动描述；需通过自定义 `flag.usage` 函数，结合 `flag.printdefaults()`，才能输出包含必需位置参数说明的完整帮助信息。
在 Go 中，flag 包原生仅管理以 - 或 -- 开头的命令行选项（即 flag 参数），而对位置参数（如 ./cmd arg1 arg2 中的 arg1）完全无感知。因此，直接调用 flag.Usage() 时，它只会打印已注册 flag 的说明（若未注册任何 flag，则输出为空），不会、也无法自动推断或展示对位置参数的要求——这正是原始代码中 Usage of ./args: 后一片空白的根本原因。
要提供专业、一致且符合 Unix 习惯的 usage 提示（例如 Usage: ./args [OPTIONS]
✅ 正确做法：注册自定义 Usage 函数
package main
import (
"flag"
"fmt"
"os"
)
func main() {
// Step 1: 自定义 Usage 函数
flag.Usage = func() {
fmt.Fprintf(os.Stderr, "Usage: %s [OPTIONS] <argument>\n", os.Args[0])
fmt.Fprintln(os.Stderr, "Arguments:")
fmt.Fprintln(os.Stderr, " <argument>\tRequired input value (e.g., filename or ID)")
fmt.Fprintln(os.Stderr)
fmt.Fprintln(os.Stderr, "Options:")
flag.PrintDefaults() // 自动打印所有已定义 flag 的格式化说明
}
// Step 2: 定义可选 flag（可选，但体现完整性）
verbose := flag.Bool("verbose", false, "enable verbose logging")
timeout := flag.Duration("timeout", 30*time.Second, "connection timeout")
// Step 3: 解析 flag（位置参数仍通过 flag.Args() 获取）
flag.Parse()
// Step 4: 验证位置参数
if len(flag.Args()) != 1 {
fmt.Fprintln(os.Stderr, "Error: exactly one positional argument is required")
flag.Usage()
os.Exit(1)
}
arg := flag.Args()[0]
if *verbose {
fmt.Printf("Verbose mode enabled, processing: %s\n", arg)
}
fmt.Println("Processed:", arg)
}? 关键要点说明
- flag.Usage 是一个函数变量：赋值后，flag.Parse() 在遇到未知 flag（如 -unknown）或调用 flag.Usage() 时会自动执行该函数；
- 务必使用 os.Stderr 输出：符合 CLI 工具规范，确保错误/帮助信息不与标准输出混淆；
- flag.PrintDefaults() 是核心助手：它按 flag.String() / flag.Bool() 等注册顺序，自动渲染带缩进、类型、默认值和注释的 flag 列表，避免重复造轮子；
-
位置参数描述需手动编写：在 flag.Usage 中显式说明
、[OPTIONAL_ARG] 等占位符含义，并注明必选/可选、类型及示例； - 验证逻辑保持独立：flag.Parse() 只负责 flag 解析；位置参数校验（如 len(flag.Args()) != 1）必须在解析后显式编写，并主动触发 flag.Usage()。
⚠️ 注意事项
- 不要省略 os.Exit(1)：在错误路径中调用 flag.Usage() 后必须退出，否则程序会继续执行（可能 panic 或产生意外行为）；
- 避免在 flag.Usage 中调用 os.Exit()：它仅用于展示帮助，退出应由调用方控制，以保证测试友好性（如单元测试中可捕获输出而不终止进程）；
- 若项目复杂，建议将 flag.Usage 提取为独立函数（如 printUsage()），提升可读性与可测试性。
通过以上方式，你的 Go CLI 工具即可输出结构清晰、专业可靠的 usage 信息，既兼容 flag 生态，又明确传达位置参数契约，真正实现“不重复造轮子，也不妥协表达力”。
