直接改import路径会编译失败，必须先用replace映射实现新旧代码并存：在主go.mod中添加replace github.com/yourorg/project/user => ./internal/user，再go mod tidy；否则因Go强制要求import路径为合法模块路径而非相对路径而报错。
直接改 import 路径会编译失败，先用 replace 隔离旧代码
老旧项目里直接把 import "github.com/yourorg/project/user" 改成 import "./internal/user"，Go 编译器立刻报错：cannot import absolute path 或 invalid import path。这不是路径写错，是 Go 模块系统强制要求 import 路径必须是合法模块路径（带域名），不能是相对路径。
正确做法是在主 go.mod 里加一行 replace 映射：
replace github.com/yourorg/project/user => ./internal/user
然后运行 go mod tidy。此时所有原 import 语句仍能通过编译，但实际加载的是本地 ./internal/user 目录下的代码。这一步不是“临时 workaround”，而是必须走的隔离通道——没它，新旧包根本无法共存。
- 如果
go mod tidy报require internal/xxx: version is required，说明replace行漏了、路径少斜杠、或目标目录下没有go.mod（哪怕空的也要有） -
replace只应在本地开发阶段使用；CI 环境或发布前必须移除，改用真实版本号require - 多个
replace容易形成隐式依赖链，每次提交前建议用go mod edit -json | grep replace扫一遍
拆包时别让 internal/ 出现在 import 路径里
常见翻车点：把包建在 internal/user/service，却在别处写 import "github.com/yourorg/project/internal/user/service"。Go 不认 internal/ 为“内部限定符”——它只在模块根路径下生效。一旦这个路径出现在 import 中，等于把实现细节当公开接口暴露，后续任何移动或重命名都会导致调用方编译失败。
对外可引用的路径必须稳定、语义化，比如 github.com/yourorg/project/user，哪怕物理位置在 ./internal/user。检查方法很简单：
- 全局搜索
import.*internal/，删掉所有匹配项 - 运行
go list ./... | grep internal，确保输出里没有你打算对外暴露的包 -
internal/下的子目录（如internal/user/adapter）绝不能被其他模块 import，只能被同级internal/user包内使用
接口定义放错位置，类型不兼容立刻炸
把 type Order struct{} 留在老包里，新包里写 func Create(o *oldpkg.Order)，看似能跑，但只要老包加个字段或改个 JSON tag，调用方就报 cannot use o (type *oldpkg.Order) as type *newpkg.Order。这不是 Go 严苛，是你没守住抽象边界。
GoLand 2026.1.1 是 2026.1 发布后的首个维护修正版本，适合已经开始体验 2026.1 新功能并希望同步补丁的开发者。它更适合用于入门项目、现有项目迁移测试和 IDE 行为验证。
每个新业务包根目录下必须建 contract.go，只放 interface 和 DTO：
type OrderService interface {<br> Create(input OrderInput) error<br>}<br><br>type OrderInput struct {<br> Name string `json:"name"`<br>}
老包实现该接口，新包只 import 自己的 contract.go，绝不 import 老包的 struct。数据转换初期手动赋值，不碰反射或 auto-mapping 库——字段名对不上、嵌套结构变深、指针 nil 处理，全靠手写才能第一时间暴露问题。
GoLand 的重构功能不能替代模块边界设计
GoLand 的 Shift+F6 重命名、Ctrl+Alt+M 提取函数，确实能快速移动符号、调整作用域，但它不会帮你判断：这个函数该放进 pkg/util 还是 internal/order；这个接口该定义在 domain 层还是 infrastructure 层。
真正卡住进度的，从来不是操作步骤，而是每次加新功能时那个犹豫：「如果明天被另一个服务复用，我现在的包名、接口签名、错误类型，还站得住脚吗？」
这个判断没法靠工具自动完成。它需要你盯着 go list -f '{{.Deps}}' ./internal/order | grep user 看循环依赖，需要你在 main.go 里删掉第 3 个 import 时停顿两秒，需要你写完 Replace 行后，手动跑一遍 go test -v ./internal/user 确保它真能独立通过——这些事，GoLand 不会提醒你，但少做一步，后面三天都在修 CI。
