Golang - Tony Bai

本文永久链接 – https://tonybai.com/2025/09/21/why-maintainers-should-say-no-to-good-idea

大家好，我是Tony Bai。

维护一个开源项目，最难的部分往往不是修复 bug 或实现新功能，而是对一个设计精良、技术上无懈可击的“好主意”说“不”。Prefect 和 FastMCP 的创始人 Jeremiah Lowin 最近发表了一篇深刻的文章，探讨了这种看似“不近人情”的行为背后的管理哲学。他指出，项目的成功最终取决于其愿景的连贯性，而非功能的堆砌。在 LLM 让代码变得“廉价”的今天，这种对项目“灵魂”的守护变得比以往任何时候都更加重要。

这篇文章让我产生了强烈的共鸣。近期，当我在维护自己的一个小工具类开源项目 bigwhite/issue2md 时，也遇到了类似的抉择：一个国外开发者提交了一个由Gemini cli实现的功能完备的 PR，但我最终还是选择了拒绝。那一刻，我深切地体会到了 Lowin 所描述的、作为维护者的艰难与责任。

一个看似完美的“好主意”，为何可能成为项目的“威胁”？Lowin 的文章为我们提供了深刻的答案。在本文中，我们就一起来看看Lowin给出的这一套在 AI 时代下尤为宝贵的实践剧本。

软件的灵魂：与用户心智模型一致的抽象

文章开篇便引用了 Prefect CTO Chris White 的一句名言：

“人们选择一个软件，是因为它的抽象与他们的心智模型相符。”

这正是开源维护者的核心职责：首先，建立并清晰地阐述这个心智模型；然后，不懈地构建反映该模型的软件。

一个功能，即便在名义上很有用，但如果与项目的“精神”不符，它就可能成为一种威胁。这种威胁的形式多种多样：

范围失控：为一个 CLI 工具请求增加 GUI。
增加复杂度：为一个用户的利基问题，给所有用户增加维护负担。
破坏一致性：最微妙的，是引入一个与项目既定模式相悖的 API，为未来的用户制造认知失调。

维护者的工作，就是像守护神一样，捍卫项目的灵魂，确保每一次代码的合并都是对项目愿景的增强，而非稀释。

LLM 时代的新挑战：廉价代码与昂贵的审查

曾几何时，编写代码是一项高成本、高投入的活动。贡献者在投入大量时间之前，通常会先通过 issue 进行讨论，以确保自己的努力不会白费。

然而，LLM 的出现彻底颠覆了这一模式。代码变得廉价，而讨论和审查变得稀缺。

作者观察到一种新常态：用户带着一个从未讨论过的、由 LLM 生成的、功能完备的 PR 突然出现。这段代码“能用”，写得也不错，但它是在完全没有项目哲学背景的情况下生成的。它的目标函数是满足单个用户的请求，而不是维护整个项目的愿景。

这导致了信噪比的急剧下降。一个未经请求的 PR，现在更有可能是一次对低成本贡献的高成本审查。维护者的时间和精力，正被大量“看起来不错”但“感觉不对”的代码所消耗。

维护者的剧本：如何优雅地拒绝与引导

面对这种新形势，维护者该如何应对？

1. 明确举证责任

作者强调，举证责任永远在贡献者，而非仓库本身。维护者无需为拒绝一个 PR 寻找借口。相反，可以简单地表示：“我们不确信框架应该为用户承担这项责任。” 如果贡献者希望说服你，那么这种努力对整个社区都是有益的。

在 FastMCP 项目中，他们尝试过要求“每个 PR 必须关联一个 issue”，结果却适得其反：用户在提交 PR 前一秒，创建一个只有一句话的 issue。这说明，程序化的流程无法替代清晰的沟通和哲学层面的对齐。

2. 转移维护责任

当一个 PR 被合并时，会发生一次重大的责任转移。未来的 bug、用户困惑、API 不一致性，甚至是后续的功能增强请求，都会落在维护者的肩上。

对于那些有用但可能不适合核心项目的功能，FastMCP 引入了 contrib 模块作为解决方案。

contrib 模块中的功能由其作者全权维护。
不保证与未来版本的项目兼容。

这为那些有价值但“非核心”的想法提供了一个出口，既鼓励了社区贡献，又保护了核心项目的稳定性和一致性。

3. 用文档作为第一道防线

如何扩展这种管理哲学？答案是文档。清晰的开发者指南和项目宗旨声明，是维护者的第一道防线。它们在贡献者写下第一行代码之前，就阐明了项目的哲学，设定了期望。

这会形成一个强大的正反馈循环：

项目的愿景越清晰 → 越能吸引认同该愿景的贡献者 → 他们的贡献强化并完善了愿景 → 进一步证明了项目世界观的正确性。

结论：今天的“不”，是为了明天热情的“是”

Jeremiah Lowin 的分享提醒我们，开源维护远不止于技术。它是一种深思熟虑的、刻意的管理艺术。在 AI 辅助编程日益普及的今天，这种对项目哲学和社区文化的守护显得尤为珍贵。

作者在文末分享了他在 MCP 委员会会议上的观察。面对这个处于技术炒作风口浪尖的年轻协议，委员会没有被“ appease the loudest voices”（安抚最大声的声音）的压力所淹没，而是始终围绕一个核心问题进行辩论：“这是个好主意。但它属于协议的职责范围吗？”

这种坚守，正是将一个有用的项目，锤炼成一个伟大项目的必要之功。

对于所有开源维护者而言，每一次用户的参与都值得庆贺。我们的责任是确保，今天对一个偏离航道的“好主意”说出的“不”，能够帮助这位贡献者，在未来带着一个与项目愿景完美契合的方案归来时，得到我们由衷的、热情的“是！”

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

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

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

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

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

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

本文永久链接 – https://tonybai.com/2025/09/20/refactoring-go-in-large-codebases

大家好，我是Tony Bai。

“要不……我们重写吧？”

在任何一个发展到一定阶段的 Go 项目中，这句话都像一个幽灵，反复出现在技术讨论中。面对一个布满补丁、逻辑盘根错节、维护成本日益高昂的“大泥球” (Big Ball of Mud)，彻底推倒重来的想法总是充满了诱惑。

然而，这往往是通往灾难的捷径。重写项目常常陷入延期、超出预算、甚至最终失败的泥潭。那么，正确的道路究竟在何方？

在 GitHub 的软件工程师 Brittany Ellich 最近的一次分享中，她系统性地为大型 Go 项目的维护者提供了一份清晰的实践指南。本文将为你完整呈现这份源自顶级工程团队的宝贵经验。

核心困境——为何“重写”如此诱人？

在深入探讨如何重构之前，我们必须先理解“为何不应轻易重写”。推动重写的往往是三个看似合理、实则充满谬误的论点。

谬误一：“重写会更快”

这是最普遍的错觉。我们往往只看到了系统中那 20% 腐烂的部分，并天真地认为重写它们就是全部工作。但我们忽略了：

那 80% 仍在正常工作的部分也必须重写。
在重写期间，旧系统仍需维护，团队精力被一分为二。
数据迁移和系统下线本身就是极其复杂且耗时的大型项目。

最终，“快速重写”几乎无一例外地会演变成一场旷日持久的拉锯战。

谬误二：“这次我们能写出‘干净’的代码”

“如果我们从头开始，就能‘做对’。” 这句话听起来无比正确，却忽视了一个残酷的现实：

“生产应用程序本质上就是混乱的。这是特性，不是 Bug。”

那些看似丑陋的边界情况，恰恰是多年用户反馈积累下的业务逻辑；那些晦涩的变通方案，是无数次深夜故障排查后沉淀下的组织知识。一个“干净”的重写版本，往往意味着这些宝贵的隐性知识被全部丢弃，你将不得不重新踩一遍所有过去的坑。

谬误三：“新技术栈能解决我们的问题”

“如果我们用 Rust 重写，性能问题就都解决了！” 这是技术驱动的典型陷阱。

学习一门新技术很容易，但精通它很难。在重写项目中引入一个全新的技术栈，意味着团队将在“学习”和“构建”之间反复横跳，犯下大量新手错误。更明智的做法是，用现有、成熟的技术栈，通过重构解决已知问题，这远比用一门新语言写出同样有问题的代码要高效得多。

诊断结论：重构，而非重写，是持续改进的唯一路径。正如敏捷宣言早已告诉我们的那样，最好的软件产品源于持续的改进，而非完美的规划。

系统性重构框架——一套可落地的实践指南

既然重写不可取，我们该如何系统性地对现有 Go 代码库进行“外科手术”？Ellich 提出了一套以“易读、易测、易改”为核心原则的实践框架-THINK。

实践一：建立测试安全网

在修改任何代码之前，第一步永远是建立安全网。如果你的代码库测试覆盖率不足，可以采用 Michael Feathers 在《修改代码的艺术》中提出的“特性刻画测试” (Characterization Tests)。这种测试不关心代码的内部逻辑，只关心“给定某种输入，是否能得到预期的输出”，以此锁定现有行为，确保你的重构不会引入新的 Bug。

实践二：统一错误处理

在 Go 中，错误处理的方式直接影响着应用的整体结构。随着时间的推移，代码库中往往会出现多种错误处理风格：丢失上下文、日志与返回并存的“双重处理”、或是被忽略的“静默失败”。选择一种统一的、规范的错误处理方式（例如，统一使用 fmt.Errorf 配合 %w），并将其应用到整个代码库，是性价比极高的重构起点。记住 Go 的谚语：“错误是值”，像对待普通值一样，认真地对待它们。

实践三：定义清晰的接口

接口定义了系统的边界。清晰的边界是实现“易测”和“易改”的关键。
* 拆分大接口：遵循接口隔离原则，将臃肿的大接口拆分成多个专注于单一职责的小接口。这能避免客户端依赖它们不需要的方法，并极大地简化 mock 的编写。
* 警惕 any (interface{})：除非在序列化等少数场景，否则应避免使用空接口。明确的类型是 Go 静态类型优势的体现，它能在编译期而非运行时发现错误。

实践四：收窄与解耦依赖

紧耦合是代码变得难以修改的根源。

使用依赖注入 (Dependency Injection)：不要在业务逻辑函数中直接创建数据库连接等外部依赖。通过函数参数或结构体字段将依赖（最好是接口）注入进来，能让单元测试摆脱对真实外部环境的依赖。
分离关注点：避免在整个应用中传递一个混合了 API、数据库、验证逻辑的“全能”模型(用户数据结构)。在应用的不同层（API 层、数据层）定义各自所需的、职责单一的模型，能让各层的修改互不影响。
外部化业务规则：将易变的业务逻辑（如折扣计算、计费规则）从代码中剥离，交由配置或独立的规则引擎服务管理。这样，当业务规则变更时，无需工程师介入修改代码和重新部署。

实践五：坚持持续改进

不要寄希望于“重构冲刺周”或“技术债偿还日”。这些形式化的活动往往收效甚微。最好的策略，是在日常的功能开发中，持续、小步地进行重构。这正是“童子军军规”——“让营地比你来时更干净”——在软件开发中的体现。

优先级规划——如何决定重构的起点？

重构任务千头万绪，如何选择最有价值的切入点？Ellich 提供了一个简单而高效的“影响力-费力” (Impact-Effort) 矩阵。

第一优先级：高影响，低费力 (Quick Wins)

这些是“速效成果”。例如，为关键路径的错误信息添加上下文、将硬编码的常量提取到配置中、用具体类型替换空接口等。这些改动风险低，见效快，能迅速提升代码质量和团队信心。

第二优先级：高影响，高费力 (Major Projects)

这些是需要严肃对待的“大型项目”。例如，拆分核心模块的大接口、标准化整个代码库的错误处理、分离紧耦合的核心模型等。这些任务需要被当做正式的功能需求来规划和排期，它们能从根本上改善系统健康状况。

第三优先级：低影响 (Ignore for now)

任何低影响的工作，无论费力与否，都应该被有意识地忽略。避免团队将宝贵的精力浪费在价值不大的事情上，直到它们有朝一日变成了高影响的问题。

现代助推器——让 AI 成为你的重构伙伴

过去，“持续重构”说起来容易做起来难，因为它会挤占开发新功能的时间。但现在，AI 编码助手（如 GitHub Copilot Agent）正在改变游戏规则。

Ellich 分享了她的团队如何利用 AI 来处理那些“重要但不紧急”的重构任务，让它们不再堆积在积压列表 (Backlog) 中直至腐烂：

提升测试覆盖率：给 AI 一个明确的指令（“为 lib/services 目录下未被覆盖的路径创建表驱动测试”），它可以快速生成高质量的测试用例。
标准化代码模式：提供一个代码片段作为范例（“使用这种新的错误处理方式，并将其应用到 lib/services 目录下的所有文件中”），AI 可以在整个代码库中系统性地推行这一模式。
迁移技术方案：创建一个小型的、人工完成的 PR 作为示例（“参照这个 PR，将项目中所有旧的 mocking 库替换为新库”），然后让 AI 将这个变更应用到所有相关文件中。

AI 的出现，让“持续处理技术债”的成本被前所未有地降低。它使我们终于有能力在交付新功能的同时，系统性地改善代码库的健康状况。