该用，且越早用越好；Go 1.4+ 编译器强制限制 internal/ 下包仅能被同模块父目录及子目录导入，用于封装强耦合业务逻辑、私有模型、未稳定工具等，防止外部误依赖。
Go 项目该不该用 internal/？什么时候必须用
必须用，而且越早用越好。Go 1.4+ 对 internal/ 有硬性限制：任何在 internal/ 下的包，都无法被其父目录以外的模块导入。这不是约定，是编译器级保护。
常见错误现象：go build 成功，但外部模块 import "github.com/user/myapp/internal/handler" 报错 use of internal package not allowed —— 这不是 bug，是预期行为。
使用场景：
- 业务逻辑强耦合、含私有配置或未稳定 API 的代码（如
internal/user/service） - 数据库模型与 repository 实现（
internal/user/model,internal/user/repo） - 不想暴露给下游依赖、但又需在本项目多处复用的工具（
internal/util/logger）
容易踩的坑：把本该放 pkg/ 的通用校验库（如 pkg/validator）误塞进 internal/，导致后续想抽成独立库时要重写路径和测试。
立即学习“go语言免费学习笔记（深入）”；
cmd/ 目录下多个子目录怎么管理 main 包
每个子目录对应一个独立可执行文件，且必须是 package main。例如 cmd/api/main.go 和 cmd/cli/main.go 是两个完全隔离的构建单元。
关键点：
- 不能共用同一个
main.go文件去条件编译；Go 不支持#ifdef风格的入口控制 - 每个
cmd/xxx下只能有一个main.go，否则go build cmd/api会报multiple main packages - 共享逻辑（如配置加载、日志初始化）应下沉到
internal/app或internal/config，由各main.go显式调用
性能影响：多个 cmd/ 子目录不会增加编译时间，go build cmd/api 只编译该目录及其依赖，不扫描整个 internal/。
为什么 pkg/ 不等于 “所有能复用的代码”
pkg/ 是对外契约，不是代码仓库。它的存在意味着你承诺：API 稳定、有文档、带测试、语义版本可控。
典型误用：
- 把刚写的
pkg/cache/redis.go直接推到公司内部 registry，结果两周后发现接口要加 context 参数，被迫发 v2 - 在
pkg/里引用internal/config—— 违反单向依赖，导致外部使用者必须也引入你的内部配置结构 - 把 HTTP handler 相关工具放
pkg/httpx，但里面用了gin.Context—— 实际绑死了框架，根本不算通用
判断标准：能否脱离当前项目单独 go test 通过？能否被另一个完全无关的 Go 模块 import 并跑通示例？不能，就别放 pkg/。
测试文件放哪？_test.go 能跨目录 import 吗
必须和被测源码同目录，且包名通常一致（user.go → user_test.go，都属 user 包）。Go 工具链只认这个模式。
常见错误现象：go test ./... 找不到测试；或者 user_test.go 里 import "github.com/user/myapp/internal/user" 报循环依赖 —— 因为测试文件和源码在同一包，直接访问字段函数即可，不需要 import。
特殊场景处理：
- 集成测试（如启动真实 DB）可放在
internal/user/integration_test.go，包名用user_test（末尾加_test），这样它就能 import 其他包，且go test -run Integration可单独执行 - 无法避免的跨包测试逻辑（如 mock 外部服务）建议提成
internal/testutil，而非塞进pkg/
最容易被忽略的是：go test 默认不运行 examples/ 或 scripts/ 下的测试文件，哪怕它们叫 xxx_test.go —— 路径不在包树内，工具链直接跳过。
