别把 Go 写成 Java：毁掉项目从过度架构开始
本文永久链接 – https://tonybai.com/2026/06/05/stop-writing-go-like-java-avoid-over-architecting
大家好，我是Tony Bai。
前不久，Go 语言社区 Reddit (r/golang) 上爆发了两场激烈的争论。
这两个帖子的主题直击了无数 Go 开发者的灵魂深处：
- 我们该如何构建一个大型的 Go 模块化单体架构，而不被复杂的“架构设计”淹没？
- 为什么现在的 Go 项目里，pkg 和 internal 目录被滥用得如此令人发指？
如果你正在维护一个中大型的 Go 后端项目，你大概率经历过这样的绝望时刻：为了加一个极其简单的业务字段，你需要穿透 handler、usecase、domain、repository、adapter 等足足五层抽象结构；你的项目根目录下躺着一个 pkg 文件夹，里面又套着 internal，代码藏在七八级目录深处。
你以为你在写出业界最高标准的“整洁架构（Clean Architecture）”，但实际上，你正在把 Go 语言写成你曾经最讨厌的“臃肿企业级 Java”。
今天，我们就来透过这层过度工程（Over-engineering）的外衣，看看顶级开发者们是如何打破这种“架构伪神话”，用最符合 Go 哲学的极简方式，构建起能支撑千万级流量的大型单体项目的。
被“标准规范”毒害的洋葱病
在一个全新的 Go 项目立项时，很多技术负责人的第一反应就是去 GitHub 搜一个叫做 golang-standards/project-layout 的高赞仓库，然后照猫画虎地建起一堆目录。
紧接着，悲剧就开始了。综合 Reddit 各位资深大佬的吐血经验，以下两大陷阱，几乎踩中了 90% 的业务团队：
陷阱 1：“死去的” pkg 与被滥用的 internal
帖子原作者一针见血地指出：pkg 目录是时代的眼泪，而 internal 正在遭受前所未有的滥用。
在早期的 GOPATH 时代，我们需要一个地方来区分业务代码和第三方包，于是有了 pkg。但在 Go Modules 已经全面普及的今天，你的代码仓库根目录本身就是一个 Module。在 root 下面再嵌套一层 pkg 纯粹是“脱裤子放屁”——它除了让你的 import 路径变长 4 个字符之外，没有任何实际意义。
更致命的是 internal。官方引入 internal 是为了防止库开发者暴露内部 API 给第三方。但是现在的业务开发团队，为了所谓的“代码隔离”，盲目地把整个 App 的所有核心逻辑全塞进 internal，导致项目结构变成了这样：
internal/app/modules/order/usecase/impl/order.go
当你接手这种代码时，你每天有 30% 的时间在 VSCode 里狂按文件树，试图搞清楚自己到底在哪。
陷阱 2：生搬硬套的 DDD 与洋葱架构（Clean Architecture）
一位在电商公司写 Go 的老哥抱怨道：他试图用严格的 DDD（领域驱动设计）和六边形架构来组织他的模块化单体代码。结果是，随着项目增大，维持这种“整洁”变成了噩梦。
每一次新增功能，都要处理无休止的接口绑定（Wiring dependencies）、防止循环引用，以及为了“解耦”而写的大量毫无意义的样板代码（Boilerplate）。“我感觉自己花在维护架构上的时间，甚至超过了实际交付业务功能的时间。”
记住：Go 语言的灵魂是简单直接。强行引入 Java/C# 语境下的沉重分层，就像给一辆轻巧的保时捷跑车装上了坦克的履带。
为什么“扁平化”才是 Go 架构的尽头？
面对这种极度臃肿的代码，我们在 Reddit 的评论区看到了海外老炮们的共识：Opting for a flatter structure typically guides you organically away from overly nested internal. (选择更扁平的结构，通常能自然而然地引导你远离过度嵌套的代码气味)。
在 Go 语言中，优秀的架构并不是靠“目录分层”来体现的，而是靠“领域边界（Domain Boundaries）”和“依赖流向”来体现的。
真相 1：Package 的划分应该基于“业务能力”，而不是“技术层次”
把项目按 controllers/、services/、models/ 划分是典型的反模式（MVC遗毒）。这种结构下，如果你要修改一个关于“订单”的功能，你必须在好几个目录下反复横跳。
真正懂 Go 的做法是：按领域（Domain）划分子包。 一个 order 包里，就应该包含订单的结构体、订单的仓储接口、乃至相关的处理逻辑。所有的东西都在一起，高内聚。
真相 2：不需要过度设计“防腐层”，直到你真正觉得痛
一些高级开发者指出，他们宁愿花更多的时间去做“事件风暴（EventStorming）”和领域建模，也不愿意去写抽象接口。如果你的 order_repository.go 从第一天起就只有一个 Postgres 实现，且未来三年都不会换数据库，那么你为了“解耦”而提取的一个洋葱接口层，就是纯粹的成本浪费。
大型 Go 项目实用构建指南
抛开那些玄乎其玄的词汇，如果你想构建一个不崩溃的、好维护的大型模块化单体（Modular Monolith），请立刻遵循以下四条“少即是多”的务实法则：
法则 1：干掉 pkg，克制使用 internal
除非你正在写一个准备开源给全世界使用的公共 Library 包，否则你的微服务或单体 Web 应用根本不需要 pkg 目录。
同样，把你的核心代码从深渊般的 internal/app/core/… 中解放出来。把业务包直接平铺在根目录或者按大模块放在一个外层目录即可。让文件树尽可能的“浅”。
法则 2：采用极简的领域扁平结构（Domain-Driven Flattening）
正如评论区大佬给出的终极解法，你的项目结构应该看起来像这样：
cmd/
server/main.go // 所有依赖注入和组装都在这里完成（Composition Root）
domain/ // 或者直接放在根目录
order/
order.go // 领域模型（Entity/Aggregate）
repository.go // 接口（依赖倒置，只定义 order 需要什么）
postgres_repo.go // 直接在同一个包下实现，或者平铺
user/
...
catalog/
...
不要再建什么 port 和 adapter 文件夹了！order.go 就是你的核心，postgres_repo.go 就是它的具体实现。它们呆在一个包里，简单明了，任何人 grep 搜索一下就能秒懂。
法则 3：让 Consumer 定义接口（Interface Segregation）
很多人为了解耦，喜欢在一个单独的 interface 包里定义全局接口，这又是 Java 思维作祟。
在 Go 里，接口应该是“隐式实现”的。不要在提供者（Provider）端定义接口，要在消费者（Consumer）端定义。
比如 order 包需要发邮件，它不应该去依赖 email 包的接口。它应该在自己的包里定义一个极小的 type Mailer interface { Send(…) }，然后在 main.go 中把真正的 Email 服务注入进去。这就是 Go 解除循环依赖的最强法宝。
法则 4：一切脏活累活，全扔进 main.go
对于单体应用来说，不要试图在每个模块内部做复杂的自动依赖注入（Autowiring）或自启动钩子。
保持每个模块都是极度干净、被动的。然后在你唯一的 cmd/server/main.go 里，显式地初始化数据库、初始化各个模块、然后手动把它们组装（Wire）在一起。是的，这个 main.go 可能会有几百行甚至上千行，但它让你在启动时一目了然，排查问题再也不用像个无头苍蝇一样在迷宫里乱撞了。
小结：回归大道至简
不管是摒弃 pkg，还是剥离 500 层的“整洁架构”，这背后体现的其实是 Go 语言最深刻的哲学：Pragmatism（务实主义）。
技术架构的终极目标，是为了让人读得懂，让业务跑得快，而不是为了满足程序员在代码里“建构精密钟表”的虚荣心。
如果你的代码不能让人在 30 秒内找到修改点，不能让你通过一个简单的 grep 搜索就锁定业务逻辑，那么不管你的架构图画得多么符合六边形、洋葱或者 DDD 规范，它都是一个失败的设计。
所以，立刻打开你的 IDE，试着把你那些嵌套了五六层的文件夹拖出来吧。相信我，当你删掉那一堆废话般的中间层接口时，你会感受到前所未有的舒畅。
资料链接：
- https://www.reddit.com/r/golang/comments/1tftqpj/how_do_you_structure_and_maintain_large_go/
- https://www.reddit.com/r/golang/comments/1tft8ds/pkg_internal_directories_are_way_overused/
今日互动探讨：
在你的 Go 项目里，曾经为了遵循所谓的“规范设计”做过哪些现在看起来极其离谱的过度工程？你现在的项目是扁平结构还是洋葱结构？
欢迎在评论区留言晒出你的代码结构，或者 @出那个每天沉迷于建文件夹的同事。让我们一起探讨，什么是真正的“Go 语言地道之美”！
(如果你觉得这篇实操指南帮到了你，请不要吝啬你的点赞和转发！)
还在为写 Agent 框架频频死循环、上下文爆炸而束手无策？我的新专栏 《从0 开始构建 Agent Harness》 将带你：
- 抛弃臃肿框架，回归“驾驭工程 (Harness Engineering)”的第一性原理
- 用 Go 语言手写 ReAct 循环、并发拦截与上下文压缩引擎等，复刻极简OpenClaw
- 构建坚不可摧的 Safety Middleware 与飞书人工审批防线
- 在底层实现 Token 成本审计、链路追踪与自动化跑分评估
- 从“调包侠”进化为掌控大模型边界的“AI 操作系统架构师”
扫描下方二维码，开启从 0 开始构建Agent Harness 的实战之旅。
原「Gopher部落」已重装升级为「Go & AI 精进营」知识星球，快来加入星球，开启你的技术跃迁之旅吧！
我们致力于打造一个高品质的 Go 语言深度学习 与 AI 应用探索 平台。在这里，你将获得：
- 体系化 Go 核心进阶内容: 深入「Go原理课」、「Go进阶课」、「Go避坑课」等独家深度专栏，夯实你的 Go 内功。
- 前沿 Go+AI 实战赋能: 紧跟时代步伐，学习「Go+AI应用实战」、「Agent开发实战课」、「Agentic软件工程课」、「Claude Code开发工作流实战课」、「OpenClaw实战分享」等，掌握 AI 时代新技能。
- 星主 Tony Bai 亲自答疑: 遇到难题？星主第一时间为你深度解析，扫清学习障碍。
- 高活跃 Gopher 交流圈: 与众多优秀 Gopher 分享心得、讨论技术，碰撞思想火花。
- 独家资源与内容首发: 技术文章、课程更新、精选资源，第一时间触达。
衷心希望「Go & AI 精进营」能成为你学习、进步、交流的港湾。让我们在此相聚，享受技术精进的快乐！欢迎你的加入！
商务合作方式：撰稿、出书、培训、在线课程、合伙创业、咨询、广告合作。如有需求，请扫描下方公众号二维码，与我私信联系。
评论