分类 技术志 下的文章

掌握架构师的“编程语言”:将“想法”部署到“人”的艺术

本文永久链接 – 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技能再上一个新台阶!


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

Go的“七宗罪”:一篇“Go依然不够好”如何引爆社区激辩?

本文永久链接 – https://tonybai.com/2025/08/25/go-is-still-not-good

大家好,我是Tony Bai。

在技术圈,平静的湖面下往往暗流涌动。对于Go语言社区而言,这股潜藏已久的暗流,被近期的一篇名为《Go is still not good》的博文彻底引爆。作者Thomas Habets,一位自称拥有超过十年Go使用经验的资深开发者,在他的这篇文章中系统性地列举了他眼中Go语言的“七宗罪”。这篇文章迅速登上Hacker News热榜,吸引了超过700条评论,形成了一场规模空前的社区大辩论。

参与者中不乏Go的早期采纳者、贡献者和日常重度使用者。他们争论的焦点,早已超越了语法糖的优劣,直指Go语言最核心的设计哲学——那些曾被誉为“简单”和“务实”的基石,如今在一些开发者眼中,却成了束缚发展、埋下隐患的“原罪”。

在这篇文章中,我就和大家一起跟随这场激辩,逐一剖析这引发轩然大波的“七宗罪”,看看从中能得到哪些有益的启示。

第一宗罪:歧义之空——nil 的双重身份

这是Go语言中最著名的“陷阱”,也是原文作者打响的第一枪。一个持有nil指针的接口变量,其自身并不等于nil。

package main

import "fmt"

type Error interface {
    Error() string
}

type MyError struct{}

func (e *MyError) Error() string { return "my error" }

func GetError() *MyError {
    // 假设在某种条件下,我们返回一个 nil 的具体错误类型指针
    return nil
}

func main() {
    var err Error = GetError()

    // 输出: false
    // 尽管接口 err 内部持有的值是 nil,但接口本身因为包含了类型信息 (*MyError),所以它不为 nil。
    fmt.Println(err == nil) 

    if err != nil {
        // 这段代码会被执行,然后可能在后续操作中引发 panic
        fmt.Printf("An error occurred: %v (type: %T)\n", err, err)
        // err.Error() // 若MyError的Error方法有解引用操作,此处会panic
    }
}

我们知道:Go的接口(interface)在内部实现为一个包含两部分的“胖指针”(fat pointer):一个指向类型元数据的指针和一个指向实际数据的指针。只有当这两个指针都为nil时,接口变量本身才被认为是nil。在上述例子中,err的内部状态是(type=*MyError, value=nil)。因为类型信息存在,err != nil的判断为真,导致程序逻辑错误地进入了错误处理分支,挑战了开发者的常规直觉。

社区激辩

  • 批评者阵营:Hacker News上,有用户提供了一个经典的Playground示例,展示了这个问题如何在生产环境中导致panic,并评论道:“这确实会在生产中咬你一口,而且在代码审查中极易被忽略。”另一位用户则更为尖锐,他引用了Rob Pike关于Go是为“非研究型、刚毕业的年轻工程师”设计的言论,反问道:“一个声称为了简化编程而设计的语言,却包含如此令人困惑的nil行为,这本身就是一种讽刺。”

  • 辩护者阵营:另一派观点认为,这并非缺陷,而是Go底层数据结构逻辑的直接体现。有开发者解释道:“接口值是一个包含类型和值的偶对。(&Cat, nil)当然不等于(nil, nil)。”他们认为,一旦理解了接口的内存模型,这个问题便不再神秘,甚至可以利用这一特性(例如,在nil接收者上调用方法)。然而,这种辩护本身就强化了批评者的观点:一门标榜高级和简单的语言,却要求开发者对底层的实现细节有如此深刻的理解,这是否可以看作设计上的一种失败呢?

第二宗罪:作用域之惑——被迫扩展的err变量生命周期

Go通过if err := foo(); err != nil语法,优雅地将err变量的作用域限制在if块内,这被广泛认为是最佳实践。然而,当函数调用需要返回除error之外的值时,这种优雅便荡然无存。

bar, err := foo()
if err != nil {
    return err
}
// 此处的err变量将在整个函数剩余部分都有效,即使它现在的值是nil

if err = foo2(); err != nil { // 复用err
    return err
}

// ... 大量代码 ...

return err

Go的短变量声明:=要求左侧至少有一个新变量。为了接收bar这个新值,err也被迫在函数作用域内被重新声明(或首次声明)。这导致err的生命周期被人为地拉长,污染了整个函数的作用域。

社区激辩

  • 批评者阵营:原文作者尖锐地指出,这种设计“强迫你做错误的事情”。一个本应是局部的错误变量,现在却像个幽灵一样在整个函数中游荡,增加了代码阅读者的认知负担。读者必须时刻追踪err变量最后一次被赋值的位置,这极易导致bug,尤其是在重构或修改长函数时。
  • 辩护者阵营:对此的辩护声音较弱,大多认为这是个“可以忍受的小麻烦”。他们认为,这是为了保持语法一致性(:=的规则)而付出的代价。然而,这恰恰暴露了Go在追求一种形式上的“简单”时,牺牲了更重要的“上下文清晰性”。

第三宗罪:所有权之乱——append的隐式副作用

slice是Go的基石之一,但其与底层数组(backing array)的模糊关系,通过append函数暴露无遗,构成了另一个经典的“搬起石头砸自己的脚”。

原文的例子一针见血地揭示了append行为的不可预测性:

package main

import "fmt"

func main() {
    // 案例一:当容量足够时,发生“幽灵写入”
    a := []string{"hello", "world", "!"}
    b := a[:1]                 // b与a共享底层数组,且cap(b) == 3
    b = append(b, "NIGHTMARE") // 修改了b,因为容量足够,直接修改了底层数组
    fmt.Println(a)// 结果:a变成了[hello NIGHTMARE !]

    // 案例二:当容量不足时,修改“失败”
    a = []string{"hello", "world", "!"}
    b = a[:1]
    b = append(b, "BACON", "THIS", "SHOULD", "WORK") // 容量不足,分配了新数组
    fmt.Println(a)// 结果:a依然是[hello world !]
}

我们知道:append的行为取决于slice的容量(cap)。如果追加后未超出容量,它会就地修改底层数组;否则,会分配一个新的、更大的数组。这种设计不仅让append的性能变得不确定,更严重的是,它破坏了函数调用的封装性,使得slice既不像值类型(可能被远程修改),也不像纯粹的引用类型(可能因重分配而断开联系)。

社区激辩

  • 批评者阵营:Hacker News上一位获得高赞的评论是这样的:“append的例子是Go缺陷中最恶劣、最不可原谅的。”这种行为使得数据流变得难以追踪,迫使开发者必须时刻警惕slice的容量,或养成防御性编程的习惯,例如总是重新接收append的返回值。这与Go追求的“明确”背道而驰。
  • 辩护者阵营:支持者认为这是为了性能做出的合理权衡,避免了不必要的内存分配。他们强调,Go官方文档已明确说明了slice的工作原理。然而,这再次回到了那个核心问题:一门标榜“简单”的语言,是否应该包含如此微妙且需要深度理解才能安全使用的核心数据结构?

第四宗罪:作用域陷阱——函数级的defer

defer是Go处理资源释放的利器,但它的作用域是整个函数,而非其所在的词法块(lexical scope)。这在循环中处理资源时会成为一个严重的资源泄漏问题。

for _, file := range files {
    f, err := os.Open(file)
    if err != nil { /* ... */ continue }
    // defer不会在每次循环结束时执行,而是堆积到函数返回时执行
    // 如果文件列表很长,将耗尽文件句柄
    defer f.Close()
    // ... process file
}

根本原因在于defer语句的执行被推入一个与当前函数关联的栈中,在函数返回前统一执行。这简化了编译器的实现,并确保了panic时资源也能被释放。

社区激辩

  • 批评者阵营:一个开发者的高赞评论代表了社区的普遍困惑:“我至今不明白defer为什么是函数作用域而非词法作用域。”这与C++的RAII或Java的try-with-resources相比,是一种设计上的倒退。公认的解决方法是使用匿名函数func(){…}()包裹循环体,但这无疑增加了代码的丑陋和复杂性。
  • 辩护者阵营:有用户指出,函数级作用域也有其便利之处,例如可以在if块中有条件地注册一个defer。但总体而言,社区普遍认为,默认应该是更安全、更符合直觉的词法作用域。

第五宗罪:异常之隐——被标准库“吞噬”的panic

Go的哲学是:error用于可预见的错误,panic用于程序无法继续的灾难。然而,作者指出,标准库中的fmt.Print和net/http服务器等关键部分,会主动recover从panic中恢复,这破坏了panic的基本约定。

这意味着开发者必须编写“异常安全”的代码。你必须假设任何传递给标准库的代码都可能在panic后被恢复。因此,像互斥锁(mutex)这样的资源必须通过defer来确保释放,否则一旦发生被“吞噬”的panic,就会造成死锁。作者愤怒地指出:“所有希望都破灭了。你必须写异常安全的代码,但你又不应该使用异常。你只能承受异常带来的所有负面影响。”

社区激辩:这一点在社区中几乎没有辩护的声音。这被视为一种设计上的不一致和“伪善”。语言在表层倡导一种错误处理哲学,却在底层库中悄悄破坏它,迫使开发者为这种矛盾买单。

第六宗罪:编码之殇——对非UTF-8的“绥靖政策”

Go的string类型本质是只读的[]byte,不强制其为合法的UTF-8。这在与操作系统交互(如处理文件名)时提供了灵活性,但也埋下了隐患。

作者控诉,这种“宽松”策略是数据丢失的根源。当工具不假思索地按UTF-8处理文件名时,遇到非UTF-8编码的文件名可能会跳过或处理失败,导致在备份、恢复等关键操作中“静默地”遗漏数据。

社区激辩

  • 批评者阵营:他们认为类型系统应防止此类错误。有用户激烈地评论道:“Go让你很容易做那些看起来99.7%的时间都有效,但却是愚蠢、错误、不正确的事情……然后有一天,你的用户就因为一个非UTF-8文件名而永久丢失了数据。”
  • 辩护者阵营:另一方则认为Go的做法才是务实的。有用户指出,一个强制Unicode正确性的文件接口在真实世界中是有问题的。Rust的OsStr虽然严谨,但人体工程学极差。Go的方式虽然“混乱”,但在实践中更方便。这揭示了严谨性与便利性之间的深刻矛盾。

第七宗罪:承诺之虚——伪善的“简单”与被忽视的性能

这并非单一技术点,而是对Go整体设计理念的综合批判。

  • 简单性的代价是复杂性转移:许多评论者指出,Go语言层面的“简单”,是把复杂性推给开发者来承担。没有枚举、没有强大的泛型(即使1.18加入了,也限制颇多)、没有Result类型,导致开发者需要手写大量重复的样板代码和自定义数据结构。
  • 内存管理的“信任危机”:原文作者提到“RAM is cheap”是危险的思维。Hacker News上有开发者分享了其在内存敏感项目中被Go的非压缩GC和堆碎片化问题折磨的经历,他们甚至不得不重写部分标准库以避免内存分配。这与Go宣称的“高性能”和“无忧GC”形成了鲜明对比。

为何着一篇文章能掀起千层浪?

这场激辩之所以如此激烈,是因为它触及了Go社区内部长期存在的深层张力:

  1. “Google的Go” vs “世界的Go”:Go的许多设计源于解决Google内部特定问题的需求(C++编译慢、monorepo文化)。这种“出身”决定了它在某些方面与更广阔的编程世界存在脱节。早年对单调时钟的忽视就是典型例子。
  2. 简单主义 vs 现代语言特性:Go的创造者们带着一种“回归本源”的复古主义情怀,刻意回避了过去几十年编程语言理论的发展成果,如高级类型系统、代数数据类型等。这使得Go易于上手,但也让它在处理复杂逻辑时显得捉襟见肘,迫使开发者“用代码的冗余换取语言的简单”。
  3. 显式 vs 便利:if err != nil是显式的,但它不便利。Result类型和?操作符是便利的,但它在某种程度上是隐式的。Go坚定地站在了“显式”这一边,但社区中渴望“便利”的声音从未停止。

小结

将Go的这些“罪状”简单归结为“错误”也是片面的。它们是Go强硬的、自洽的设计哲学所带来的必然产物。

  • 这是一门有“历史”的现代语言:Go的设计深受其创造者们在C、Unix、Plan 9上的经验影响。它继承了C的简洁,但也继承了其对底层细节的暴露。
  • 承认权衡,理解其生态位:Go在“开发效率”、“运行性能”和“语言简单性”之间做出了明确的取舍,在云原生、微服务领域找到了无与伦比的“甜蜜点”。
  • 缓慢的进化也是一种承诺:Go团队对语言的改变极为谨慎,以维护其著名的向后兼容性承诺。但它并非一成不变。泛型的加入、for range循环变量作用域的修正,都表明Go在倾听社区的声音。

《Go is still not good》及其引发的激辩,为我们提供了一个宝贵的窗口,去重新审视这门既年轻又充满“历史感”的语言。它提醒我们,没有完美的语言,只有充满权衡的工具。

对于Go开发者而言,理解这“七宗罪”的来龙去脉,不仅能帮助我们写出更健壮、更地道的代码,更能让我们清晰地认识到Go的优势与边界。与其无休止地争论它是否“足够好”,不如深入思考:它是否是解决我们当前问题的正确工具? 而这,或许才是这场大辩论给予我们的最大启示。


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

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

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

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

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


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

如发现本站页面被黑,比如:挂载广告、挖矿等恶意代码,请朋友们及时联系我。十分感谢! Go语言第一课 Go语言进阶课 Go语言精进之路1 Go语言精进之路2 Go语言第一课 Go语言编程指南
商务合作请联系bigwhite.cn AT aliyun.com

欢迎使用邮件订阅我的博客

输入邮箱订阅本站,只要有新文章发布,就会第一时间发送邮件通知你哦!

这里是 Tony Bai的个人Blog,欢迎访问、订阅和留言! 订阅Feed请点击上面图片

如果您觉得这里的文章对您有帮助,请扫描上方二维码进行捐赠 ,加油后的Tony Bai将会为您呈现更多精彩的文章,谢谢!

如果您希望通过微信捐赠,请用微信客户端扫描下方赞赏码:

如果您希望通过比特币或以太币捐赠,可以扫描下方二维码:

比特币:

以太币:

如果您喜欢通过微信浏览本站内容,可以扫描下方二维码,订阅本站官方微信订阅号“iamtonybai”;点击二维码,可直达本人官方微博主页^_^:
本站Powered by Digital Ocean VPS。
选择Digital Ocean VPS主机,即可获得10美元现金充值,可 免费使用两个月哟! 著名主机提供商Linode 10$优惠码:linode10,在 这里注册即可免费获 得。阿里云推荐码: 1WFZ0V立享9折!


View Tony Bai's profile on LinkedIn
DigitalOcean Referral Badge

文章

评论

  • 正在加载...

分类

标签

归档



View My Stats