Go项目一旦超过几千行代码，包怎么放就成了绕不开的问题。有的团队把所有业务代码塞在一个包里，测试文件和工具脚本混在一起；有的团队照搬开源项目结构，建了一堆空目录却没人知道该往哪写代码。其实Go官方在语言层面已经提供了一套约束机制，也就是internal包，配合合理的目录划分，就能让项目结构自然收敛。这篇文章把规则、目录骨架和常见坑一次性讲清楚。
internal包的可见性规则到底是怎么回事
internal是Go编译器内置的特殊目录名，规则只有一句话：internal包只能被以internal父目录为根的子树内的代码导入。听起来抽象，看个例子就明白了。假设模块路径是github.com/yourname/shop，目录结构如下：
shop/
├── internal/
│ └── service/
│ └── order.go
├── cmd/
│ └── server/
│ └── main.go
└── pkg/
└── util/
└── string.go
在这个结构里，cmd/server/main.go可以正常导入shop/internal/service，因为cmd和internal是兄弟目录，它们共同的上层是模块根目录，满足可见性要求。但如果另一个模块github.com/other/project尝试导入这个internal包，编译器会直接报错，提示"use of internal package not allowed"。这个限制是硬性的，无法通过任何配置绕开。
这个机制的价值在于契约明确。你把核心业务逻辑放进internal，等于向所有外部使用者声明：这些代码随时可能重构甚至删除，不要依赖它们。相比之下，仅靠文档说明“这个包请不要导入”约束力几乎为零，团队协作中总有人会不小心引用，等你要重构时才发现处处是牵绊。
需要注意的是，internal不一定要放在模块根目录。任何一级目录下都可以有internal，规则同样生效于该目录的子树。比如shop/api/internal/...就只能被api目录下的代码导入，这种局部化的可见性控制在大型单体仓库中特别有用，可以让不同子系统之间保持隔离。
一个可复用的项目目录骨架
社区经过多年实践，形成了一套相对收敛的目录约定。下面这个骨架适合大多数中型Web服务项目：
shop/ ├── cmd/ │ └── server/ │ └── main.go // 程序入口，尽量薄，只做初始化和启动 ├── internal/ │ ├── handler/ // HTTP处理层 │ ├── service/ // 业务逻辑层 │ ├── repository/ // 数据访问层 │ ├── model/ // 领域模型定义 │ └── config/ // 配置加载 ├── pkg/ │ └── logger/ // 明确允许外部项目复用的通用库 ├── api/ │ └── proto/ // 接口定义文件 ├── scripts/ │ └── migrate.sh // 构建、部署脚本 ├── go.mod └── go.sum
cmd目录的main.go应该只做三件事：解析配置、初始化依赖、调用启动函数。不要在main.go里写业务逻辑，因为它无法被单元测试覆盖。一个健康的main.go通常不超过五十行，所有具体逻辑都下沉到internal中的包里，通过依赖注入的方式组装起来。
internal里的分层建议保持单向依赖：handler依赖service，service依赖repository，model被各层引用但不依赖任何层。这种单向箭头一旦被打破，比如repository反过来调用了handler的类型，整个项目的编译依赖会迅速腐化，后续每次改动都可能引发连锁反应。
pkg目录要谨慎使用。很多人误以为pkg是“公共代码区”，把所有不想放internal的东西都丢进去，结果pkg越来越臃肿，最后变成了没有约束的杂物间。正确的判断标准是：这个包是否愿意被外部项目导入并承诺长期兼容？如果答案是否定的，放internal更合适。如果项目本身就不打算被别人当库引用，甚至可以不建pkg目录。
循环依赖的成因与拆包思路
随着业务膨胀，几乎每个Go项目都会撞上循环依赖。典型报错是"import cycle not allowed"，Go在编译期就禁止包之间互相导入。最常见的成因是两个包互相引用了对方的类型，比如service包需要一个User模型，而model包里定义User时又需要service包中的某个常量。
解决思路有三种。第一种是把共享的类型和常量抽到一个更底层的包，让原来的两个包都依赖它，依赖箭头重新变成有向无环图。第二种是引入接口，在调用方定义接口而不是在被调用方，这是Go推崇的“接口由消费者定义”哲学。第三种是合并包，如果两个包纠缠得实在太深，说明它们本质上是一个关注点，硬拆反而增加了理解成本。
// internal/service/order.go
package service
// 接口定义在消费方，避免反向依赖repository包的具体实现
type OrderRepo interface {
Save(order *model.Order) error
GetByID(id string) (*model.Order, error)
}
type OrderService struct {
repo OrderRepo
}
func NewOrderService(repo OrderRepo) *OrderService {
return &OrderService{repo: repo}
}
上面这段代码演示了接口下沉的写法。service包只依赖自己定义的OrderRepo接口，repository包在main中通过参数注入实现，两个包之间没有任何直接导入关系。这种模式配合internal使用效果很好：即使repository包放在internal/repository，service也完全不感知它的存在，替换成内存实现做单元测试时非常方便。
多模块仓库与go.work的配合
当单模块膨胀到几十个包、CI构建时间明显变长时，可以考虑拆分成多个模块，也就是在仓库的不同子目录下各放一个go.mod。拆分后各模块独立版本化、独立构建，但本地开发时跨模块调试会很麻烦，改一行代码就得先发布版本才能被另一个模块引用。
go.work文件就是为解决这个问题出现的。在仓库根目录执行go work init ./module-a ./module-b，会生成一个工作区配置，本地构建时各模块直接引用磁盘上的源码而不是版本库中的提交，改动即时生效。团队协作时要注意：go.work通常只用于本地开发，建议加进.gitignore，不要提交到仓库，避免干扰其他环境构建。
最后提醒一点，目录结构没有银弹。上面这套骨架适合起步，但真正需要坚守的原则只有两条：用internal守住不该暴露的边界，用单向依赖维持包图的健康。只要这两条不破，目录怎么调整都是低成本的；反过来，一旦边界失守，再漂亮的结构图也救不了越来越乱的代码。