internal目录是编译器硬编码的路径可见性边界，仅允许父目录及其子目录导入，不控制符号可见性或运行时行为；真正封装需结合小写首字母、接口与工厂函数。
Go 多模块接口解耦不是靠“定义更多 interface”，而是靠约束导入路径、控制符号可见性、明确依赖方向——做错这三点，go build 会编译通过，但运行时一调用就 panic 或循环依赖。
为什么 internal/ 目录不能随便挪动
Go 的 internal/ 是硬编码的可见性边界：任何包只要路径包含 /internal/，就只能被其父目录或同级目录下的包导入。这不是约定，是编译器强制检查。
- 错误做法：
project/internal/user被project/cmd/worker导入 —— ✅ 合法；但若project/pkg/logger试图导入它 —— ❌ 编译失败 - 常见误用：把通用工具（如
validator、httpclient）放在internal/下，结果pkg/层无法复用，只能复制粘贴 - 正确分工：
internal/放业务专属逻辑（如internal/order/service.go），pkg/放跨模块可复用组件（如pkg/trace、pkg/httpx）
interface 定义该放哪层才不导致循环依赖
接口不是越抽象越好，而是谁消费、谁定义。把 Service 接口放在调用方（比如 handler）里，比放在被调用方（service 包）里更安全。
- 反模式：
internal/user/service/user.go定义type UserService interface { CreateUser(...) }，然后internal/user/handler依赖这个接口 —— 看似解耦，实则让 handler 和 service 形成隐式双向依赖 - 正解：
internal/user/handler自己声明type userUsecase interface { CreateUser(...) }，再让internal/user/service实现它。这样 handler 不依赖 service，只依赖自己需要的能力 - 额外好处：测试时可直接 mock
userUsecase，无需引入整个 service 包
跨模块调用时，go mod replace 怎么避免本地调试变生产事故
replace 只在当前 module 生效，且不参与远程构建。如果忘记删掉，CI 构建会拉取远端版本，而本地跑的是替换后的代码，行为不一致。
立即学习“go语言免费学习笔记（深入）”；
- 必须加注释说明用途，例如：
// replace internal/config => ./local-config // only for local dev, DO NOT COMMIT TO MAIN - 禁止在主模块的
go.mod中replace其他正式发布模块（如github.com/org/lib），应改用require+version控制 - 真正需要隔离调试的场景，建议用
replace指向本地../other-module，而非修改远端路径；同时确保other-module有独立go.mod并已go mod tidy
最易被忽略的一点：接口解耦后，真正的耦合常藏在错误处理和上下文传递里。比如所有模块都用 fmt.Errorf 包装错误，上层就无法用 errors.Is 判断类型；又或者每个 service 都从 context.Background() 新起 goroutine，导致超时和取消信号彻底丢失。解耦不只是结构，更是契约细节的统一。
