微服务中直接在根目录执行go mod init会将所有内部包耦合为单一模块，导致版本锁定混乱、测试隔离失效、import cycle及路径解析失败；正确做法是按逻辑子域划分独立模块路径，并通过replace临时链接本地子模块。
微服务里直接用 go mod init 会踩哪些坑
直接在微服务根目录执行 go mod init example.com/service/user 看似合理，但实际会让整个服务变成一个“巨石模块”：所有内部包（internal/handler、internal/repository、pkg/cache）都共享同一份 go.mod，版本锁定、依赖升级、测试隔离全受影响。
常见错误现象包括：import cycle not allowed（因跨 internal 子包循环引用）、cannot load internal/xxx: cannot find module providing package（测试时路径解析失败）、CI 中 go list -m all 输出混乱。
- 每个逻辑子域（如用户认证、订单处理、通知推送）应有独立模块路径，例如
example.com/service/user/auth、example.com/service/order/core -
internal/下的代码不能导出，也不该出现在模块路径中；真正需要复用的组件必须提成pkg/或单独仓库 - 主服务二进制入口（如
cmd/user-service/main.go）只负责组装，不放业务逻辑，它的go.mod只声明对各子模块的依赖，而非包含它们
怎么让 pkg/ 包真正可复用又不耦合主服务
很多人把工具函数、通用结构体塞进 pkg/util，结果发现一改就崩——因为这些包悄悄 import 了 internal/config 或 internal/metrics，导致外部项目无法使用。
判断标准很简单：运行 go list -f '{{.Imports}}' ./pkg/cache，输出里不该出现任何以 example.com/service/... 开头的路径。
立即学习“go语言免费学习笔记（深入）”；
- 所有配置、日志、监控等上下文依赖，必须通过接口注入，比如
cache.NewRedisClient(redis.Conn, cache.Option)，而不是硬编码读取config.Global().Redis -
pkg/内部禁止 importinternal/或cmd/；如有共享类型，应定义在api/或单独的types/模块中 - 对外暴露的
go.mod文件需显式设置require版本，避免依赖漂移；建议用go mod tidy -compat=1.21锁定最小 Go 版本
go get 替换本地子模块时为什么总失败
开发阶段想快速验证 pkg/cache 修改是否生效，执行 go get example.com/service/user/cache@latest 却报错：go get: example.com/service/user/cache@latest: invalid version: unknown revision latest。这是因为 Go 默认从远程拉取，而你的子模块还没 push 到远端。
在 Golang 中使用 samber/hot 进行内存缓存，支持 LRU、LFU、TinyLFU、W‑TinyLFU、S3FIFO、ARC、TwoQueue、SIEVE、FIFO 等淘汰算法，提供 TTL、缓存加载器及分片功能。
正确做法是用 replace 指向本地路径：
replace example.com/service/user/cache => ../user-cache
但注意：replace 只在当前模块生效，不会传递给下游依赖；上线前必须删掉 replace 行并发布真实版本号（如 v0.3.1），否则其他服务无法构建。
- 多个 replace 共存时，顺序无关，但路径必须是绝对路径或相对于当前
go.mod的相对路径 - 如果子模块路径含
-（如example.com/service/user-event），Go 会拒绝解析，应改用下划线或驼峰 - CI 流水线中禁用
replace，可用go mod edit -dropreplace自动清理
多模块协作时 go test 执行范围容易误判
在 pkg/cache 目录下跑 go test 看似只测缓存，但若它 import 了 example.com/service/user/internal/db，而 db 又依赖未启动的 PostgreSQL 容器，测试就会失败——你根本没意识到这个依赖链。
根本原因在于 Go 的模块边界不等于测试边界；go test ./... 会递归扫描所有子目录，包括被 replace 覆盖的模块路径。
- 始终用
go test -v ./...查看实际运行了哪些测试文件，确认无意外导入 - 对集成测试（如要连 Redis），放在
integration/子目录，并用//go:build integration标签隔离，避免和单元测试混跑 - 主服务的
go.mod不应包含require子模块的indirect依赖，否则go list -deps会漏掉真实依赖项
模块划分不是一劳永逸的事，最常被忽略的是版本号语义：子模块每次 breaking change 都必须升主版本（v2+），哪怕只是改了函数签名；否则 go mod graph 里会出现多个同名模块不同版本共存，调试时连 panic 堆栈都指向错的源码行。
