Go 项目目录结构：标准 layout 与真实业务的取舍

每次新开一个 Go 项目，最纠结的事情往往不是用什么框架，而是目录到底怎么建。是直接照抄 GitHub 上 stars 最高的 `go-standard-layout`，还是按着自己过往的习惯随手乱搭？

这几乎是每个 Gopher 心照不宣的烦恼。打开那份流传甚广的标准布局，`cmd`、`internal`、`pkg` 这些顶级目录赫然在列，看着确实专业，也很“标准”。但真落进业务代码里，你会发现这套纯粹的单体仓库分层蓝图，大概率会和你的业务现实撞个满怀。

标准 layout 解决的是什么？

平心而论，这份 layout 本身是优秀的兵棋推演。`cmd` 目录明确告诉我们，应用入口应该集中管理；`internal` 圈定了谁才是自己人，防止外部代码越俎代庖；`pkg` 则承载了团队决定对外开放能力的边界。

这背后更贴近工程化本质的考量在于——让后来者和参与者拿到代码后，能快速对齐沟通语境。它其实是在倡导一种约定优于配置的组织管理方式，约定在 Go 工程里扮演着“活文档”的角色。

为什么普通业务团队会觉得它“重”？

在真实业务中，核心需求永远是“快”和“准”。MVP 要求两周上线，如果遵循标准布局，你通常需要在一开始就分配好 `pkg`（对外赋能模块）、`internal`(内部代码库）、`api`（也许还包括 `scripts` 下的持续集成处置）等五六层骨架，然后才在某个角落找地方塞进你的第一个 `Hello World` 接口。

这带来的最明显痛点，是被迫提前做架构决策和拆分，而这些决策在你根本没写完第一行业务逻辑时往往是错的。目录太发散，反而直接切碎了业务上下文。某个微服务本身只需消费自己的实体域和小型存储接口，却被硬生生拆成七八个文件夹。

另一个致命问题是：过度的扁平化分类有时候会在代码评审时让维护者精神错乱。业务模型变化频繁，当你需要在一个 Controller 中跨域调用另一个模块的内部逻辑时，你若不上沉到 `pkg`，就得考虑包依赖循环——结果为了适配标准布局的漂亮结构，你妥协做了一堆抽象层，代码行数翻倍，可读性减半。

来自业务演进的真切反馈

很多踩坑者最终会从纯结构引导回到“按模块划分”的路径。模块，也叫 feature-based layout，才是业务写代码时直觉上的抽象仓库。具体表现是按领域区分，将 `user`、`order`、`payment` 这样的业务域作为顶级目录，在每个模块内部再去自由使用 `handler`、`service`、`repository` 等职责分层。

这套范式下，整个代码的边界就是清晰的实际业务逻辑边界，域模型高度内聚，内部重构成本也低。对多数中小团队而言，模块化布局才是回归业务本质的核心解法。你的代码结构越是能迅速映射出业务关系，后续需求变更的熵增就越可控。

标准的精华在思想，不在死板的“文件夹”

标准 layout 并非不能借鉴。在支持多功能面的中期项目或 B 端中台里，你可以借鉴其精华——强制使用 `cmd` 保证启动逻辑唯一，以及用 `internal` 和 `pkg` 来定义开放边界。这是以代码结构为代码库做的规则设定，是对工程质量的积极把关。

只要遵循依赖流向清晰（入口依赖应用层，应用层依赖领域层，不反向倒灌）和向外公开必须显式声明（除非必要，不轻易开放编辑越权）这两条底线，你完全可以结合业务演化出自己的组织作风，让自己的业务模块与工程骨架形成共生关系，而不是逼着一个 20 行的脚手架去填满 10 个空目录。

Go 语言本身就是一股务实清流，目录组织也绝不例外。社区争论的标准 layout 本质是大厂最佳实践的某种架构对齐样本，需要足够的业务量级来托底。而对我们这些依然在快速迭代、频繁调整 API 的团队来说，唯业务是图，模块私有治理，只在真正需要共享时才上升接口进 `pkg`，或许才是被真实世界验证过的最佳工程实践。

标准 layout 并非万能药，更深层的关键是：你的团队成员是否理解为何而建这套目录，以及这套结构是否能随业务演进实现免疫性的自我迭代。