综合实战与进阶路线

综合实战不是再堆一组新 API，而是把前面建立的契约放在同一个项目中验证：领域不变量能否穿过 JSON 与 HTTP，取消能否到达最底层，错误是否保留原因，CLI 是否稳定，发布产物能否在干净环境恢复数据。

一、学习目标

落实单向依赖与进程入口边界
完成六个命令和版本化 JSON 仓储
实现可取消、有限并发的本地 HTTP 同步
建立功能、失败、竞态与恢复测试矩阵
形成安全、性能、发布和回滚检查表

二、最终架构

项目结构：

studytasks-go/
  go.mod
  cmd/studytasks/main.go
  internal/domain/
    task.go
    service.go
  internal/store/
    json.go
    snapshot.go
  internal/syncclient/
    client.go

domain 不导入 store、HTTP、flag 或 slog。应用服务声明最小仓储接口；入口读取配置并注入 JSONRepository、HTTP Client、时钟与 logger。每个包能独立说明自己的输入、输出、所有权和错误。

三、命令闭环

add --title：验证标题、生成 ID、UTC 时间并保存。
list --status：稳定排序，只向 stdout 输出结果。
done --id：保持错误链并拒绝不存在任务。
delete --id：显式确认或 --yes，保存新快照。
export --output：输出版本化 JSON，不覆盖未知文件。
sync --endpoint：带幂等键、超时、取消和并发上限。

所有修改命令遵循“加载—验证—产生新状态—安全保存”。任一步失败都不把内存中的半完成状态当作持久化成功。

四、测试矩阵

领域测试覆盖空标题、状态转换和重复完成；仓储测试覆盖损坏 JSON、未知版本、替换失败和备份恢复；CLI 测试覆盖参数、输出流与退出码；HTTP 测试覆盖超时、限流、超大响应和取消；并发测试在 -race 下验证上限与退出。

端到端冒烟使用临时目录和 httptest.Server，按 add→list→done→export→sync→delete 执行。每一步检查文件、输出和退出码，而不是只看最后进程是否为 0。

五、安全与可靠性

输入限制包括标题长度、JSON 文件大小、响应体大小、URL scheme 和数据目录。日志不记录完整任务正文、令牌或文件内容。HTTP 只接受显式配置的 http 本地测试或生产 https，重定向策略限制跨主机敏感 Header。

JSON 仓储声明单写者，损坏时拒绝自动覆盖。信号取消会停止新同步、等待 worker、关闭响应并保留本地快照。panic 只在入口记录并返回失败，不继续复用可能损坏的状态。

六、性能与可观测性

先建立基准：加载 1、1000、10000 个任务的时间和分配；List 稳定排序；同步不同并发度下的吞吐与错误率。优化以真实 profile 为依据，避免为了减少一次分配破坏 API 所有权。

日志字段至少包含命令、任务 ID（可安全时）、耗时、尝试次数和错误类别。不要把日志当指标系统；CLI 的最小可观察目标是能复现某次操作选择了哪份配置、在哪个阶段失败以及是否保存成功。

七、交付检查表

test -z "$(gofmt -l .)"
go mod tidy -diff
go vet ./...
go test -race -cover ./...
go build -trimpath ./cmd/studytasks

随后交叉编译、生成校验和，在无源码环境运行冒烟，并验证旧快照升级和备份恢复。发布说明列出 Go 版本、数据格式版本、配置变化、已知限制和回滚条件。所有检查都通过后才标记版本。

八、进阶路线

完成项目后可沿三条路线深入：

语言与运行时：编译器、逃逸、调度器、GC、内存模型。
服务工程：标准库 HTTP Server、OpenTelemetry、数据库与分布式一致性。
工具与平台：模块代理、供应链证明、跨平台安装器和持续交付。

不要同时引入数据库、Web 框架、消息队列和微服务。每次只替换一个外部边界，保留测试矩阵，对比新方案带来的能力与成本。

九、最终验收矩阵

综合项目完成后，用下面的矩阵做一次不依赖源码上下文的验收：

场景	操作	必须观察的结果
首次运行	空数据目录执行 list	创建策略明确，不产生损坏文件
正常写入	add、done、delete	状态、退出码和 JSON 快照一致
输入失败	空标题、坏 ID、未知参数	非零退出且旧数据不改变
文件失败	只读目录、截断 JSON	保留错误链，不覆盖可恢复数据
网络失败	超时、429、损坏响应	有界重试、context 取消、无泄漏
并发失败	worker 中途返回错误	停止新工作并等待已启动 goroutine
信号退出	同步中触发 Ctrl+C	有限时间退出，快照保持可读
升级回滚	新旧数据格式切换	备份、迁移与回滚条件可执行

验收者只拿到归档、校验和、README 和一个本地测试服务地址，不使用开发目录中的配置。每个失败场景都保存命令、stdout、stderr、退出码、日志和数据文件校验和。若某项只能通过阅读源码判断，就说明可观察性或文档仍不够。

最后审查依赖与供应链：go.mod 只有标准库基线，构建信息指向正确模块和版本，归档不含编辑器文件、真实任务数据或秘密。三平台产物分别命名，Windows 后缀、Unix 执行位和换行说明清楚；交叉编译未运行的平台明确标记“待真实平台烟测”，不夸大验证范围。

十、从知识点到工程契约

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

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

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

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

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

十一、验证策略与复盘

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

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

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

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

本篇可以用以下目标做验收：完成六个命令和版本化 JSON 仓储；实现可取消、有限并发的本地 HTTP 同步；建立功能、失败、竞态与恢复测试矩阵。把它们逐项转成命令输出或断言，而不是写成“人工看起来正确”。当实现与预期不符时，先保存最小失败样例，再调整设计。

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

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

十二、StudyTasks 实践

从空临时目录重建完整项目，执行所有质量命令、端到端冒烟、竞态检测、限时 fuzz、三平台构建和校验和生成。再故意制造损坏 JSON、HTTP 超时和 Ctrl+C，证明程序以文档化方式失败并可恢复。

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

十三、常见错误

综合项目中绕过包边界直接访问内部字段
只测试成功路径，不测试保存失败、取消和恢复
用无界 goroutine 提高看似吞吐量
日志泄露任务正文、令牌或本地路径中的敏感信息
发布新数据格式却没有备份与回滚条件

十四、练习与自测

画出一次 sync 从 CLI 到 HTTP 的 context、错误和日志传播路径。
完成 10000 个任务的加载、排序和同步基准。
编写一次发布演练记录，包括校验和、烟测与回滚。
选择一个外部边界替换方案，并列出能力、复杂度和迁移测试。
让另一台干净机器仅根据 README 完成安装与冒烟。

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

十五、官方资料

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

上一篇：构建、交叉编译与发布