命令行、配置与结构化日志

命令行程序的外部契约不仅是函数返回值，还包括参数、标准输出、标准错误、退出码、配置来源和日志字段。把这些全部写在 main 中会迅速变得难测。入口应只负责适配进程环境，核心命令接收显式输入并返回结构化结果。

一、学习目标

使用 FlagSet 实现多个子命令
定义默认值、配置文件、环境变量与参数优先级
区分用户输出和诊断日志
使用 slog 记录结构化上下文
稳定映射错误、信号与退出码

二、子命令与 FlagSet

标准库 flag 没有完整子命令框架，但可用独立 FlagSet 保持边界：

func runAdd(args []string, out, errOut io.Writer) error {
    fs := flag.NewFlagSet("add", flag.ContinueOnError)
    fs.SetOutput(errOut)
    title := fs.String("title", "", "task title")
    if err := fs.Parse(args); err != nil {
        return err
    }
    if strings.TrimSpace(*title) == "" {
        return ErrTitleRequired
    }
    return addTask(*title, out)
}

注入 Writer 而不是直接使用全局标准流，测试就能断言输出。ContinueOnError 让调用方掌握退出码，而不是由解析器直接退出进程。

三、配置优先级

本系列固定优先级：命令行参数 > 环境变量 > JSON 配置文件 > 默认值。每个字段同时记录来源，诊断时才能解释最终值从哪里来。

配置文件路径可由 --config 或平台默认目录确定。环境变量统一使用 STUDYTASKS_ 前缀。解析分为三步：读取原始来源、合并优先级、验证最终配置。不要在业务代码各处直接调用 os.Getenv，否则测试和优先级会散落。

秘密不写入普通日志或示例配置。即使 CLI 目前没有真实令牌，也应从设计上区分可公开配置与敏感值。

四、结构化日志

log/slog 将消息与字段分离：

logger.InfoContext(ctx, "task synchronized",
    "task_id", task.ID(),
    "attempt", attempt,
    "duration", elapsed,
)

字段名保持稳定、使用小写下划线，并避免高基数敏感数据。用户要求的 list 结果写 stdout；诊断与警告写 stderr 或日志处理器。这样管道可以消费数据，不会混入时间戳。

测试可注入自定义 Handler 收集记录，不必解析带颜色的人类文本。

五、退出码与错误展示

只有 main 调用 os.Exit，因为它会跳过 defer：

func main() {
    os.Exit(run(os.Args[1:], os.Stdout, os.Stderr))
}

run 将成功映射为 0，参数错误映射为 2，可预期业务失败映射为 3，内部或 I/O 失败映射为 1。具体数字不是行业强制标准，关键是文档化并保持稳定。

面向用户的错误简洁可操作，详细错误链进入诊断日志。不要输出两次同一个错误：底层返回，上层统一展示。

六、信号与生命周期

使用 signal.NotifyContext 把 Ctrl+C 或终止信号转换成 context：

ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt)
defer stop()

Windows 与 Unix 支持的信号集合不同，跨平台 CLI 只依赖共同语义。收到取消后停止接受新工作，等待有限时间清理，并返回明确退出状态。不要让后台 goroutine在 main 返回后寄希望于继续写文件。

七、从知识点到工程契约

本篇的示例最终要进入可维护的 Go 包，而不是停留在 main 中的一次性片段。先把目标写成调用者可以观察的契约：输入是否允许零值或 nil，返回值是否是快照，错误能否通过 errors.Is/As 分类，函数是否启动 goroutine、取得资源或修改共享状态。然后再选择结构体、接口、函数值或泛型；抽象形式必须服务于契约，而不是反过来决定需求。

可以用以下顺序把知识点落到工程代码：

在独立小函数中写出最小成功路径，并让 go test 能直接调用。
加入一个与“在深层函数调用 os.Exit，导致 defer 与测试失效”相关的失败样例，确认失败可观察且不会留下半完成状态。
把文件、网络、时间、环境或并发等外部因素改成显式依赖，测试使用临时目录、固定时钟或本地服务。
运行 gofmt、vet 和相关测试；涉及共享状态时追加 -race，涉及解析器时追加有上限的 fuzz。
最后再评估 API 是否需要导出。只在同一模块内部使用的能力保留在 internal，避免过早形成公共兼容负担。

审查代码时至少回答四个问题：谁拥有数据，谁允许修改，失败由谁处理，工作由谁停止。Go 的垃圾回收只解决不可达内存回收，不会替你关闭文件、取消请求、等待 goroutine 或恢复被覆盖的数据。只要其中一个问题没有答案，就先缩小函数或包的边界。

本篇最重要的能力是“使用 FlagSet 实现多个子命令”。不要用注释替代可执行约束：能由类型表达的就交给类型，能由构造或验证表达的就返回错误，能由测试观察的就保存回归用例。示例扩展到 StudyTasks 时，还要保持领域包不导入命令行、文件和 HTTP 细节。

八、验证策略与复盘

验证分为静态、动态和故障三层。静态层检查格式、模块图和分析器；动态层用正常输入证明结果；故障层主动制造取消、权限、损坏数据、超时或竞态。一次测试通过只能说明执行过的路径符合断言，不能证明所有输入都安全，因此需要让每条关键契约至少对应一个成功用例和一个反例。

建议保存下面的复盘记录：

项目	需要记录的证据
版本	`go version`、模块与 toolchain 指令
输入	最小正常值、零值、边界值和非法值
状态	调用前后数据、资源和 goroutine 的所有者
输出	返回值、错误链、stdout/stderr 与日志字段
失败	第一个失败点、清理动作和可恢复状态
工具	实际运行的 test、race、vet、benchmark 或 build 命令

完成验证后，用另一份干净临时目录重跑，不读取开发机的用户配置、缓存数据或真实网络。若测试只能按特定顺序成功，就说明状态隔离仍不完整。若为了让测试通过必须长时间 sleep，应改用 channel、WaitGroup、context 或可注入时钟表达确定的同步条件。

本篇可以用以下目标做验收：定义默认值、配置文件、环境变量与参数优先级；区分用户输出和诊断日志；使用 slog 记录结构化上下文。把它们逐项转成命令输出或断言，而不是写成“人工看起来正确”。当实现与预期不符时，先保存最小失败样例，再调整设计。

发布前再做一次反向审查：从调用方而不是实现内部出发，写出一个完全不知道具体类型和文件布局的使用示例；从故障点出发，假设进程在每个 I/O 之后被取消；从升级出发，假设下一版改变字段或默认值。若调用方必须知道未公开细节、故障会留下无法判断的状态，或升级只能覆盖旧数据，契约就还不完整。把这三个场景加入测试或文档，比继续增加抽象更有价值。

最后检查示例能否被复制到一份最小程序独立运行，所有导入、错误处理和清理是否完整。教学代码可以省略与主题无关的界面，却不能省略会改变正确性的 context、Close、边界检查或同步。对为了篇幅省略的部分要明确标注，不能让读者把伪代码误当成生产承诺。

九、StudyTasks 实践

实现六个子命令的 FlagSet 分派、统一 run 函数和配置合并器。为参数错误、环境覆盖、配置文件覆盖、stdout/stderr 分离、日志字段与 Ctrl+C 取消编写测试，不在包级读取环境。

完成本节后，不要只保存代码或 SQL。请同时保存执行命令、关键输出和失败案例；学习笔记真正有价值的部分，是能够说明输入、状态变化、输出以及失败后的恢复方式。

十、常见错误

在深层函数调用 os.Exit，导致 defer 与测试失效
每个包自行读取环境变量，配置优先级不可追踪
把用户数据和诊断日志都写 stdout
日志记录令牌、完整请求体或高基数敏感字段
解析器直接退出进程，无法测试错误路径

十一、练习与自测

实现参数、环境、文件、默认值四层合并并返回来源。
为每类错误建立稳定退出码测试。
注入 bytes.Buffer 测试 list 输出不含日志。
用自定义 slog Handler 断言 task_id 字段。

自测时应在干净的临时目录或临时数据库中重新执行，而不是依赖上一节遗留的状态。如果结果与预期不同，先记录实际输出，再缩小问题范围。

十二、官方资料

版本行为与二手文章不一致时，以本系列固定版本的官方文档、命令输出和可重复测试结果为准。

上一篇：文件、JSON、正则与时间下一篇：JSON 持久化、安全写入与仓储