go模块导入路径必须严格匹配go.mod中module声明的完整路径，不支持相对路径或缩写；子目录包需以模块路径为前缀，如module github.com/user/project，则internal/handler的导入路径必须是github.com/user/project/internal/handler。
Go 模块系统不支持“多级子目录对应多级模块”的理解方式——go.mod 文件所在目录即为模块根，所有子目录包都属于该模块，不存在“子模块自动继承父模块路径”的行为。路径解析混乱，本质是包导入路径与模块声明路径不一致，或误以为嵌套目录能天然形成隔离边界。
为什么 import 路径和实际目录结构对不上？
Go 编译器只认 import 语句里的字符串，不自动推导目录层级。如果你的模块路径声明为 module github.com/user/project，那么哪怕包放在 internal/handler/v2/auth 目录下，它的完整导入路径也必须是 github.com/user/project/internal/handler/v2/auth，而不是 project/internal/handler/v2/auth 或其他缩写。
- 常见错误：在
main.go里写import "handler"或"./handler"—— Go 不支持相对路径 import，也不识别未声明的短名 - 错误现象：
import "xxx" is a program, not an importable package或cannot find package "xxx" - 根本原因：没按
go.mod中module行声明的路径来组织import字符串 - 验证方法：运行
go list -f '{{.ImportPath}}' ./internal/handler，看输出是否匹配你代码里写的import内容
go mod init 放错位置导致整个路径体系崩塌
模块初始化必须在项目逻辑根目录执行，且该目录应包含 main.go 或至少一个顶层包。若你在 cmd/app 下执行 go mod init myapp，那模块路径就变成 myapp，但 import "myapp/internal/config" 在别处就无法解析——因为其他包并不知道这个 myapp 是谁。
- 正确做法：在项目最外层目录（如
~/myproject/）运行go mod init github.com/user/myproject - 错误做法：在
src/、cmd/、internal/等子目录下 init，会割裂包可见性 - 补救方式：删掉错误位置的
go.mod，回到顶层重做；已有import语句需批量替换为新模块路径前缀 - 注意：
go mod init不会自动修正已有 import，它只生成配置文件
用 internal/ 和语义化路径代替“物理分层”
Go 没有“包层级权限控制”，但 internal/ 是唯一被语言强制限制外部导入的机制。真正的分层靠的是路径命名表达职责，而非目录嵌套深度。
-
internal/handler表示仅本项目使用的请求接入层，外部无法 import -
pkg/repository表示可被其他项目复用的数据访问抽象，路径本身暗示稳定性 - 避免无意义嵌套：
internal/api/v1/rest/handler不如internal/handler/rest/v1—— 后者更贴近实际引用习惯 - 所有包路径必须以模块路径为前缀，例如模块是
github.com/user/app，则internal/handler的完整 import 就是github.com/user/app/internal/handler
go build 报错 “main module does not contain package” 怎么快速定位？
这不是路径写错了，而是当前工作目录不在模块根，或 go.mod 声明的模块路径与你 import 的路径不匹配。Go 会严格校验：你 import 的每个路径，必须能映射回某个已知模块的 go.mod 所声明的路径前缀。
- 先确认当前目录是否有
go.mod，并运行go list -m看模块名是否是你预期的 - 检查报错中提到的 package 路径，比如
github.com/user/app/cmd/server，然后手动 cd 进去，运行go list -f '{{.Module.Path}}'看它声称属于哪个模块 - 如果返回空或报错，说明该目录没被任何模块覆盖——要么删掉多余
go.mod，要么把 import 改成上级模块能识别的路径 - 临时调试可用
go build -work查看实际构建时使用的临时目录结构，比猜更可靠
最易被忽略的一点：模块路径不是 URL，也不是文件系统路径，而是一个**命名空间标识符**。哪怕你把代码全挪到 /tmp/xyz 下，只要 go.mod 里写的是 module github.com/a/b，所有 import 就必须以 github.com/a/b/... 开头——否则 Go 就不认识它。
