包、模块、工作区与依赖

包是 Go 代码复用和信息隐藏的基本单元，模块负责版本化一组包，工作区只帮助本地同时开发多个模块。把三者混在一起，会出现循环导入、巨大 common 包、无法独立构建和本地正常而 CI 失败等问题。

一、学习目标

按变化原因而不是文件类型拆分包
理解导出标识符、internal 与包初始化
维护模块依赖、版本选择和校验和
安全使用 replace 与工作区
建立 StudyTasks 的单向依赖结构

二、包边界与命名

同一目录中的非测试 Go 文件属于同一包。大写开头的标识符可被其他包访问，但“可导出”不代表“应该公开”。公共 API 越小，兼容成本越低。

包名应简短并表达提供的能力，例如 domain、store、syncclient，调用处读起来是 domain.Task、store.Open。避免 utils、common 这类没有所有权的垃圾箱，也避免包名重复类型含义，如 task.TaskManager。

Go 禁止循环导入。遇到循环时应重新判断职责或把最小稳定契约下沉，而不是通过全局变量、回调注册表掩盖结构问题。

三、internal 与入口包

位于 internal 下的包只能被其父目录树中的代码导入，适合表达仓库内部 API：

cmd/studytasks/main.go
internal/domain/task.go
internal/store/json.go
internal/syncclient/client.go

main 包只负责进程级工作：解析参数、读取配置、创建依赖、映射退出码和处理信号。业务规则放在可测试的普通包中。不要让 init 隐式连接网络、读取配置或启动 goroutine；这会让测试顺序和导入本身带有副作用。

四、模块版本与最小版本选择

go.mod 记录直接依赖和模块语义，go.sum 记录已下载模块内容的校验。Go 使用最小版本选择：构建列表为每个模块选择依赖图中要求的最高版本，不会自动追逐最新版本。

go list -m all
go mod graph
go get example.com/lib@v1.2.3
go mod tidy
go mod verify

升级依赖前先阅读变更并运行完整测试。不要手工删除 go.sum 中“看起来没用”的行；让 go mod tidy 根据源码、测试和构建标签整理。

五、replace 与工作区风险

replace 能指向本地目录或其他模块版本，适合临时调试 fork，但发布前必须确认消费者可解析：

replace example.com/lib => ../lib

本地路径不会被上传到模块代理，离开当前目录结构就失效。多模块开发优先用 go.work 表达本地组合，并在 GOWORK=off 下验证发布输入。不要提交指向个人目录的 replace，也不要用 replace 长期隐藏上游版本问题。

六、依赖方向与接口位置

Go 接口通常由使用方定义。domain 不需要提前声明一个包含所有存储操作的巨大接口；应用服务可声明它实际需要的最小能力：

type TaskReader interface {
    Get(context.Context, domain.TaskID) (domain.Task, error)
}

具体 JSON 仓储实现自然满足接口，无需显式声明。这样内层模型不依赖外层 I/O，测试也可提供轻量 fake。接口不是为了每个结构体都配一个抽象，而是为了隔离变化和表达调用方需求。

七、从知识点到工程契约

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

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

在独立小函数中写出最小成功路径，并让 go test 能直接调用。
加入一个与“创建无边界的 utils/common 包”相关的失败样例，确认失败可观察且不会留下半完成状态。
把文件、网络、时间、环境或并发等外部因素改成显式依赖，测试使用临时目录、固定时钟或本地服务。
运行 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 或可注入时钟表达确定的同步条件。

本篇可以用以下目标做验收：理解导出标识符、internal 与包初始化；维护模块依赖、版本选择和校验和；安全使用 replace 与工作区。把它们逐项转成命令输出或断言，而不是写成“人工看起来正确”。当实现与预期不符时，先保存最小失败样例，再调整设计。

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

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

九、StudyTasks 实践

把 StudyTasks 拆成 cmd 与三个 internal 包，运行 go list -deps ./cmd/studytasks 检查依赖。为读取任务定义一个最小使用方接口，并用内存 fake 测试应用服务，确认领域包不导入文件或 HTTP 包。

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

十、常见错误

创建无边界的 utils/common 包
在 init 中执行网络连接、读配置或启动后台任务
提交指向个人相邻目录的 replace
依赖 go.work 才能构建发布模块
由实现方定义巨大接口，迫使调用者依赖不需要的方法

十一、练习与自测

用 go list -json 查看一个包的直接导入和测试导入。
制造循环导入，再通过重新分配职责消除它。
临时创建本地 replace，随后在干净目录验证为什么失败。
把一个五方法接口缩成某个调用者真正需要的两个方法。

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

十二、官方资料

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

上一篇：控制流、函数与错误设计下一篇：结构体、方法、接口与组合