本文永久链接 – https://tonybai.com/2025/09/05/go-proxy-revise-background-refresh-pacing

大家好，我是Tony Bai。

2025年8月14日，Go开发者Ted Unangst发表了一篇措辞犀利的博文——《What is the go proxy even doing?》。他用服务器日志作为证据，公开质疑Go官方模块代理（proxy.golang.org）对其个人代码托管服务humungus.tedunangst.com产生了“洪水般”的、看似毫无意义的巨大流量。这个事件迅速在社区发酵，将一个通常在后台默默工作的核心基础设施，推上了风口浪尖。当然在我的印象中，这已经不是Go社区第一次“抱怨” 官方Go proxy的“诡异”行为给一些小型站点带来的烦恼了。

不过不同的是，这次Go团队的前技术leader、核心成员Russ Cox (rsc) 迅速响应，在Go的官方issue追踪系统中创建了两个关键问题（#75120 和 #75191），不仅承诺调查并解决问题，更罕见地、极其详尽地公开了Go Module Proxy的内部工作原理、缓存策略以及导致此次事件的深层原因。

这场由一篇博文引发的“悬案”及其官方复盘，为我们提供了一个绝佳的机会，去深入理解Go Module Proxy这个我们每天都在使用，却又知之甚少的系统。它背后的“背景刷新”机制，究竟是为了提升开发者体验的“优化”，还是在某些边缘情况下会演变成对小型开源社区的“DDoS”？

事件回顾：来自小型服务器的“呐喊”

Ted Unangst的博文主要控诉了以下几个现象：

1. 持续的背景流量：即使没有任何新版本发布，proxy.golang.org也会以几分钟一次的频率，持续尝试从他的服务器hg clone（克隆）多个仓库。由于他的服务器设置了24小时内只允许一次克隆的速率限制，这些请求大多被429 Too Many Requests拒绝，但在日志中形成了持续的“背景辐射”。
2. “惊群效应”（Thundering Herd）：当他推送一个新版本（一个新tag）并本地执行go mod tidy后，短短14秒内，他的服务器就遭到了来自Google不同IP地址的、数十个并发的hg clone请求。他将其形容为“洪水来了”。
3. 低效的拉取策略：Proxy每次都执行完整的hg clone，而不是更高效的hg pull，这对于非Git的VCS（版本控制系统）来说，意味着巨大的带宽浪费。

Unangst的质疑直击要害：“为什么你们要这样构建一个分布式系统？……难道Google认为从我的服务器下载比从他们自己的云存储下载更便宜吗？”

Go官方的深度复盘：揭开代理的神秘面纱

Russ Cox的官方回应堪称透明沟通的典范。他不仅承认了问题的存在，还详细解释了Proxy的设计理念和实现细节，让我们得以一窥其内部运作。

Go Module Proxy的核心目标

• 可用性与可靠性：作为Go生态的中央缓存，确保开发者在任何上游代码仓库宕机时，依然能获取到模块。
• 降低延迟：通过主动的背景刷新，提前将热门或近期被访问过的模块信息更新到缓存中，使得开发者在执行go get等命令时，能立即获得响应，而不是等待Proxy实时回源。

缓存与刷新策略的权衡

Proxy缓存多种类型的数据，每种都有不同的刷新策略，而这些策略正是问题的根源：

• 模块Zip包：

  • 有许可证：被认为是可再分发的，永久缓存，从不刷新。
  • 无许可证：被视为不可再分发，缓存30天后过期。为了避免用户请求时缓存失效导致的高延迟，Proxy会在其25天“高龄”时触发刷新，但前提是过去1天内有人请求过这个版本。

• 版本列表 (go list -m -versions …)：

  • 缓存3小时后过期。为了让go get -u能尽快看到新版本，Proxy会在其25分钟“高龄”时触发刷新，但前提是过去3天内有人请求过这个列表。

• 版本查询 (go get module@main)：

  • 缓存1小时后过期。同样，在25分钟时触发刷新，前提是过去1天内有人请求过。

“万恶之源”：不匹配的刷新与访问周期

在issue #75191中，rsc进行了一次深刻的自我反思，指出了这些策略中的一个致命缺陷——读放大（Read Amplification）。

• 模块Zip包（无许可证）：刷新周期（25天）与“近期访问”周期（1天）不匹配，但因为时间跨度大，影响不大。

• 版本列表：刷新周期是25分钟，但触发条件是过去3天内有一次访问即可。这意味着，一个开发者在周一的一次go get -u，将导致Proxy在接下来的72小时内，每25分钟就去上游仓库检查一次更新！

  • 最坏情况下的读取放大：3天 * 24小时/天 * 60分钟/小时 / 25分钟/次 ≈ 172.8次。一次用户请求，可能导致Proxy向上游发起172.8次刷新！

• 版本查询：类似地，一次go get …@main请求，可能导致24 * 60 / 25 ≈ 57.6次刷新。

rsc坦诚，这种激进的刷新策略源于早期社区对“go get无法立即看到新版本”的普遍抱怨，是当时Go团队为了优化开发者体验而做出的决策。然而，对于那些不常用（比如几天才被访问一次）且托管在非Git（如Mercurial）小型服务器上的模块，这种策略就演变成了一场流量灾难。

解决方案：重新“步调一致”

Go团队提出的解决方案，是让刷新周期与“近期访问”的定义“步调一致”（Pacing）。新的策略是：

• 版本查询：每25分钟刷新一次，但前提是过去25分钟内必须有用户请求。
• 版本列表：每25分钟刷新一次，但前提是过去25分钟内必须有用户请求。

这个看似微小的改动，却有着深远的影响：

• 对于热门模块：几乎没有影响，因为它们每时每刻都有用户在请求。
• 对于无人问津的模块：没有影响，它们不会被刷新。
• 对于偶尔被访问的模块：影响巨大。现在，一次用户请求最多只会触发未来25分钟内的一次背景刷新。最坏情况下的读取放大被降至最优的1倍。

这意味着，Go Module Proxy因为背景刷新而产生的上游流量，将永远不会超过一个没有缓存、所有请求都实时回源的代理所产生的流量。

对Go开发者和开源维护者的启示

这场事件不仅仅是Go团队的一次内部优化，它为整个生态的参与者都带来了宝贵的经验：

1. 开源模块维护者：如何保护你的服务器？

• 使用Git：Go Proxy对Git有特殊的轻量级刷新优化。它可以通过git ls-remote来检查更新，而无需克隆整个仓库。对于Mercurial、Bazaar等VCS，目前仍需要完整克隆。 issue #75119 正在追踪为Mercurial添加类似优化的工作。
• 添加LICENSE文件：如果你的代码允许再分发，务必在仓库根目录添加一个被Go识别的LICENSE文件。这将让你的模块版本被Proxy永久缓存，彻底免除Zip包的刷新流量。
• 了解求助渠道：Go团队在issue中明确表示，如果你的服务器遭受了来自Proxy的过多流量，应该去Go的官方issue追踪系统报告。他们已经添加了FAQ条目来引导用户。

2. Go模块使用者：如何做一个“好公民”？

• 理解你命令的“涟漪效应”：下一次你输入go get -u或go get module@main时，请意识到这个简单的命令可能会给模块的源服务器带来持续一段时间的刷新压力。
• 工具开发者请注意：如果你正在编写扫描或爬取Go模块的工具，请尽可能使用https://proxy.golang.org/cached-only端点。这将只访问Proxy的缓存，不会触发任何到上游服务器的回源或刷新请求。

3. 对Go团队的思考：简单性与复杂性的永恒权衡

这个事件也揭示了Go语言哲学的一个侧面。Go团队为了追求用户体验的“简单”（即时获取最新版本），在Proxy的内部引入了“复杂”的、带有潜在风险的刷新逻辑。当这种复杂性与现实世界的多样性（不同的VCS、不同的模块流行度）碰撞时，问题便暴露出来。

最终的解决方案，回归到了一个更“简单”、更可预测的模型。这再次印证了软件工程的一条黄金法则：简单的、可预测的系统，长期来看往往比一个充满“智能”优化的复杂系统更加健壮。

小结：一次迈向成熟的进化

Go Module Proxy的这次“流量悬案”，最终以一次开放、透明的社区互动和深刻的技术改进而告终。它既解决了小型服务器维护者的燃眉之急，又推动了Go核心基础设施向着一个更公平、更健壮、更尊重生态多样性的方向进化。对于我们开发者而言，这是一个了解Go Proxy内部机制的宝贵机会，也是一堂关于分布式系统设计、社区责任和技术权衡的生动课程。

参考资料

• https://github.com/golang/go/issues/75191
• https://github.com/golang/go/issues/75120
• https://flak.tedunangst.com/post/what-is-the-go-proxy-even-doing

想系统学习Go，构建扎实的知识体系？

我的新书《Go语言第一课》是你的首选。源自2.4万人好评的极客时间专栏，内容全面升级，同步至Go 1.24。首发期有专属五折优惠，不到40元即可入手，扫码即可拥有这本300页的Go语言入门宝典，即刻开启你的Go语言高效学习之旅！

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

本文永久链接 – https://tonybai.com/2025/08/25/documents-the-architects-programming-language

大家好，我是Tony Bai。

从初级到高级，开发者的职业路径通常是清晰的：写出更好的代码。但当站在高级工程师的十字路口，是转向管理还是深入技术成为架构师？许多人选择了后者，却发现这个角色的定义模糊不清。最近，stackoverflow的一篇精彩的博客文章《文档：架构师的编程语言》提出了一个深刻的洞见：高级开发者将代码部署到代码构成的系统中，而架构师将想法部署到人构成的系统中。

本文将和大家一起来学习一下文章中的观点和方法，并探讨为何高效的文档写作，是工程师实现这一关键角色转变的核心技能。

架构师之路：一个定义模糊的岔路口

对于许多热爱技术的资深工程师来说，放弃编码转向管理岗是一个艰难的抉择。架构师（Architect）或首席工程师（Principal Engineer）的职业路径，似乎提供了一个两全其美的方案：既能继续深入技术，又能扩大个人影响力。

然而，架构师的角色究竟与高级开发者有何不同？毕竟，他们看起来都在做相似的事情：写代码、审查 PR、讨论部署流水线。文章作者一针见血地指出了核心区别：

• 高级开发者知道如何将代码部署到由代码构成的系统中。
• 架构师知道如何将想法部署到由人构成的系统中。

这并非一句空洞的比喻。它意味着架构师的核心工作，是超越单纯的代码实现，去解决那些真正阻碍项目前进的、更大的“人的问题”：沟通、说服和决策。

文档：部署“想法”的“基础设施即代码”

在软件世界里，我们无法仅仅通过一次 git push 就启动一个跨越数月的大型项目、重写一个核心服务，或者为一个新产品选定技术栈。这些重大决策需要跨团队、跨职能的协作、输入和共识。

那么，我们如何可靠地、可重复地将一个复杂的“技术想法”部署到由不同观点、不同背景的人组成的组织中呢？作者给出的答案是：文档。

Confluence, Google Docs, Notion… 这些工具就是架构师的“部署平台”。一篇精心撰写的文档，是推动想法落地最有效的“传输协议”和“基础设施即代码”。它能：

1. 异步地将你的想法传递给所有利益相关者。
2. 结构化地呈现问题背景、方案和权衡。
3. 持久化地记录决策过程，供未来追溯。
4. 最高效地利用关键人物（通常是最忙碌的人）的碎片化时间。

优秀技术文档的原则与技巧

许多程序员对写作感到畏惧，认为其主观且难以掌握。但文章指出，编写优秀的技术文档并不需要文学天赋，只需要掌握几个简单的技巧。

技术文档宣言

作者提出了一个类似“敏捷宣言”的文档价值观：

• 随时记下东西 胜过 担心如何组织它们
• 文档化的文化 胜过 走过场的行为
• 思考什么才重要 胜过 使用模板
• 某个时间点的文档 胜过 持续更新

核心思想是：先写下来，再求完美。 与其纠结于完美的格式，不如先把你知道的记录下来。

两个魔法技巧：要点和标题

1. 要点 (Bullet Points)：这是架构师最好的朋友。它强迫你以结构化、信息密集的方式思考，而不是追求华丽的辞藻。对于读者而言，要点易于快速扫描，能在最短时间内获取核心信息。
2. 标题 (Headers)：使用有意义的标题来组织你的要点，就像在编程中将一个大函数重构成多个小函数一样。一个清晰的“上下文（Context）”标题，能迅速帮助读者（包括未来的你）回忆起项目的背景和约束。

文档的生命周期：一次性的“脚本”，而非“活服务”

成为架构师的一个重要的心态转变是：将大多数文档视为一次性的 Bash 脚本，而不是需要持续维护的 SaaS 应用。 这点与笔者近几年的实践不谋而合。

一篇设计文档、一个项目提案，一旦完成了它的使命——即推动决策、同步信息——它的价值就会随着时间的推移而递减。强求所有文档都保持最新是不现实的。

因此，作者提出了一个反直觉但极其有效的组织方法：按时间顺序组织文档

• 传统做法（按主题）：为每个功能或项目创建一个文件夹。这会导致文件夹价值不均，新旧文档混杂，甚至相互矛盾，查找困难。
• 推荐做法（按时间）：按年份 -> 迭代（Sprint）来组织。这种方式保留了清晰的时间线，当你通过搜索找到一篇文档时，能立刻了解它是在什么背景下、与哪些其他事件同时发生的。至于按主题查找？“那是搜索框的工作。”

架构师必备的“文档武器库”

文章最后还提供了一个高价值的附录，列举了几种在工程组织中最具影响力的文档类型。对于架构师来说，这些就是你的核心工具集：

• 架构概览 (The architecture overview)
  • 目的：帮助所有人快速理解系统的结构和设计。
  • 时机：构建新系统或重构现有系统之前。
• 开发设计 (The dev design)
  • 目的：在你写下大量代码前，获取关于实现思路的反馈。
  • 金句：“你写的文档越多，你需要写的代码就越少。” 一份好的设计文档能帮你避免因误解、错误假设和设计缺陷导致的返工。
• 项目提案 (The project proposal)
  • 目的：阐明一个项目的价值和成本，以获得资源分配。
  • 技巧：让你的提案易于被技术和非技术决策者“点头同意”。
• 开发者预测 (The developer forecast)
  • 目的：当你预见到一个决策可能带来负面结果时，以中立的、建设性的方式提出风险和缓解方案。
• 技术选型清单 (The technology menu)
  • 目的：在面临技术选型（例如，为新的 Go 微服务选择 RPC 框架）时，通过对比，帮助团队达成共识。

结论

从一个出色的开发者成长为一名卓越的架构师，其核心转变在于影响力的半径。代码的影响力作用于机器，而想法的影响力作用于人。文档，正是放大和部署后者影响力的核心媒介。

它不是编程的替代品，而是编程活动的“元编程”。一篇好的文档，可以在代码被编写出来之前，就解决掉项目中最大的瓶颈——那些关于人的沟通、协同和决策问题。对于所有追求技术卓越的工程师而言，将写作和文档管理提升到与编码同等重要的高度，是通往架构师之路的必经修炼。

资料链接：https://stackoverflow.blog/2025/08/20/documents-the-architect-s-programming-language/

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

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

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

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

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

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