本文永久链接 – https://tonybai.com/2025/12/15/go-language-anti-patterns-10-donts

大家好，我是Tony Bai。

“有哪些‘不要做’的教训，是你花了好几年才学会的？”

近日，在 r/golang 社区，这个简单的问题，引爆了一场关于 Go 语言“反模式”与“最佳实践”的集体反思。帖子下数百条评论，汇集了无数 Gopher 在真实项目中用“血与泪”换来的宝贵经验。这些教训，往往不是关于某个高深的算法，而是关于那些看似“理所当然”，却在不经意间为代码埋下地雷的日常习惯。

这篇文章，正是对这场集体智慧的一次系统性梳理。我们从中提炼出 10 条最核心的“不要做”法则，它们如同一份“避坑指南”，能帮助你绕开那些最常见的陷阱，更快地从一名“会写 Go 的程序员”，成长为一名“懂 Go 的工程师”。

不要过度封装包

Don’t overpackage things

初学者往往有一种冲动，想把代码组织成“语义化”的、层层嵌套的包结构。internal/models, internal/services, internal/repositories…… 这种源自其他语言（如 Java）的模式，在 Go 的世界里，往往是一种过早的、不必要的复杂性。

社区忠告：从一个 main.go 文件开始。努力思考，是否真的有必要将代码拆分到多个文件/包中。Go 的包，其主要目的是封装和依赖管理，而不是单纯的文件夹分类。在小型或中型项目中，一个清晰的、扁平的包结构，远比一个复杂的“企业级”目录树更易于维护。

不要滥用 channel 和 goroutine

Don’t just add in channels

并发是 Go 的“名片”，这使得许多开发者（尤其是新手）有一种“锤子心态”——看到任何问题，都想用 goroutine 和 channel 来解决。然而，不必要的并发，是复杂性和 bug 的温床。

社区忠告：

• 先问“是否需要”：你真的需要并发吗？如果不需要在线程间传递消息，你可能根本不需要 channel。一个简单的 sync.WaitGroup 或 sync.Mutex，在很多场景下都比 channel 更简单、更直接。
• 并发不是免费的：Go 让创建 goroutine 变得异常简单，但这并不意味着它是零成本的。过多的 goroutine 会增加调度器的负担，而 channel 的滥用则会使数据流变得难以追踪和调试。

不要盲目追求 DRY

Don’t be zealous about DRY

DRY 是编程的基本原则，但在 Go 的哲学中，它有一个更重要的“上级”——清晰性。为了消除几行重复代码，而引入一个复杂的接口或一个晦涩的辅助函数，往往得不偿失。

社区忠告：“一点点复制，胜过一点点依赖 (a little copy-paste is better than a little dependency)。” 当你发现自己在为了 DRY 而绞尽脑汁时，请停下来问问自己：这份重复，是否真的带来了维护上的痛苦？如果不是，那么接受它，可能是一个更明智的选择。

不要在同一个 PR 中既重构又添加新功能

Don’t refactor and add features in the same PR

在添加一个新功能时，顺手“优化”一下周围的代码，这看起来很高效。但实际上，这会让 Code Review 变得异常痛苦。Reviewer 无法清晰地分辨，哪些改动是为新功能服务的，哪些是纯粹的重构。这不仅增加了审查的难度，也提高了引入新 Bug 的风险。

社区忠告：遵循“童子军军规”——“让营地比你来时更干净”——是好的。但请将它分解为两个独立的、目标明确的 PR：一个只做重构，另一个（基于重构后的代码）只添加新功能。

不要跳过写测试，“就这一次”

Don’t skip writing tests “just this once”

这是所有开发者都曾屈服过的诱惑。“这个改动太小了”、“我百分之百确定它是对的”、“项目赶时间”…… 每一次“就这一次”的妥协，都在为未来的“技术雪崩”添砖加瓦。

社区忠告：将测试视为代码不可分割的一部分。在 Go 中，编写测试是如此简单和自然，以至于没有任何借口可以跳过它。你今天节省下来的 10 分钟，可能会在未来，让你或你的同事，花费数天时间去调试一个本可避免的生产问题。

不要害怕使用 sync.Cond

channel 非常强大，但它并非解决所有并发同步问题的“银弹”。社区中有一种“反 sync”的情绪，认为所有同步都应该用 channel 来完成。

社区忠告：sync.Cond 是一个被低估了的、极其强大的并发原语。当你需要基于某个特定条件来唤醒一个或多个等待的 goroutine 时（例如，一个任务队列的消费者在队列为空时等待），sync.Cond 往往比用 channel 实现的复杂信令机制，要更简单、更高效。不要因为不熟悉，就回避它。

不要返回接口

Returning interfaces. Don’t do it.

在函数签名中返回一个接口，看似遵循了“依赖倒置”的高级原则，甚至觉得这样更“灵活”。但实际上，这往往是一种过早的、有害的抽象。它剥夺了用户访问底层具体类型特有功能的能力，并且如果未来需要添加新方法，接口的变更会极其痛苦。

社区忠告：遵循 Go 的经典谚语：“接收接口，返回结构体 (Accept interfaces, return structs)。”

• 接收接口：让你的函数接收一个只包含其所需最小方法集的接口作为参数。这使得你的函数更容易被测试和复用（你可以传入任何满足该接口的实现，包括 Mock 对象）。
• 返回结构体：让你的函数返回一个具体的类型（通常是指针）。这给了调用者最大的灵活性。

经典范例：

看看标准库中的 os.Open，它返回的是 *os.File（具体结构体），而不是 io.Reader（接口）。
* 为什么这样做？ 因为 *os.File 不仅能读（Read），还能关闭（Close）、获取状态（Stat）、甚至改变权限（Chmod）。
* 灵活性：如果它返回的是接口，用户就无法使用 Chmod 等特有功能了。而返回结构体，用户既可以使用其全部功能，也可以在需要时，轻松地将其赋值给 io.Reader 接口来使用。这就是“返回结构体”带来的自由。

(注：只有当返回的类型是包内私有的、不希望外部直接访问的实现细节时，返回接口才是有意义的，例如 context.WithCancel 返回的是 Context 接口。)

不要过度依赖依赖

Don’t add dependencies without vetting

为了解决一个小问题，而引入一个庞大的、闪亮的第三方库。这在 Node.js 生态中很常见，但在 Go 社区，这通常被视为一种“危险信号”。

社区忠告：

• 先求诸标准库：在引入任何依赖之前，先问问自己：这个问题，标准库真的解决不了吗？
• 审慎评估：如果必须引入依赖，请仔细评估它：它的依赖树有多深？社区是否活跃？维护者是否可靠？一个简单的依赖，可能会为你整个项目，带来潜在的供应链安全风险和维护噩梦。

不要盲从

Don’t do [or not do] something simply because an authoritative voice recommended it

盲目地遵循某个“大神”、某篇“爆款”博客文章、或者某个“权威”推荐的模式，而没有结合自己的具体场景进行批判性思考。

社区忠告：上下文决定一切。YAGNI (You Aren’t Gonna Need It) 是一个好原则，但有时你确实需要提前设计。微服务很好，但有时单体就是最佳选择。没有银弹。最好的实践，是那些在你的团队、你的项目中，被证明行之有效的实践。

不要忘记，代码是给人读的

忘记了代码的最终读者是人类，而不是编译器。编写只有自己能看懂的“聪明”代码，或者忽略文档和注释的重要性。

社区忠告：

• 编写能让你的未来“自已”不会痛骂你的代码。
• 好的设计不是增加，而是保持本质的简单。代码即是负债 (Code is liability)。
• 不要忽视清晰文档的重要性。

小结：在“坑”里成长

这份清单，远非全部。社区的讨论中还充满了诸如“不要用 singleton 来做 mock”、“不要滥用 init 函数”、“不要在疲劳时 Review 代码”等无数宝贵的经验。

它们共同指向了一个核心思想：成为一名优秀的 Go 工程师，其过程不仅仅是学习语言的特性，更是一个不断反思、不断“踩坑”、并从“坑”中总结出属于自己“不要做”清单的修炼过程。希望这份来自社区的集体智慧，能让你在这条路上，走得更稳、也更远。

资料链接：https://www.reddit.com/r/golang/comments/1pib68y/whats_a_dont_do_this_lesson_that_took_you_years/

还在为“复制粘贴喂AI”而烦恼？我的新专栏 《AI原生开发工作流实战》 将带你：

• 告别低效，重塑开发范式
• 驾驭AI Agent(Claude Code)，实现工作流自动化
• 从“AI使用者”进化为规范驱动开发的“工作流指挥家”

扫描下方二维码，开启你的AI原生开发之旅。

你的Go技能，是否也卡在了“熟练”到“精通”的瓶颈期？

• 想写出更地道、更健壮的Go代码，却总在细节上踩坑？
• 渴望提升软件设计能力，驾驭复杂Go项目却缺乏章法？
• 想打造生产级的Go服务，却在工程化实践中屡屡受挫？

继《Go语言第一课》后，我的《Go语言进阶课》终于在极客时间与大家见面了！

我的全新极客时间专栏 《Tony Bai·Go语言进阶课》就是为这样的你量身打造！30+讲硬核内容，带你夯实语法认知，提升设计思维，锻造工程实践能力，更有实战项目串讲。

目标只有一个：助你完成从“Go熟练工”到“Go专家”的蜕变！ 现在就加入，让你的Go技能再上一个新台阶！

商务合作方式：撰稿、出书、培训、在线课程、合伙创业、咨询、广告合作。如有需求，请扫描下方公众号二维码，与我私信联系。

本文永久链接 – https://tonybai.com/2025/11/24/google-adk-go-in-action

大家好，我是Tony Bai。

上周，我花了一个下午，仅仅是为了让一个Python写的Agent能稳定地调用我Go服务里的一个简单函数。在那一刻，看着屏幕上纠缠的gRPC、Python虚拟环境和混乱的日志，我脑海里只有一个念头：这不对劲，这绝对不是软件工程该有的样子！

显然，不仅仅是我一个人在为此焦虑。

就在最近，一个名为 google/adk-go 的项目悄然开源，并迅速霸榜 GitHub Go 语言趋势榜长达一周之久！ 全球的 Gopher 似乎都在用脚投票，表达着同一个渴望：我们受够了“炼丹”，我们要回归工程！

过去的一年，AI 的浪潮席卷了整个技术圈。我们 Gopher，作为构建云原生世界的中坚力量，看着 Python 社区在 AI 领域“杀”得热火朝天，心中或许都有一个共同的疑问：

“这场 AI 的盛宴，我们 Gopher 的主菜在哪儿？”

我们习惯了用 goroutine 优雅地处理并发，用 channel 安全地传递消息，用静态编译的单个二进制文件征服任何服务器。我们是天生的“工程师”，我们信奉的是可测试、可维护、可部署的软件工程哲学。

然而，当我们尝试踏入 AI Agent 的世界时，却常常感觉自己像一个闯入了“炼丹房”的“机械师”。面对那些需要反复“吟唱咒语”（调 Prompt）、结果飘忽不定的“丹炉”（模型），我们不禁会问：

• 我的 Agent 行为不稳定，怎么写单元测试？
• Prompt 稍微一改，整个“丹方”都可能失效，版本管理怎么做？
• 我如何将这个“充满魔法”的 Python 脚本，与我现有的 Go 微服务体系优雅地集成，而不是变成一坨无法维护的“耦合怪”？

这些问题，不是因为我们不懂 AI，而是因为我们太懂工程。我们厌倦了“炼丹”式的不确定性，我们渴望一种能将 AI 的强大能力，用严谨的工程纪律约束起来的解决方案。

现在，Google 亲自下场，为我们递来了“工程图纸”。

Google ADK for Go：写给工程师的 AI Agent 开发框架

这个霸榜的项目，全称是 Agent Development Kit (ADK) for Go。

这不是又一个“玩具”或“研究性”框架。从它的设计理念中，我看到了一个清晰而坚定的信号——AI Agent 开发，正在从“炼丹”式的“艺术创作”，全面进入“工程化”的“工业生产”时代。

而 ADK for Go 的核心哲学，与我们 Gopher 的信仰不谋而合，那就是——代码优先 (Code-First)。

• 你的 Agent，就是你的 Go 代码： 不再有晦涩的 YAML，不再有天书般的“链”，Agent 的所有逻辑、决策、工作流，都由你亲手编写的、地地道道的 Go 代码来定义。
• 天生的可测试性： 你的 Agent 就是一个实现了 agent.Agent 接口的 struct。这意味着什么？你可以像测试任何 Go 代码一样，go test 走起！Mock 依赖、断言行为，所有你熟悉的工程实践，全部回归。
• Git 即版本管理： Agent 的每一次进化，都是一次清晰的 git commit。Code Review、版本回滚，一切都尽在掌握。
• 云原生无缝集成： 它就是一个标准的 Go 模块，可以被无缝地集成到你的 Gin/gRPC 服务中，打包成一个极小的 Docker 镜像，部署到任何 K8s 集群。

这就是为什么它能霸榜 GitHub 的原因——它不是在教你如何更好地“调优 Prompt”，而是在教你如何用坚实的工程代码，去彻底终结那个不可控的“炼丹”时代。

Google的adk-go，就是那座连接 Gopher 工程世界与 AI Agent 智能世界的桥梁。

和我一起，从零开始“造”一个真正的 AI Agent

坦白说，ADK for Go 刚刚推出，市面上的教程几乎一片空白。文档虽有，但如何将其与真实的工程场景结合，如何理解其设计背后的权衡，如何避开那些必将遇到的“坑”——这些都需要有人去探索，去趟路。

所以，我决定做这件事。

我将以一个“学伴”和“探索者”的身份，推出我的全新付费微专栏：

《Google ADK 实战：用 Go 构建可靠的AI Agent》

在这个专栏里，我不会扮演一个无所不知的专家。相反，我会将我从零开始学习、实践、踩坑、顿悟的全过程，毫无保留地分享给你。

我们将一起，手把手地、从一个空 main.go 文件开始，完成一次令人兴奋的创造之旅：

• 第 1-2 讲：思维转变与灵魂注入
  我们将彻底理解“代码优先”的哲学，拆解adk-go，了解其中的概念、架构和核心组件，并亲手定义出第一个实现了 agent.Agent 核心接口的智能体。

• 第 3 讲：为 Agent 插上“手臂”： 让你的Agent能调用任何Go函数，像操作自己的手脚一样自如
  我们将学会 ADK 的“魔法”函数 functiontool.New，将一个普通的 Go 函数，零成本地转化为 Agent 可用的工具。

• 第 4 讲：赋予 Agent “双核记忆”
  我们将深入 session（短期记忆）和 memory（长期记忆），让我们的 Agent 能够理解上下文，并记起与你的历史交互。

• 第 5 讲：从“单兵”到“军团”： 构建一个懂分工、会协作的Agent团队，自动化完成复杂任务
  我们将学习 workflowagents，通过编排多个专家 Agent，构建一个强大的“代码生成-审查-重构”自动化流水线。

• 第 6 讲：从“原型”到“产品”
  我们将为 Agent 建立科学的评估体系，并最终将其打包成 Docker 镜像，部署到通用的 Kubernetes 环境中。

学完这个专栏，你将收获的，不仅是一个能跑起来的酷炫 AI 项目，更是一套可复用的、工程化的 AI Agent 构建方法论，以及在 AI 新浪潮中，属于我们 Gopher 的那份自信和底气。

加入这场 Gopher 的 AI 工程化之旅

这个微专栏，是我为你，也为我自己准备的一份“AI 时代 Gopher 生存指南”。它凝聚了我对 Go 工程哲学的理解，和我对 AI Agent 未来的全部热情。

微专栏共 6 篇深度长文，每一篇都是我亲手实践、细节满满的 step-by-step “航海日志”。

我没有设定一个高昂的价格，而是希望与更多志同道合的 Gopher 一起探索。所以，订阅这份专栏，仅需你一杯咖啡的诚意。

花一杯咖啡的时间，你或许能得到片刻的清醒；而用同样的价格投入到这里，我希望能为你带来一次思维的升级和技能的跃迁。

点击这里，或扫描二维码，立即加入。

让我们一起，用代码，构建智能。

P.S. 如果你对 AI Agent、Go 语言或者这个微专栏有任何问题，欢迎在评论区留言，我们一起交流探讨！

还在为“复制粘贴喂AI”而烦恼？我的新专栏 《AI原生开发工作流实战》 将带你：

• 告别低效，重塑开发范式
• 驾驭AI Agent(Claude Code)，实现工作流自动化
• 从“AI使用者”进化为规范驱动开发的“工作流指挥家”

扫描下方二维码，开启你的AI原生开发之旅。

商务合作方式：撰稿、出书、培训、在线课程、合伙创业、咨询、广告合作。如有需求，请扫描下方公众号二维码，与我私信联系。