Go internal 包边界怎么定：哪些代码该藏起来，哪些应该开放复用

Go 项目里看到 internal 文件夹时，不少开发者第一反应是“是不是所有实现细节都得塞进去”。更靠谱的判断逻辑根本不是看代码够不够底层，而是看它该被谁导入：只服务当前仓库、还在频繁迭代调整、误用之后成本很高的包，适合放进 internal；真正要给多个仓库稳定复用的能力，再考虑放到普通公共包或者 pkg 这类公开路径下。

internal 更像一道包边界，不是代码分层装饰

internal 是Go工具链原生支持的特殊路径规则。如果一个包落在 internal 文件夹下方，只有它所在父级范围内的代码可以正常导入，边界之外的外部代码尝试导入会直接被编译器拦截。也就是说这不是靠团队自觉的约定，是语言工具链直接帮你把边界守死了。

举个实际的项目结构例子：

shop/
  go.mod
  cmd/api/main.go
  internal/order/service.go
  internal/mysql/store.go
  pkg/money/amount.go

cmd/api 可以正常使用 shop/internal/order，同一个仓库里的测试代码也能围绕它做完整验证；仓库外的其他项目如果尝试导入 shop/internal/mysql，会得到类似 use of internal package ... not allowed 的编译报错提示。这个提示作用非常实用，直接把“暂时不要依赖我”的边界规则写进了构建流程里，不需要靠人工审核来卡。

适合放进 internal 的压力通常来自变化

我习惯把 internal 当成“变化缓冲区”来用。一段代码对外暴露之后很难改名、很难拆分方法、很难调整入参，就完全没必要急着对外开放。尤其是业务服务、数据库适配器、支付网关封装、缓存键拼接、消息消费者这类包，当下看着像是通用公共能力，过不了多久就会和业务状态、数据库字段、自定义错误码深度绑定。

这类包一旦被其他仓库直接导入，后续很容易出现两个棘手问题：内部实现细节被外部代码当成稳定接口来使用；后续想要做重构调整的时候，不得不迁就一堆原本完全不需要知道这些细节的外部调用方。internal 能提前把这类依赖全部挡在当前仓库范围内，让后续重构的成本始终可控。

典型写法：公开入口保持小，内部实现可以随时替换

行业里很成熟的一种做法是把HTTP服务入口、命令行程序入口放在 cmd，把业务核心逻辑和各类存储适配器全部放在 internal。外部真正需要复用的，从来都不是 mysqlStore 这类具体实现，而是更稳定的接口定义、值对象封装或者标准化客户端。

package order

type Store interface {
    Save(ctx context.Context, o Order) error
}

type Service struct {
    store Store
}

func NewService(store Store) *Service {
    return &Service{store: store}
}

func (s *Service) Create(ctx context.Context, req CreateRequest) (OrderID, error) {
    o, err := NewOrder(req)
    if err != nil {
        return "", err
    }
    return o.ID, s.store.Save(ctx, o)
}

这里的 Store 可以直接定义在 internal/order 相邻位置，对应的MySQL具体实现逻辑全部放在 internal/store/mysql 下。调用方只需要知道订单创建的规则，完全没必要知道底层用的什么表名、连接池配置、事务处理细节。后续就算把存储从MySQL换成PostgreSQL，或者把数据落库动作改成异步队列投递，外层公开入口也不需要跟着做大规模调整。

反例：把 pkg 当成万能公共层会很快变重

不少新项目一开始就会直接创建一个 pkg 文件夹，然后把配置封装、日志组件、数据库操作、业务模型、第三方SDK封装全部往里面塞。短时间看着导入路径非常整齐，跑久了很容易变成“所有人都能随便拿，没人敢随便改”的负担。

最明显的信号就是：一个包里装了太多逻辑，被非常多地方导入，但没人能说清它的稳定边界到底在哪。比如 pkg/store 里同时放着数据库连接池封装、订单表查询逻辑、会员表更新逻辑，看起来通用性很强，实际是把不同业务的变化点全部绑定到同一个公共节点上。这类公共包不仅后续调试非常麻烦，每次做字段调整都要当成一次跨项目迁移来处理。

测试替身不要求把实现包公开

有人会担心代码放进 internal 之后不好做单元测试。这个担心只说对了一半：如果测试逻辑非要直接实例化内部实现类，确实会被边界规则限制；但Go生态里更自然的处理方式，是在调用方附近定义最小粒度的接口，再用轻量替身覆盖所有外部依赖。

type fakeStore struct {
    saved order.Order
}

func (f *fakeStore) Save(ctx context.Context, o order.Order) error {
    f.saved = o
    return nil
}

测试业务逻辑的时候，核心校验点从来都不是MySQL包本身能不能被外部测试到，而是订单创建之后的行为是否符合预期。内部存储实现完全可以在自己的包内写集成测试，上层业务逻辑只需要用替身把外部依赖mock掉测规则就够了。这么处理之后测试边界反而更清晰：业务测试完全不需要关心存储细节，存储测试也不需要假装自己是完整业务流程。

判断清单：先问这几个问题

真正难的从来都不是知道 internal 的基础规则，而是判断一个包到底要不要对外开放。可以用下面这份清单先逐一核对，答案越偏向保守侧，就越适合先放在当前仓库内部。

• 会被几个仓库复用？只有当前仓库会用的前提下，优先放进 internal。
• 语义稳定吗？入参、返回值、错误类型还在频繁调整的阶段，先不要对外开放。
• 外部依赖它会不会误用？如果外部拿到底层适配器之后很容易绕过预设的业务规则，必须收紧边界。
• 有没有明确的维护责任人？对外开放公共包，就意味着后续文档维护、版本兼容、变更通知都要有明确的负责人跟进。
• 测试逻辑真的必须依赖公开实现吗？绝大多数场景都可以通过调用方自定义小接口加替身的方式解决。

有个很实用的经验可以参考：一开始尽量从窄边界起步。代码在 internal 里跑稳了，调用场景也完全明确了，再移动到公开路径下补上兼容承诺；反过来想把已经被多个外部仓库依赖的公共包收回来，成本会高非常多。

相关问题

Go 项目一定要有 internal 吗？

完全不用硬性要求。小项目、练习项目、单一功能命令行工具完全可以保持简单结构。等后续出现多个入口、多个适配器、或者明确有部分包不希望被外部直接导入的时候，再引入 internal 就很自然。

pkg 文件夹是不是 Go 官方推荐的固定写法？

不是强制规范。pkg 更多是社区里流传很广的通用习惯，用来标识这个文件夹下的包可以被外部复用。要不要用这个命名，完全看你自己项目的维护策略，不用看到其他项目用就直接照搬。

internal 里的代码可以被同仓测试访问吗？

可以，只要测试代码放在允许导入的父级范围内就行。更推荐的做法是把业务规则的测试代码放在对应包的相邻位置，跨包测试只需要覆盖真正需要对外暴露的行为就够了。

什么时候应该把 internal 包挪到公开位置？

等它已经具备稳定语义、固定的外部调用方、清晰的版本兼容责任，同时确实有多个仓库需要用到的时候，再对外开放比较稳妥。移动之前最好先整理好命名规范、错误语义和最小使用示例。

internal 不是用来让项目结构看起来更复杂的摆设，它专门解决依赖边界不清的问题。只给当前仓库使用、迭代还没稳定、误用代价高的实现，先全部收拢在内部；跨仓库复用同时愿意承担后续兼容责任的能力，再放到公开包对外提供。按照这个顺序来处理会更稳妥，后续做重构的时候负担会轻很多。