工程实践 on 止语Lab

AI能审代码，但审不了你的决策

Wed, 22 Apr 2026 15:58:50 +0800

上周审查一个 AI 生成的 PR，工具扫完给了全绿：无空指针、并发安全、错误处理完整、命名规范。

但我越看越不对。

这段代码在给一个用户偏好配置项加缓存层。用户偏好这种东西，一个月改一次算频繁的，每次请求也只在会话开始时读一次。加缓存层的收益约等于零。而真正的性能瓶颈在写入路径——批量更新用户偏好时数据库压力大。AI 生成的代码完美地优化了一个不需要优化的地方，同时完美地忽略了真正的问题。

代码没有一行是错的。但整个方向错了。

AI 在代码层的审查能力已经很强——格式、安全漏洞、空值检查这类机械性问题，覆盖能力远超人类。但一旦涉及业务逻辑和架构合理性，AI 的表现断崖式下跌。“这段代码该不该存在"这种问题，AI 连问都不会问。

所以真正的问题不在 AI 会不会取代 Code Review。而是你的 Review 时间花在了哪一层。

一、AI 已经赢了——在代码层

Google 2025 年在 ICSE 发表的内部代码审查研究（Vijayvergiya et al., 2025）显示，AI 生成的审查评论被开发者接受的比例（42%）和人类评论（38%）已经非常接近。4 个百分点的差距算不上碾压——而且 AI 处理的主要是格式和常见缺陷类评论，难度本身就比人类处理的设计类评论低。但配合另一个数字看就清楚了：引入 AI 预审查后，人类审查者平均每次审查时间减少了 12%。机械性检查上，AI 已经在帮人省时间了。

多项学术研究也给出了一致的方向。其中一项覆盖了 1200 个 PR 和 40 个开源项目的研究数据比较有代表性：

维度	AI 独立审查	人类独立审查	AI + 人类
缺陷捕捉率	62%	71%	89%
审查周期	4 分钟	26 小时	8 小时

单看 AI 独立审查的 62%，确实不如人类的 71%。AI 独立跑并不能替代人。但关键数字是最后一列：AI + 人类协作的 89%——比任何一方单独都高。这说明 AI 补上了人类审查的盲区，而不只是重复人类已经能做的事。更重要的是审查周期——从 26 小时压缩到 8 小时，AI 在代码层帮人类省下了大量机械性检查时间。

你大概也有体会：连续审查三四个 PR 之后，最后一个你基本是在"扫"而不是在"读”。审查质量随时间衰减，这是认知负荷的客观限制。AI 不会有这个问题——它审第一个 PR 和第一百个 PR 的质量一样。

有意思的是，截至 2025 年，Google 自己依然要求每行代码经过人类审查。但他们内部的数据显示，人类审查者的关注点已经在转移。AI 接手了格式、命名、常见缺陷这些机械性检查之后，人类留下的评论越来越集中在设计合理性和方案选择上。这不是 Google 刻意推动的变革，是 AI 能力到了那个水平之后自然发生的。

二、AI 看不见的大半

回到那个缓存层。

你的团队在做一个用户偏好服务。有人用 AI 生成了一段缓存逻辑——TTL 控制过期，读取时先查缓存再查数据库。代码写得很标准，是你在任何教程里都能看到的写法。

AI 审查工具扫了一遍，报告很漂亮：无空指针风险，并发安全，过期逻辑正确，数据库查询有错误处理，命名符合规范。如果你团队用了自动化审查流水线，这个 PR 大概率直接进入"待合并"队列。All Clear。

但一个有系统上下文的人会追问三个问题。

用户偏好多久变一次？几乎不变，一个月改一次算频繁的。一次请求读几次偏好？一次，会话开始时加载，整个会话复用。性能瓶颈在哪？在写入路径——批量更新偏好时的数据库压力，不在读取路径。

三个问题问完，结论就出来了：这个缓存层不该存在。读取频率低、数据几乎不变、瓶颈不在读——三个条件都不支持加缓存。AI 却往读取路径加了一层完全不需要的抽象，而真正该优化的写入路径没人碰。

这是 AI 审查的边界。

AI 擅长发现机械性缺陷——一个未关闭的资源、一个缺少的空值检查、一个有竞态风险的并发写入。这些问题有明确的模式，AI 可以通过模式匹配高效检出。但"这段逻辑在业务上说不说得通"，它几乎无能为力。

架构合理性更弱。AI 能检出一些有明确模式的架构问题（比如 N+1 查询、循环依赖），但它判断不了"在我们当前的阶段，引入消息队列是不是过度设计"。这个判断需要知道业务量的数量级、团队有没有运维消息队列的经验、产品未来半年的扩展计划——这些信息全在代码之外。

至于"这个 PR 解决的是不是对的问题"——AI 完全没有这个判断能力。它能判断代码"写得对不对"，但判断不了"该不该写"。

根源在上下文。AI 看到的是 diff，人看到的是 diff 背后的系统、团队、业务目标。虽然 AI 审查工具已经在尝试接入架构文档和 ADR，但效果还远不够。真正决定一个 PR 方向对不对的，往往是那些只存在于人脑中的隐性知识——为什么上次选了这个方案、某个模块为什么不能碰、产品下个季度要往哪走。这些知识有的可以文档化（比如 ADR），有的变化太快写下来的成本比口头同步高得多。

而恰恰是这些知识，决定了一个 PR 的方向对不对。

三、三层升维——你的 Review 在看哪一层？

代码审查保护的东西在变。我把它分成三层。

代码层——对不对。 语法、安全漏洞、空值、并发、性能反模式。前面说过了，这是 AI 的主场，不再展开。

架构层——合不合理。 关注的是技术方案内部的合理性：设计模式选择、模块耦合度、职责划分、是否引入了不必要的复杂度。AI 能发现一些有明确模式的问题，但对"这个设计选择在我们的上下文中合不合理"几乎无能为力。

为什么架构层这么难？因为"合理"没有绝对标准。同样是引入一个中间层，在一个 3 人团队的早期项目里是过度工程，在一个 20 人团队的成熟服务里是合理解耦。AI 看不到团队规模，看不到项目阶段，看不到上下游依赖关系。它能告诉你这个抽象层的接口设计有没有问题，但告诉不了你这个抽象层该不该存在。

意图层是最容易被忽视的一层——该不该做。 关注的不再是技术方案本身，而是整个 PR 的存在价值：这个 PR 解决的是不是对的问题？值不值得这个复杂度？有没有更简单的替代方案？

AI 审查代码是否存在，人审查代码是否应该存在——这两个问题之间隔着一整个认知维度。

用一个简化的场景来感受差异。

有人提了一个 PR：重构订单服务，引入事件驱动架构。代码层审查（无论人还是 AI）发现了几个空值遗漏和竞态条件，结论是修复后可合并。

但如果你往上看一层。当前业务量不大，团队也没有消息队列的运维经验。事件驱动在这个阶段属于过度设计——你在为一个还没到来的规模问题预支复杂度。更重要的是，引入消息队列意味着团队要学习一整套新的运维技能：消息积压怎么处理、消费者挂了怎么办、消息顺序如何保证。这些隐性成本，代码层审查一个也看不到。

再往上看一层。这个重构要解决什么？“提升订单处理速度”。瓶颈真的在架构吗？查了一下——瓶颈在一个内部服务的同步调用链路上。把那个同步调用改成异步回调，处理时间从秒级降到毫秒级。

结论翻转了：不应该合并。方向错了。真正的修复是调整调用方式，不是重构整个架构。几百行的重构白写了，几个月的运维债也不用背了。

当然，意图层审查不保证每次都对——你可能判断错瓶颈所在。但它确保你至少问了对的问题：“这件事该不该做？“不问这个问题的 Review，默认方向是对的——而方向错误恰恰是代价最大的那类错误。

有人可能会说，好的工程师一直在做架构和意图层的审查，这不是什么新鲜事。没错。区别在于：以前人类审查者要同时兼顾三层，认知带宽被代码层大量消耗。当 AI 接管了代码层，人类第一次有了把全部注意力放在架构层和意图层的条件。三层升维不是发明了新东西，是 AI 让人类第一次有机会把该做的事做到位。

四、怎么升维

说了三层模型，落到实操上怎么做？

代码层交给 AI。配置好审查工具的规则——安全策略、代码风格、性能反模式。定期抽查它的输出，校准而非逐行复查。先让 AI 跑一遍生成报告，人只看它标记为"需要人类确认"的项目。

这一步最大的心理障碍是"万一 AI 漏了怎么办”。AI 会漏，人也会漏。前面的数据说得很清楚：AI 独立 62%，人类独立 71%，但 AI+人协作 89%。协作模式下两边互补盲区，比任何一方单独都强。你不需要 100% 信任 AI，你只需要把它当成一个不会疲劳的第一轮筛查员。

架构层的关键是问对问题。举个例子：有人在 PR 里把一个内部调用改成了 gRPC 微服务。架构层审查不是看 proto 文件定义对不对——那是代码层的事。架构层要问的是：这两个模块之间的交互频率是多少？拆成独立服务后部署复杂度增加了多少？团队有没有运维微服务的经验和基础设施？如果答案是"交互频率高、团队没有服务网格、当前单体完全扛得住”，那拆分就是过度设计。

架构审查不需要你是架构大师，但需要你有系统上下文——知道这个模块和其他模块怎么交互，知道团队的技术栈边界在哪，知道当前阶段的约束条件是什么。很多团队的架构问题不是某个人设计得差，而是没人在 Review 时问"我们真的需要这个复杂度吗"。

意图层只需要三个问题：这个 PR 解决的是不是对的问题？有没有更简单的方案？投入和产出匹配吗？

听起来简单，难的是跳出代码的视角。怎么训练这种意识？一个实操习惯：每次打开 PR 页面，强迫自己先读标题和描述，而不是直接滚到 diff。标题和描述是 PR 的"意图声明"——如果标题都说不清楚这个 PR 要解决什么问题，代码写得再好也该打回去。

三层不是每个 PR 都要走一遍。小改动（修 typo、更新依赖版本）代码层 AI 扫完就够了。但凡涉及业务逻辑变更、架构调整、新模块引入的 PR，架构层和意图层就不能省。判断标准：这个 PR 如果方向错了，返工成本有多大？返工成本越高，越值得在意图层多花时间。

升维不只是个人意识转变，它需要团队文化支持——允许你在 Review 时说"这件事该不该做"而不会被认为越权。在很多团队里，质疑 PR 的存在意义比质疑代码的实现方式困难得多。一个可行的起步方式：在 PR 模板里加一个必填字段——“这个 PR 要解决什么问题？有没有考虑过更简单的方案？“把意图层审查从依赖个人意识变成流程保障。

意识是第一步，文化是土壤。

PR 没有死，但你的 Review 可能该升级了。

下次审查 PR 的时候，先滚动到最上面，看一眼标题和描述。问自己：这件事该不该做？

这个问题，AI 回答不了。

别再只用 go/ast 了：Go 代码分析工具链三层实战

Mon, 20 Apr 2026 00:32:15 +0800

你大概率用过 go/ast。解析一下源码、遍历一下节点、提取点结构信息——30 行代码就能跑起来一个小工具。

挺好。

直到有一天，你想做一件"很简单"的事：检查代码里有没有忽略 error 返回值。你用 go/ast 写了一版，能抓到 _ = err 的情况。但 os.Remove("file.txt") 呢？返回值被直接丢弃，AST 层面只看到一个函数调用——你不知道它返回了什么，更不知道里面有没有 error。

问题出在哪？go/ast 只看"形状"。它知道这里有个函数调用，但不知道这个函数返回几个值、哪个是 error。这些信息在另一层——go/types。

这篇文章就从这个问题出发。我会用同一个需求——检测被忽略的 error——分别用 go/ast、go/types、go/analysis 三层工具实现，让你直观感受每层能做什么、做不了什么。

1. go/ast 能做什么：从源码到语法树

先从一个最简单的例子开始。

假设你们团队有个规矩：单个函数不能超过 50 行。你想写个工具自动检查。用 go/ast，核心逻辑不到 20 行：

fset := token.NewFileSet()
f, err := parser.ParseFile(fset, path, nil, parser.ParseComments)
if err != nil {
    log.Fatal(err)
}

ast.Inspect(f, func(n ast.Node) bool {
    fn, ok := n.(*ast.FuncDecl)
    if !ok {
        return true
    }
    start := fset.Position(fn.Body.Lbrace)
    end := fset.Position(fn.Body.Rbrace)
    lines := end.Line - start.Line
    if lines > 50 {
        fmt.Printf("⚠ %s:%d  函数 %s 有 %d 行（上限 50）\n",
            start.Filename, start.Line, fn.Name.Name, lines)
    }
    return true
})

我拿它跑了一个测试文件 [实测 Go 1.26.2]，里面有三个函数：shortFunc（3 行）、mediumFunc（15 行）、longFunc（54 行）。输出：

`1`	`⚠ testdata.go:14 函数 longFunc 有 54 行（上限 50）`

干净利落。这就是 go/ast 的舒适区：纯语法层面的检查。它能告诉你代码"长什么样"——有几个函数、函数有多长、参数叫什么名字、哪里有注释。

这类需求用 go/ast 就够了：

函数/方法行数检查、命名规范检查
注释覆盖率统计（统计导出函数前是否有注释）
代码结构提取和简单的代码生成

核心 API 就三步：token.NewFileSet() 创建位置信息容器，parser.ParseFile() 把源码解析成 AST，ast.Inspect() 递归遍历节点。

2. go/ast 做不了什么：三个撞墙时刻

go/ast 的能力边界在哪？三个场景，每个都是"写到一半才发现做不了"。

场景一：检测被忽略的 error

你想检查代码里有没有丢弃 error 返回值。用 go/ast 能做到一部分——扫描赋值语句，找到左侧有 _ 的情况：

ast.Inspect(f, func(n ast.Node) bool {
    assign, ok := n.(*ast.AssignStmt)
    if !ok {
        return true
    }
    for _, lhs := range assign.Lhs {
        ident, ok := lhs.(*ast.Ident)
        if ok && ident.Name == "_" {
            fmt.Printf("发现 _ 赋值，可能忽略了 error\n")
        }
    }
    return true
})

问题来了：os.Remove("file.txt") 返回一个 error，但调用者直接丢掉了返回值，连赋值都没有。AST 层面只看到一个 *ast.ExprStmt 包着一个 *ast.CallExpr——你不知道这个函数返回了什么。

更麻烦的是 fmt.Println("hello")。它也返回 (int, error)，但在多数场景下忽略它是合理的。纯 AST 没法区分"应该检查的 error"和"可以安全忽略的 error"——因为它根本不知道返回值类型。

场景二：判断类型是否实现了某个接口

你想写个工具，找出所有 http.Handler 的实现。AST 能找到名叫 ServeHTTP 的方法声明，但它无法验证参数签名是否匹配：

// AST 能看到这个方法声明
func (s *MyServer) ServeHTTP(w http.ResponseWriter, r *http.Request) { ... }

// 但如果签名写错了呢？AST 同样会找到它：
func (s *MyServer) ServeHTTP(w io.Writer, r *http.Request) { ... }
// ↑ 第一个参数类型不对，没实现 http.Handler，AST 分不清

AST 只看到"有个方法叫 ServeHTTP"，不知道 http.ResponseWriter 和 io.Writer 是不同类型。判断接口实现必须有类型信息。

场景三：跨包的同名函数

你的代码里有一行 Parse(input)。AST 告诉你"这里调用了 Parse"，但：

import "encoding/json"
import "github.com/you/myparser"

// 这两个 Parse 签名完全不同，行为完全不同
json.Unmarshal(data, &v)    // 标准库
myparser.Parse(input)       // 你自己的包

如果你只看 AST，两个调用长得一样——都是 SelectorExpr。但它们是完全不同的函数。纯语法分析分不清谁是谁。

三个场景的共同点：go/ast 只做语法分析，不做语义分析。它知道代码"长什么样"，但不知道代码"什么意思"。

3. go/types 补位：从"形状"到"含义"

go/types 解决的核心问题是：给 AST 节点赋予类型信息。

还是用"检测被忽略的 error"这个需求。同一个测试文件，包含四种场景：

func goodExample() {
    f, err := os.Open("file.txt")   // 正确处理了 error
    if err != nil { return }
    defer f.Close()
}

func badExample1() {
    _, _ = fmt.Println("hello")     // 用 _ 显式丢弃
}

func badExample2() {
    os.Remove("temp.txt")           // 完全丢弃返回值
}

func noErrorReturn() {
    fmt.Println("no error here")    // 返回值包含 error 但通常可忽略
}

我分别用纯 go/ast 和 go/ast + go/types 两个版本跑了一遍 [实测 Go 1.26.2]：

纯 go/ast 版输出（7 条警告）：

[AST] target.go:20  发现 _ 赋值，可能忽略了 error     ← _ = fmt.Println 的两个返回值
[AST] target.go:20  发现 _ 赋值，可能忽略了 error     ← 同上，两个 _ 各报一次
[AST] target.go:30  发现 _ 赋值，可能忽略了 error     ← f, _ := os.Open 的 _
[AST] target.go:31  发现 _ 赋值，可能忽略了 error     ← _ = f 的 _
[AST] target.go:12  函数调用返回值被丢弃（不知道是否含 error）  ← fmt.Println 在 goodExample 里
[AST] target.go:25  函数调用返回值被丢弃（不知道是否含 error）  ← os.Remove
[AST] target.go:36  函数调用返回值被丢弃（不知道是否含 error）  ← fmt.Println 在 noErrorReturn 里

7 条。前 4 条是 _ 赋值的文本匹配——_ = f 并不是忽略 error，但 AST 只看到 _ 就报了。后 3 条是丢弃返回值的调用，AST 不知道它们是否返回了 error，只能模糊提示。

go/ast + go/types 版输出（3 条警告）：

1
2
3

[Types] target.go:12  函数 fmt.Println 返回 error 但被丢弃
[Types] target.go:25  函数 os.Remove 返回 error 但被丢弃
[Types] target.go:36  函数 fmt.Println 返回 error 但被丢弃

3 条，每条都精确到函数名。它能区分"返回了 error 的调用"——至于 fmt.Println 这种通常可安全忽略的，是否报警属于策略问题，不是工具层面的能力缺陷。

关键差异在哪？go/types 版本能拿到函数签名：

// 完整链路：AST 标识符 → 类型对象 → 函数签名
// 1. 从 AST 拿到函数标识符（*ast.SelectorExpr 的方法名）
// 2. 通过 TypesInfo.ObjectOf() 拿到类型对象（types.Object）
// 3. 再取函数签名（*types.Signature）
obj := pkg.TypesInfo.ObjectOf(sel)  // sel 是 *ast.Ident
sig, ok := obj.Type().(*types.Signature)
results := sig.Results()
for i := 0; i < results.Len(); i++ {
    if types.Identical(results.At(i).Type(), errorType) {
        // 确认：这个函数返回了 error，且被丢弃了
    }
}

go/ast 看到 os.Remove("temp.txt") 只知道"这是一个函数调用"。go/types 知道 os.Remove 的签名是 func(name string) error——返回一个 error，而这个 error 没有被接收。

代价是什么？

维度	纯 go/ast	go/ast + go/types
警告数	7 条（含噪音）	3 条（精确到函数名）
代码行数	~45 行	~85 行
示例加载方式	标准库直接解析	`golang.org/x/tools/go/packages` 加载
分析范围	单文件	整个包（含依赖）

说明：go/types 本身在标准库里，但要方便地加载整个包的类型信息，通常用 golang.org/x/tools/go/packages。这不是 go/types 的硬依赖，是实际使用中的常见搭配。

代码量翻了一倍，但换来的是从"文本匹配"到"类型系统级"的精确度提升。

4. go/analysis：标准化你的分析器

到目前为止，不管用 go/ast 还是 go/types，你写的都是"散装"工具——自己解析文件、自己遍历节点、自己输出结果。这样做有两个问题：

没法复用。你写的 error 检查器和我写的函数行数检查器，各自 main() 一套，没法组合到一起跑。
没法集成。golangci-lint 支持几十个分析器并行运行，但你的"散装"工具接不上去。

golang.org/x/tools/go/analysis（注意：不在标准库，在 x/tools 扩展库里）解决的就是这个问题。它不替代 go/ast 或 go/types——它在它们之上提供了一套标准化的分析器接口。

一个 go/analysis 分析器长这样：

var Analyzer = &analysis.Analyzer{
    Name: "funclen",
    Doc:  "检查函数行数是否超过上限",
    Run:  run,
}

func run(pass *analysis.Pass) (any, error) {
    for _, file := range pass.Files {
        ast.Inspect(file, func(n ast.Node) bool {
            fn, ok := n.(*ast.FuncDecl)
            if !ok {
                return true
            }
            start := pass.Fset.Position(fn.Body.Lbrace)
            end := pass.Fset.Position(fn.Body.Rbrace)
            if end.Line-start.Line > 50 {
                pass.Reportf(fn.Pos(), "函数 %s 有 %d 行",
                    fn.Name.Name, end.Line-start.Line)
            }
            return true
        })
    }
    return nil, nil
}

核心逻辑和之前的"散装"版几乎一样。但区别在于：

pass.Files 帮你处理了文件加载
pass.Fset 帮你管理了位置信息
pass.Reportf 是标准化的报告接口
pass.TypesInfo 给你当前包的类型信息（不需要自己加载包）

先用 singlechecker 跑通单个分析器，再用 multichecker 组合多个：

// 单独跑
func main() { singlechecker.Main(Analyzer) }

// 组合多个分析器一起跑
func main() {
    multichecker.Main(
        funclen.Analyzer,
        errcheck.Analyzer,
        nilcheck.Analyzer,
    )
}

这就是 go/analysis 的价值：不是让你写出更好的分析逻辑，而是让你的分析逻辑能被整个生态复用。

你可能会想：我直接用 golangci-lint 不就行了？大多数场景确实够了。但 golangci-lint 内置的规则未必覆盖你们团队的特定规范——比如"禁止在 handler 层直接调用 repository"。这些定制需求，就得自己写 Analyzer。

有个坑值得提前知道：pass.Files 默认不包含 _test.go 文件。如果你的规则需要检查测试代码，需要额外处理。

5. 决策地图：你的需求该用哪一层

回头看，Go 的代码分析工具链是三层结构：

层	包	适用场景	适用边界
语法层	`go/ast` + `go/parser`	命名检查、行数检查、结构提取、代码生成	不知道类型，不做跨包语义分析
语义层	`go/types`	类型推断、接口匹配、error 检测、跨包分析	不做控制流/数据流分析，不处理反射
框架层	`golang.org/x/tools/go/analysis`（非标准库）	标准化分析器，可组合，可集成 golangci-lint	学习成本略高于直接用 go/ast

选型就一个问题：你的需求需要知道"类型"吗？

不需要类型 → go/ast 就够了
需要类型 → go/types
需要类型 + 想集成到 golangci-lint → go/analysis

一个更直接的判断：如果你发现自己在用字符串匹配来"猜"类型信息，说明你该升级到 go/types 了。

再往上还有 go/ssa（静态单赋值分析）、go/callgraph（调用图分析）等更高级的工具，本文不展开。

go/ast 是入口，但不是终点。下次写代码分析工具的时候，问自己一个问题：我需要知道类型吗？

完整实验代码已开源在 GitHub（zhiyulab-evidence/go-ast-tooling），所有数据均基于 Go 1.26.2 实测。

附录：实验代码和原始数据

本文 3 组实验的代码已开源：

GitHub：zhiyulab-evidence/go-ast-tooling

func-length-linter/ — 函数行数检查 linter（第1章）
error-check-ast/ — 纯 go/ast 版 error 检查（第2-3章）
error-check-types/ — go/ast+go/types 版 error 检查（第3章）
analysis-framework/ — go/analysis 框架版分析器（第4章）

每个子目录可独立编译运行。二进制产物不入库，跑实验前自己 go build。

Go 的测试框架不想让你 TDD

Wed, 15 Apr 2026 19:03:45 +0800

你有没有觉得，Go 的测试写起来哪里不太对？

别急，我不是要教你写测试——这类文章已经够多了。我想和你一起挖一挖：Go 的 testing 包为什么长这样？为什么没有 assert？为什么 Test 和 Benchmark 混在一个包里？为什么连 Go 的创造者自己，在专门讲测试的演讲里，一条 TDD 都没提？

这些"为什么"背后，藏着一条刻意拒绝 TDD 教条的设计路线。

一、你有没有觉得 Go 的测试哪里不对劲？

想象一下这个场景：你是一个有 Java/Python 背景的开发者，刚开始写 Go。你打开一个 _test.go 文件，期待看到熟悉的 assert.Equal()，结果看到的是：

1
2
3

if got != want {
    t.Errorf("Add(1, 2) = %d, want %d", got, want)
}

你的第一反应可能是：“这也太原始了吧？”

然后你去搜索"Go 测试最佳实践"，发现几乎所有教程都在教你 table-driven tests 和 if + Errorf——没有人告诉你为什么没有 assert。

再然后，你注意到 Benchmark 和 Test 长在同一个包里，用同一套框架，但它们显然在做不同的事。所有教程把它们并列讲解：“这是单元测试，这是性能基准。“但没有教程告诉你，它们为什么被放在同一个框架里。

我跑了一组数据来回答这个问题。

我统计了 Go 标准库源码中所有 *_test.go 文件的测试函数分布。结果是：

类型	数量	占比
func TestXxx	9198	82.3%
func BenchmarkXxx	1915	17.1%
func FuzzXxx	56	0.5%

9198 个 Test，1915 个 Benchmark——Test 是 Benchmark 的 4.8 倍。但更关键的是：

标准库中 0 处 testify（Go 社区最流行的第三方断言库）使用
0 处第三方 assert 风格调用
if 条件判断模式 24971 处

Go 官方自己都不用 assert。官方不用第三方库是常规操作——但框架自身也没有提供任何 assert 函数，这就是设计选择而非依赖策略了。这不是"忘了加”，是故意不加。

56 个 Fuzz 函数是 Go 1.18 引入的模糊测试，代表了 Go 测试体系的第三个维度——但那是另一个故事了。

二、没有 assert 的信号

“没有 assert"这件事，大多数人把它当缺陷。但换个角度看：这是信号。

我对比了 Go testing 包和 JUnit 5 Jupiter API 的公共面积：

维度	Go testing	JUnit 5 Jupiter
核心 API 数量	~60	150+（含关联包）
断言机制	if + Errorf（手写）	Assertions 类（200+ 方法）
生命周期回调	无注解	@BeforeAll/@BeforeEach 等
参数化测试	t.Run + table	@ParameterizedTest 系列
扩展机制	t.Helper() 自建	Extension API 完整体系

Go 的 60 个 API 覆盖了测试、基准、模糊测试三个领域。JUnit 5 仅测试领域就用了 150+ API。

这是"刻意不做”。

那多写的代码到底有多少？用 5 个常见断言场景做了对比——纯 testing 包 51 行，testify 32 行，差 37%。摩擦真实存在，但不是翻倍级别的差距。

更有意思的是这个数字：Go 标准库中 t.Helper() 被调用了 2559 次。t.Helper() 是什么？它是一个标记函数——在你自己写的断言辅助函数里调用它，Go 的测试框架就能在报错时显示调用者的行号，而不是辅助函数内部的行号。

Go 需要断言，但让你自己建，框架只帮你把行号搞对。断言是你自己的事，框架不替你做。

三、Benchmark 和 Test 不是一家人

大多数教程把 Test 和 Benchmark 并列教，好像它们只是 testing 包的两个功能。但仔细看 API 就会发现，它们做的事情完全不同：

testing.T 的独有方法：Chdir、Deadline、Parallel、Setenv ——全是关于"验证正确性"的。

testing.B 的独有方法：Loop、ReportAllocs、ReportMetric、ResetTimer、RunParallel、SetBytes、StartTimer、StopTimer… ——全是关于"度量性能"的。

它们通过 testing.TB 接口——一个定义了 Log/Error/Fatal/Cleanup/TempDir 等基础行为的接口——共享了公共能力，但核心能力完全正交。T 验证"对不对”，B 度量"快不快"。

这是设计哲学。

Go 把正确性验证和性能度量放在同一个框架里，不是图省事。从结果看，两者在同一个框架里这件事本身就说明性能在 Go 的测试体系里不是二等公民——17.1% 的 Benchmark 比例不是装饰。相比之下，JUnit 生态中 Benchmark 测试的占比远低于 Go 标准库的 17.1%——大多数 Java 项目的基准测试是事后补的，不是和功能测试一起写的。

对比一下：在 JUnit 生态里，性能测试是 JMH 的活，和 JUnit 是两个世界。在 pytest 里，benchmark 是 pytest-benchmark 插件，和 pytest 本体也是分开的。Go 是少数把 Test 和 Benchmark 原生整合在同一个框架里的主流语言。

这个设计不是偶然。可测量才能优化——如果 Benchmark 和 Test 是两个框架，开发者会倾向于"先写功能测试，有空再补性能测试"。但 Go 把它们放在同一个入口——go test 跑 Test，go test -bench 跑 Benchmark——框架统一，命令一体，性能测试的门槛被降到了最低。

四、并发：TDD 的最大盲区

Go 最引以为傲的特性——goroutine 和 channel——恰好是 TDD 最覆盖不了的领域。

为什么？因为并发代码的测试面临一个根本困境：“还没发生"和"永远不会发生"之间没有可靠的区分。你想测试"这个 goroutine 不会往 channel 里写数据”，但你怎么判断？等 1 秒？等 10 秒？等 1 分钟？

Go 官方博客说得很直白：

“We can make the test less flaky at the expense of making it slower, and we can make it less slow at the expense of making it flakier, but we can’t make it both fast and reliable.”

翻译：快和可靠，你只能选一个。

更关键的是时间线：Go 1.24（2025 年 2 月发布）才实验性引入了 testing/synctest 包。这意味着 Go 从 2009 年开源到 2025 年 synctest 引入，16 年间没有官方的确定性并发测试方案。

16 年。

日常开发中，go test -race 是发现数据竞争的第一道防线——但它只能发现已触发的竞争，不能证明竞争不存在。

这不是疏忽——并发测试是一个硬问题。synctest 是 Go 对这个硬问题的第一个官方回答。它的思路很 Go：给你一个确定性的调度环境，让你在测试里精确控制 goroutine 的执行顺序，不再靠 time.Sleep 碰运气。

这恰恰说明了 Go 测试哲学的本质：不是拒绝测试，而是在找到正确方案之前，宁可不提供。

五、Russ Cox 的选择

上面的分析都是我的解读——Go 团队自己怎么说？

Russ Cox，Go 项目的技术负责人，在 2023 年的 GopherCon AU 上做了一个演讲叫"Go Testing By Example"。这个演讲给出了 20 条测试建议。

我逐条读完了。20 条建议里，没有一条提到"TDD"、“Red-Green-Refactor"或"测试先行”。在一个专门讲测试的演讲中，TDD 是业界最知名的测试方法论——完全不提意味着主动选择不推荐。这是回避，不是缺席。

他推荐的是什么？参考实现对比法——写一个简单但显然正确的参考实现，然后穷举小规模输入，比较生产代码和参考实现的输出。这意味着你不需要预测每个用例的期望值——你只需要一个"笨但对"的版本做对照。

这和经典 TDD 的断言模式完全不同。TDD 要求你为每个用例预测期望输出（assert），Russ Cox 建议你写一个参考实现然后比较等价性。TDD 是"我知道答案"，Russ Cox 是"我有一个简单版本可以对照"。

他还说了一句很关键的话：

“Coverage is no substitute for thought.”

覆盖率不能替代思考。这句话直接指向了 TDD 的一个副作用：当你机械地追求红绿循环，你关注的是"测试有没有通过"，而不是"我在测什么"。

另一位 Go 社区的重要声音 Peter Bourgon（InfluxDB 联合创始人）更直接——他认为好的可观测性比好的测试更重要，100% 测试覆盖率"几乎肯定是适得其反的"。

你不需要同意他们。但 20 条建议 0 条 TDD——这不是演讲者忘了提，是在他看来，测试有比 TDD 更实用的做法。

六、你的项目需要什么层次的验证

说了这么多，我不是要说服你"Go 不该 TDD"。我想给你一个判断框架。

回到核心论点：Go 的测试哲学是"测试必存，但不必先行"。测试的质量和存在比编写顺序更重要。

那你的项目该走哪条路？

如果你在探索阶段——不确定 API 长什么样，先写测试就是在给不存在的接口写规约。TDD 的红绿循环确实能帮你理清思路，但摩擦也真实存在（多写 37% 代码）。

设计清晰的团队则相反——已经知道接口长什么样，先写测试就是给自己加摩擦。Go 惯用路线（先实现再验证）效率更高，尤其是当你需要 RWMutex、需要考虑并发安全时——这些在 TDD 的小步迭代中很难自然生长出来。

性能敏感的项目多了一步：先跑 Benchmark 再决定实现方案——性能测试先行，功能测试后补。

并发代码是另一个故事——TDD 帮不了你太多。Go 1.24 的 synctest 提供了确定性并发测试的起点，但在它成熟之前，可观测性（日志、metrics、trace）可能比测试更能帮你发现并发 bug。

现实项目往往同时踩中几个维度——这时候优先级就看哪个维度最可能出错。

Go 标准库的选择是：0 testify，2559 个 t.Helper()，9198 个 Test，1915 个 Benchmark。这是自建断言体系、性能非二等公民、测试必存但不必先行的实践证明。

Go 选了一条路，这条路的核心逻辑是：给你最小的工具集，让你自己决定怎么用。23k+ stars 的 testify 说明社区自己填上了 assert 的空缺——而 Go 官方没有反对，也没有收编。

Go 的 testing 包不是 TDD 框架做得不好，而是一套不想让你 TDD 的设计。 理解这个意图，你才能为自己的项目做出正确的选择。

Go 错误分层实战：从裸奔到三层防线

Sat, 11 Apr 2026 10:00:00 +0800

Go 社区吵了十年的错误处理问题，吵偏了方向。

每隔几个月就有人提新提案，想给 if err != nil 加语法糖。try-catch、check-handler、? 操作符……提案来来去去，Go 团队的态度始终一致：不加。2025 年 6 月，Go 官方博客发了一篇文章，标题很直白——“On No Syntactic Support for Error Handling”，正式关闭了语法变更的大门。

理由很清晰：冗长但可行。写代码、读代码、调试代码是三种不同的活动，Go 当前的显式错误返回在"读"和"调"上表现优秀，代价是"写"的时候多敲几个字。

我怎么看？官方说得对，但只对了一半。冗长不是问题，真正的问题是，绝大多数 Go 项目根本没有错误分层。底层 infra 错误裸奔到 HTTP 响应，业务错误和系统错误混为一谈，panic 被当成快捷 throw。语法糖加不加，跟这些问题毫无关系。

你写了一万遍 if err != nil，但你有没有想过：这个错误该往哪层抛？该对谁暴露？该返回什么 HTTP 状态码？

如果没有想过，那冗长就是最小的毛病。

这篇文章从问题诊断开始，先拆解社区十年争论为什么吵偏了，再用一个真实的信息泄露实验展示无分层的代价。然后给出三层错误分层方案——Infra、Service、Handler 各司其职。接着聊 panic 的边界：什么时候该用，什么时候是滥用。最后用 Go 1.13 以来的标准库新武器串联全局，给出一条不用重写的渐进式改造路径。

1 吵偏了十年

把过去十年 Go 社区关于错误处理的讨论做个分类，大致分三派：

语法派：if err != nil 太冗长，需要语法糖
语义派：错误需要更好的包装和检查能力（errors.Is/errors.As）
架构派：错误需要分层，不同层的错误有不同的处理策略

三派中，语法派声量最大，提案最多，成果为零。语义派的成绩单是 Go 1.13 的错误包装机制和 1.20 的 errors.Join，实打实的语言改进。架构派的讨论散落在各个项目的实践中，没有形成社区级的共识和统一方案。

但架构派才是真正解决问题的方向。

为什么语法派注定失败？因为他们的前提就错了。假设语法是瓶颈，那加语法糖就能解决问题。但实际情况是：即便给你一个 ? 操作符，自动把 error 往上冒泡，你依然面临同样的问题。这个 error 冒泡到哪一层？冒泡上去之后，该返回 400 还是 500？该暴露什么信息给调用方？

语法糖只是让你少打几个字，它解决不了错误该往哪放的问题。就像一栋楼没有消防通道，你把楼梯加宽了也没用。问题不在楼梯宽度，在于根本没规划逃生路线。

Go 官方关闭语法提案这件事本身就说明了一个事实：Go 团队认为当前语法框架足以支撑正确的错误处理实践。他们没有说"现有方式完美"，他们说的是"语法层面不需要改动，工程实践层面需要改进"。

一个类比：网络分层。TCP 不会把物理层的信号错误暴露给应用层。物理层错误在物理层处理，链路层错误在链路层处理，每一层只向上暴露对上一层有意义的抽象。如果网卡丢包了，你的 HTTP 客户端看到的是"连接超时"，不是"eth0: RX descriptor error, status=0x8"。

Go 项目的错误处理应该遵循同样的原则。但现实是，大部分项目根本没有这样做。包装不等于分层。%w 只是把错误链连起来了，但你依然把底层的 pq: 前缀和 SQL 语句一路透传到了 HTTP 响应。包装是手段，分层是策略。有手段没策略，跟没有手段没区别。

那没有分层的代码，实际跑起来会怎样？

2 无分层的灾难

先看一段常见的 Go 代码。很多人写过，很多人还在写：

func GetUser(w http.ResponseWriter, r *http.Request) {
    user, err := db.Query("SELECT * FROM users WHERE id = $1", r.URL.Query().Get("id"))
    if err != nil {
        http.Error(w, err.Error(), http.StatusInternalServerError)
        return
    }
    json.NewEncoder(w).Encode(user)
}

看起来没问题？当数据库正常时确实没问题。但当连接池耗尽、查询超时、表不存在的时候，err.Error() 会返回什么？

我跑了一个实验。用 lib/pq 驱动连接 PostgreSQL，模拟连接池耗尽的场景，直接把 db.Query 返回的错误写到 HTTP 响应里：

1
2
3

HTTP/1.1 500 Internal Server Error

pq: sorry, too many clients already

这只是一种场景。将不同错误类型的 err.Error() 汇总起来，你的代码可以泄露以下信息：

连接池耗尽：pq: 前缀暴露数据库驱动类型
查询失败：SQLSTATE 暴露错误分类
权限不足：database 字段暴露数据库名
SQL 语法错误：query 暴露完整 SQL 语句
表不存在：table 暴露表名

五种场景，五类泄露。每一种单独看"只是一条错误信息"，但攻击者可以通过触发不同错误来拼出你的后端架构。

有人说：“我用 fmt.Errorf 包一层不就好了？”

if err != nil {
    http.Error(w, fmt.Errorf("query failed: %w", err).Error(), http.StatusInternalServerError)
    return
}

试试看。响应变成：

`1`	`query failed: pq: sorry, too many clients already`

pq: 前缀还在。%w 只是加了一层壳，底层信息照样透传。你在 HTTP 响应里加了一个"query failed"的前缀，但攻击者关心的是后面的 pq: 前缀，它直接告诉你后端是 PostgreSQL。

这不是假设场景。近年来，多个知名开源项目因错误信息泄露被发现安全漏洞。Kubernetes 就曾因日志中暴露 service account token 被报告安全问题，修复方案正是加了一层错误包装，对非管理员用户隐藏内部细节。

这说明了一个结构性问题：Kubernetes 这种级别的项目都会犯这种错，说明这不是粗心问题。没有错误分层的项目，错误泄露不是"会不会"的问题，是"什么时候"的问题。

再推演一条完整的攻击链路。你的服务对外暴露了一个 /api/users/:id 接口。数据库连接池耗尽 → db.Query 返回超时错误 → handler 里 fmt.Errorf("query failed: %w", err) 把 pq: 前缀一路透传 → HTTP 500 响应体里出现了 PostgreSQL 特征 → 攻击者确认后端是 PostgreSQL → 根据 SQLSTATE 和表名推测 schema → 下一步就有了构造针对性攻击的基础。如果你的参数化查询也有漏洞，攻击成本会大幅降低。

三层透传，每层都不觉得自己有错。db.Query 只是返回了错误，fmt.Errorf 只是包装了一下，http.Error 只是把错误写给客户端了。没人做错什么，但结果就是灾难。

问题出在哪？每一层都把底层错误原封不动地往上抛，没有做分层转换。

还有一种更隐蔽的泄露方式。很多项目用了日志中间件，会在请求结束时记录响应内容：

func LoggingMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        rec := &responseRecorder{ResponseWriter: w}
        next.ServeHTTP(rec, r)
        log.Printf("response: %s", rec.body) // 错误响应体也记进去了
    })
}

如果错误响应里包含了敏感信息，日志里也全有。日志系统通常是多个服务共享的，日志泄露的半径比 HTTP 响应大得多。一个开发环境的日志平台可能被几十个人访问，其中任何一个人都可能成为攻击向量。

3 三层错误分层

解决方案不复杂。三层就够了：

`1`	`Handler 层（HTTP） → Service 层（业务） → Infra 层（数据库/缓存/消息队列）`

每一层有自己的错误类型，只向上暴露对上一层有意义的错误。Infra 层是物理层，Service 层是传输层，Handler 层是应用层。物理层故障不应该以原始形态暴露给应用层。当然，Go 的错误分层是约定而非强制，这要求团队的自律和 code review。

3.1 Infra 层：只报故障，不报细节

// infra/errors.go
type InfraError struct {
    Op   string // 操作名，如 "db.Query"
    Err  error  // 原始错误，仅在日志中使用
}

func (e *InfraError) Error() string {
    return e.Op + ": " + e.Err.Error()
}

func (e *InfraError) Unwrap() error {
    return e.Err
}

关键设计：InfraError 在 Error() 输出中包含底层信息，但这是给日志看的，不是给 HTTP 响应看的。转换的职责在 Service 层。

Infra 层的另一个职责：给错误打上操作标签。db.Query 返回的错误只有一个超时信息，但 InfraError 会告诉你"这是在执行 db.Query 操作时发生的超时"，而不是"某个地方超时了"。操作标签是后续做错误路由的基础，Service 层需要知道错误发生在哪个操作上，才能决定怎么转换。

有人会问：为什么不直接在 InfraError 里加一个 IsRetryable 字段？因为可重试性是 Service 层的业务判断。同样一个数据库超时，在"创建订单"场景下可能不重试（幂等性问题），在"查询用户"场景下可以重试。Infra 层不应该替 Service 层做这个决定。

3.2 Service 层：业务语义转换

// service/errors.go
type ServiceError struct {
    Code    string // 业务错误码，如 "USER_NOT_FOUND"
    Message string // 面向用户的消息
    Err     error  // 内部错误，不暴露给外层
}

func (e *ServiceError) Error() string {
    return e.Code + ": " + e.Message
}

func (e *ServiceError) Unwrap() error {
    return e.Err
}

Service 层的职责是：把 Infra 层的错误转换成业务语义。数据库连接超时不是"数据库错误"，是"服务暂时不可用"。用户不存在不是"查询返回空"，是"用户未找到"。

这个转换不是简单的文字替换。数据库连接超时在用户看来是"服务不可用"（他不知道也不关心后端是数据库），但在运维看来是"数据库连接池需要扩容"。同一个错误，面向不同的受众，有不同的表达方式。Service 层负责面向用户的表达，运维的表达留给日志。

func (s *UserService) GetUser(ctx context.Context, id string) (*User, error) {
    user, err := s.repo.FindByID(ctx, id)
    if err != nil {
        var infraErr *InfraError
        if errors.As(err, &infraErr) {
            // Infra 错误转换成 Service 错误
            return nil, &ServiceError{
                Code:    "SERVICE_UNAVAILABLE",
                Message: "service temporarily unavailable",
                Err:     infraErr,
            }
        }
        return nil, &ServiceError{
            Code:    "INTERNAL_ERROR",
            Message: "an unexpected error occurred",
            Err:     err,
        }
    }
    if user == nil {
        return nil, &ServiceError{
            Code:    "USER_NOT_FOUND",
            Message: "user not found",
        }
    }
    return user, nil
}

示例中所有 InfraError 一律转为 SERVICE_UNAVAILABLE，这是最简化的演示。实际项目中，你可能需要在 InfraError 中加一个 Kind 字段（Timeout / Permission / NotFound），Service 层据此做更精确的错误码映射。

注意：InfraError 的底层细节（数据库驱动、SQL 语句、表名）被保存在错误链里，但 Service 层不再传递它们。上层能通过 errors.As 检查错误类型做路由，但 HTTP 响应里不会出现这些细节。

这里有一个容易忽略的设计点：ServiceError.Err 保存了底层错误，这意味着 errors.As 仍然能从 Service 层的错误中提取到 Infra 层的错误类型。这在日志记录时非常有用，你可以在 handler 层统一记录完整错误链，而不需要在每一层都写日志。

但这也意味着，如果你在 handler 层直接把 ServiceError.Error() 写到 HTTP 响应里，底层信息仍然可能泄露。所以 handler 层的输出必须显式选择要暴露的字段，而不是直接调用 .Error()。

到这里，Infra 层和 Service 层的分工已经明确：Infra 只报故障类型，Service 翻译成业务语义。接下来看 Handler 层怎么用这些信息。

3.3 Handler 层：只输出安全信息

func GetUser(w http.ResponseWriter, r *http.Request) {
    user, err := svc.GetUser(r.Context(), r.URL.Query().Get("id"))
    if err != nil {
        var svcErr *ServiceError
        if errors.As(err, &svcErr) {
            switch svcErr.Code {
            case "USER_NOT_FOUND":
                writeJSON(w, http.StatusNotFound, ErrorResponse{
                    Error:   svcErr.Message,
                    Code:    svcErr.Code,
                    TraceID: traceID(r),
                })
            case "SERVICE_UNAVAILABLE":
                writeJSON(w, http.StatusServiceUnavailable, ErrorResponse{
                    Error:   svcErr.Message,
                    Code:    svcErr.Code,
                    TraceID: traceID(r),
                })
            default:
                writeJSON(w, http.StatusInternalServerError, ErrorResponse{
                    Error:   "internal server error",
                    Code:    "INTERNAL_ERROR",
                    TraceID: traceID(r),
                })
            }
            slog.Error("request failed", "error", err, "trace_id", traceID(r))
            return
        }
        // 未知错误类型，最保守处理
        slog.Error("unhandled error type", "error", err, "trace_id", traceID(r))
        writeJSON(w, http.StatusInternalServerError, ErrorResponse{
            Error:   "internal server error",
            Code:    "INTERNAL_ERROR",
            TraceID: traceID(r),
        })
        return
    }
    json.NewEncoder(w).Encode(user)
}

Handler 层有一个铁律：永远不把 error 的 .Error() 输出写到 HTTP 响应里。响应里只放 Message 字段和 Code 字段，这两个字段是在 Service 层精心设计的安全信息。完整的错误链只进日志。同理，绝不用 %+v 格式化错误后写入响应，那会遍历整条错误链，底层信息全部暴露。

注意最后一个 default 分支。对于未知的 Service 错误码，一律返回 500 + “internal server error”。这是防御性设计。如果你新增了一个 Service 错误码但忘了在 handler 里加 case，用户不会看到原始错误信息。

同一个数据库超时场景，经过三层处理：

1
2
3

HTTP/1.1 503 Service Unavailable

{"error":"service temporarily unavailable","code":"SERVICE_UNAVAILABLE","trace_id":"abc-123"}

零泄露。数据库驱动、SQL 语句、表名全部留在日志里，不出现在响应中。运维根据 trace_id 在日志中定位，攻击者什么都看不到。

我把两种方案做了对比实验：

维度	无分层版	三层分层版
HTTP 状态码	500	503
响应体内容	pq 前缀 + SQLSTATE + 库名 + SQL + 表名	`service temporarily unavailable`
敏感信息泄露	5 项	0 项
可观测性	无 trace_id	trace_id 关联日志

状态码从 500 变成 503 也有实际意义。500 意味着"服务器出了 bug"，503 意味着"服务暂时不可用，可以稍后重试"。如果你的客户端有重试逻辑，500 不会触发重试，503 会。错误分层的收益不只是安全，还有语义正确性。

4 panic 不是你的 throw

Go 里的 panic，被太多人当成了 try-catch 的 throw。

来自 Java 或 Python 的开发者，习惯用异常做控制流。转到 Go 之后，发现 error 要一路手动传回去太麻烦，于是用 panic 来"快速返回"，再在 handler 顶层 recover 一下。看起来很优雅，实际上是灾难。

翻看主流 Go 开源项目的代码，一个反复出现的模式是：大量 panic 调用可以用 error 返回替代，而项目中 panic 密度与代码库的"Go 原生度"成反比。越是 Java/Python 背景的开发者写的代码，panic 越多。

然后是性能数据。我跑了 benchmark，对比 panic+recover 和 error return 的开销：

1
2

BenchmarkPanicRecover-8     157 ns/op    48 B/op    2 allocs/op
BenchmarkErrorReturn-8      0.23 ns/op   0 B/op     0 allocs/op

panic 比 error 慢约 670 倍，每次调用有 2 次堆分配，而 error return 是零分配。在绝大多数业务场景中，157 ns 的绝对值可以忽略。panic 的真正问题不在性能，在于丢失类型信息和错误路由能力。但在高并发热路径上，累积的 GC 压力不可忽视。

为什么会差这么多？因为 panic 的工作机制跟 error return 完全不同。panic 要遍历 goroutine 的调用栈，逐帧执行 defer，收集 recover 信息，构建堆栈跟踪字符串。而 error return 就是一个简单的值传递，编译器甚至可能把它内联掉。

4.1 panic 的正当使用场景

panic 不是不能用，而是只有极少数场景才该用。判断标准很简单：如果程序继续执行会产生比崩溃更严重的后果，panic 就是合理的。

1. 程序初始化失败

func init() {
    cfg, err := config.Load("config.yaml")
    if err != nil {
        panic("fatal: cannot load config: " + err.Error())
    }
}

程序启动时配置缺失，跑下去也没有意义。没有数据库连接，没有缓存地址，所有请求都会失败。这时候 panic 是合理的，因为这是真正的不可恢复错误。不是"这个请求失败了"，是"整个程序不应该存在"。

2. 不可恢复的一致性违反

func (r *RingBuffer) Next() []byte {
    if r.count == 0 {
        panic("ringbuffer: Next called on empty buffer")
    }
    // ...
}

当一个数据结构的约束被破坏，继续执行会产生错误结果，panic 是合理的。RingBuffer 的 Next 在空缓冲区上调用，说明调用方有 bug，应该立即暴露而不是返回一个零值让 bug 静默传播。

但注意，这种情况通常意味着调用方有 bug，应该在测试阶段被发现。如果你的生产环境频繁触发这种 panic，说明你的测试覆盖不够。

3. 接口实现的编译期检查

`1`	`var _ http.Handler = (*MyHandler)(nil) // 编译期检查`

这行代码是编译期行为，不是运行时 panic。如果 MyHandler 没有实现 http.Handler 接口，编译直接报错，程序起不来。它的作用是把"运行时才发现接口没实现"的风险提前到编译期消灭。

三个场景的共同特征：错误是不可恢复的，或者应该在编译/初始化阶段就暴露。凡是运行时的业务错误，都不该用 panic。

4.2 常见的滥用模式与降级方案

滥用 1：用 panic 做"快速返回"

// 滥用
func processOrder(order *Order) {
    if order == nil {
        panic("order is nil")
    }
    if order.Items == nil {
        panic("order has no items")
    }
    // ...
}

// 降级方案：error 返回
func processOrder(order *Order) error {
    if order == nil {
        return fmt.Errorf("process order: order is nil")
    }
    if len(order.Items) == 0 {
        return fmt.Errorf("process order: no items")
    }
    // ...
    return nil
}

“快速返回"的需求本质是：调用链太长，不想一层层传 error。但这恰恰说明了你的调用链太深，需要的是重构调用链，而不是用 panic 绕过。

一个常见的辩解：“我只是把 panic 当断言用，确保前置条件成立。” 这在开发阶段说得通，但在生产环境，一个 nil order 不应该让整个服务崩溃。正确的做法是返回 error，让调用方决定怎么处理。是返回 400 告诉客户端参数有误，还是记录日志后降级处理，这个决定权不应该被 panic 剥夺。

滥用 2：用 panic+recover 做"统一错误处理”

// 滥用
func handler(w http.ResponseWriter, r *http.Request) {
    defer func() {
        if r := recover(); r != nil {
            http.Error(w, "internal error", 500)
        }
    }()
    doSomething() // 内部可能 panic
    doAnother()   // 内部也可能 panic
}

// 降级方案：三层分层 + error 返回
func handler(w http.ResponseWriter, r *http.Request) {
    result, err := svc.DoSomething(r.Context())
    if err != nil {
        handleError(w, err) // 统一错误处理，但走分层的路径
        return
    }
    // ...
}

recover 捕获的 panic 丢失了类型信息，你只能拿到一个 interface{}，做不了 errors.Is/errors.As 检查，也做不了分层路由。结果是所有错误都变成 HTTP 500，回到无分层的原点。

更严重的问题：recover 之后你很难判断 panic 的来源。是数据库超时？是 nil 指针？还是除零错误？没有类型信息，你只能猜。猜测的结果就是一律返回 500，然后运维在凌晨三点被 oncall 叫醒，发现所有请求都是 500，但不知道哪里出了问题。

还有两种更隐蔽的滥用。

goroutine 内 panic 导致整个进程崩溃：

// 滥用：goroutine 内 panic，没有 recover，直接崩溃
go func() {
    result, err := doWork()
    if err != nil {
        panic(err) // 整个进程 GG
    }
    ch <- result
}()

// 降级方案：goroutine 内把 error 传出去
go func() {
    result, err := doWork()
    if err != nil {
        ch <- Result{Err: err} // 错误通过 channel 传递
        return
    }
    ch <- Result{Data: result}
}()

goroutine 内的 panic 如果没有 recover，会导致整个进程崩溃。Go 运行时不会替你决定怎么处理不可恢复的错误，你在 goroutine 里用 panic 的后果比在主 goroutine 里更严重。正确做法是把 error 当作普通值通过 channel 传递，让调用方决定怎么处理。

同样的逻辑也适用于用 panic 做业务"短路"。你可能写过这种代码：折扣超限时直接 panic 跳出循环。

// 滥用
func calculatePrice(order *Order) float64 {
    for _, item := range order.Items {
        if item.Discount > 0.5 {
            panic("discount exceeds limit")
        }
        // ...
    }
    return total
}

// 降级方案
func calculatePrice(order *Order) (float64, error) {
    for _, item := range order.Items {
        if item.Discount > 0.5 {
            return 0, fmt.Errorf("calculate price: discount %.2f exceeds limit for item %s", item.Discount, item.ID)
        }
        // ...
    }
    return total, nil
}

折扣超限是业务规则违反，不是不可恢复错误。用 panic 处理业务逻辑违反了 Go 的基本设计哲学：error 是给调用方的，panic 是给运行时的。

5 Go 1.13 以来的新武器

Go 1.13 引入的错误包装机制（fmt.Errorf("%w", err) + errors.Is/errors.As）是分层的基础设施。没有它，你做不了错误链检查，也就做不了分层路由。但有一个痛点：当一个操作产生多个错误时，你只能拼字符串或逐个包装。

Go 1.20 加了 errors.Join，解决了这个问题。errors.Join 返回的错误可以被 errors.Is 逐个穿透检查，而手动拼接的字符串会丢失全部类型信息：

// errors.Join：保留类型信息
joined := errors.Join(errNotFound, errTimeout)
errors.Is(joined, errNotFound) // true
errors.Is(joined, errTimeout)  // true

// 字符串拼接：类型信息全丢
manual := fmt.Errorf("%v; %v", errNotFound, errTimeout)
errors.Is(manual, errNotFound) // false
errors.Is(manual, errTimeout)  // false

错误组合的方式直接决定了上层的路由能力。用 errors.Join，上层可以精确判断错误类型；用字符串拼接，上层只能拿到一坨文本。

errors.Join 的实际应用场景：批量操作中的部分失败。

func BatchInsert(ctx context.Context, users []*User) error {
    var errs []error
    for _, u := range users {
        if err := insert(ctx, u); err != nil {
            errs = append(errs, fmt.Errorf("insert user %s: %w", u.ID, err))
        }
    }
    return errors.Join(errs...) // nil if no errors
}

调用方可以检查具体是哪种错误：

err := BatchInsert(ctx, users)
if err != nil {
    var infraErr *InfraError
    if errors.As(err, &infraErr) {
        // 有 infra 层错误，返回 503
    }
}

一个额外收益：errors.Join 在没有任何错误时返回 nil。你可以直接 return errors.Join(errs...)，不需要先判断 len(errs) > 0。在大量使用时能减少很多样板代码。

再来看一个结合三层分层的完整场景。批量导入用户时，有些用户已存在（业务错误），有些插入因为数据库超时失败（infra 错误）。Service 层需要把这两种错误区分开：

func (s *UserService) BatchImport(ctx context.Context, users []*User) error {
    var bizErrs []error
    var infraErrs []error

    for _, u := range users {
        if err := s.repo.Create(ctx, u); err != nil {
            var infraErr *InfraError
            if errors.As(err, &infraErr) {
                infraErrs = append(infraErrs, infraErr)
            } else if isDuplicateKey(err) {
                bizErrs = append(bizErrs, &ServiceError{
                    Code:    "USER_ALREADY_EXISTS",
                    Message: fmt.Sprintf("user %s already exists", u.ID),
                })
            } else {
                infraErrs = append(infraErrs, err)
            }
        }
    }

    // 优先返回 infra 错误（更严重）
    if len(infraErrs) > 0 {
        return &ServiceError{
            Code:    "SERVICE_UNAVAILABLE",
            Message: "partial failure due to service issues",
            Err:     errors.Join(infraErrs...),
        }
    }
    if len(bizErrs) > 0 {
        return &ServiceError{
            Code:    "PARTIAL_SUCCESS",
            Message: "some users already exist",
            Err:     errors.Join(bizErrs...),
        }
    }
    return nil
}

Handler 层只需要对 ServiceError.Code 做 switch，不需要关心底层是哪种 infra 错误。这是分层带来的最大好处：Handler 层的错误处理逻辑是稳定的，不会因为底层 infra 变化而变化。换数据库、加缓存、换消息队列，Handler 层的代码一行不改。

6 渐进式改造路径

如果你有一个已经跑了一两年的项目，到处是 err.Error() 写到 HTTP 响应、panic 做快速返回、错误没有分层的代码，你不需要重写，可以渐进式改造。

关键原则：每一步改造都应该让系统比改造前更好，而不是让系统处于一个"改了一半"的不稳定状态。

6.1 第一步：止血——Handler 层加兜底

不动现有逻辑，只在 handler 最外层加一道防线：

func SafeHandler(h http.HandlerFunc) http.HandlerFunc {
    return func(w http.ResponseWriter, r *http.Request) {
        defer func() {
            if rec := recover(); rec != nil {
                slog.Error("panic recovered",
                    "panic", rec,
                    "trace_id", traceID(r),
                    "stack", string(debug.Stack()),
                )
                writeJSON(w, http.StatusInternalServerError, ErrorResponse{
                    Error:   "internal server error",
                    Code:    "INTERNAL_ERROR",
                    TraceID: traceID(r),
                })
            }
        }()
        h(w, r)
    }
}

这一步的收益：panic 不再泄露到响应体，所有未知错误都有 trace_id。成本极低，一个中间件函数搞定。

但这个中间件有个问题：它捕获所有 panic，包括那些"合理"的 panic（比如初始化失败）。更好的做法是：合理 panic 只发生在程序启动阶段，启动完成后进入 HTTP 服务阶段，此时所有 panic 都应该被捕获。

6.2 第二步：定义错误类型

在 infra/ 和 service/ 目录下各加一个 errors.go，定义 InfraError 和 ServiceError。不用改现有代码，只是把类型定义放在那里。

这一步本身不产生直接收益，但它是后续所有改造的基础。没有类型定义，后面的步骤无法进行。

一种常见的阻力：“我们的项目已经在用 pkg/errors 了，换成自定义类型改动太大。“不需要换。InfraError 和 ServiceError 可以在现有错误处理体系之上工作。你在 Infra 层用 InfraError 包装 pkg/errors 返回的错误，在 Service 层用 ServiceError 包装 InfraError。两种体系可以共存，不需要一次性迁移。

6.3 第三步：逐个接口改造

从最核心的接口开始，把 handler 里的 err.Error() 替换成类型检查和分层响应。每个接口改造的步骤：

handler 里加 errors.As 类型检查
Service 层加错误转换（Infra → Service）
Infra 层加 InfraError 包装

一次改一个接口，改完上线验证。不需要一次性全部改完。

这里有个实操建议：改造的顺序从外到内。先改 handler 层的错误输出（确保不泄露），再改 service 层的错误转换（确保语义正确），最后改 infra 层的错误包装（确保操作标签完整）。这样每一步都是在已有防线的基础上加固，不会因为内部改造还没完成而导致新的泄露。

最常见的改造陷阱：改了 service 层新增了错误码，但忘了在对应的 handler 里加 case，导致新错误码走了 default 分支一律返回 500。建议每次新增 ServiceError.Code 时，同步搜索所有引用该 service 方法的 handler，确认 switch case 已更新。

6.4 第四步：清理 panic

在第三步推进的过程中，你会自然发现哪些 panic 可以被替换。替换标准：

场景	能否替换	替换方案
参数校验失败	能	返回 error
外部调用失败	能	返回 error
业务规则违反	能	返回 error
初始化配置缺失	不能	保留 panic
数据结构约束违反	看情况	测试能覆盖就改 error；不能就保留

“看情况"这一行需要展开说。数据结构约束违反的 panic 是否应该替换，取决于两点：一是这个约束是否在测试中能被覆盖，二是这个 panic 发生时的后果。如果测试能覆盖，说明 panic 只会在测试阶段触发，改成 error 没有实际区别。如果测试不能覆盖（比如并发竞争条件），panic 发生时你需要完整的堆栈信息来定位问题，这时候保留 panic 更有价值。

6.5 改造的优先级

不是所有代码都值得改。优先改这些：

面向公网的 API handler——错误泄露风险最高
数据库交互层——信息泄露的重灾区
核心业务路径——错误处理不当影响用户最大的地方

内部工具、管理后台、低流量接口，可以排到后面。先止血，再治病，不求一步到位。

有人可能会问：“这套分层方案适用于微服务吗？“适用，而且更重要。微服务之间通过 API 通信，每个服务都是一个信任边界。如果你的订单服务把数据库错误原封不动地返回给支付服务，支付服务再把错误返回给网关，跨了三个信任边界的错误透传，泄露风险比单体应用更大。三层分层的逻辑在微服务中不变，只是每一层变成了服务的内部分层，服务间的错误传递需要额外做一层"跨服务错误转换”。

在写下一行 if err != nil 之前，先过一遍这个清单：

你的 handler 是否直接输出了 err.Error()？
你的错误类型是否区分了 infra 和 service？
你的 panic 是否只在不可恢复场景使用？

Go 官方关闭了语法变更的提案，这不是终点。恰恰相反，这是"在现有语法下做对"的起点。if err != nil 不是问题，不知道这个 error 该往哪层放才是问题。三层错误分层、panic 的正确使用场景、Go 1.13 以来的标准库新能力，这些都不需要改语言，只需要改认知。

你的技术债不是代码问题

Mon, 23 Mar 2026 00:00:00 +0000

本文是「AI 工程时代三部曲」第二篇。第一篇我们聊了 Agent 框架设计比模型选型更重要；这一篇，我们聊聊框架设计中最容易被忽视的一环：可观测性。

那 7 个运行了 5 年的幽灵任务

2024 年某天，Buffer 的工程师们做了一件"常规"的事：把散落在多个仓库的微服务代码合并回一个单体仓库。

迁移完成后，开始例行审计。本来只是检查重复代码、清理废弃依赖——那种每个团队都做过的日常维护。

然后他们发现了一个奇怪的 cron job。

每天凌晨 3 点执行。没人知道它是干什么的。任务列表里写着一个谁也没见过的名字。

工程师查了 git blame。最后一次修改——5 年前。提交者——一个早已离职的同事。提交信息——「add birthday email reminder」。

生日邮件提醒？这个功能不是两年前就下线了吗？

功能下线了。但任务还在跑。每天凌晨 3 点，准时执行一个早已没有意义的操作，消耗着计算资源，从来没有人知道。

这不是个例。工程师们继续翻，翻出了 7 个类似的"幽灵任务"——都是多年前某个功能的残留，功能早没了，任务还在。

这 7 个任务不是谁的失误。它们是架构制造的盲区。

不是工程师不负责。是看不见。

这不是多仓库的专利。即使是单体仓库，不同团队负责不同模块，你知道隔壁组跑了哪些定时任务吗？

代码级债务 vs 系统级债务

你可能会说，很多技术债就是代码问题啊。命名混乱、重复代码、没有测试——这些不就是技术债吗？

没错。这些是技术债。但这只是技术债的一部分。

你的技术债不只是代码问题——还有一整片你看不见的盲区。但我们先从你熟悉的部分说起。

我把它叫做代码级债务。特点是：你知道它在，你只是没时间修。

还有另一类债务，更难缠。我称之为系统级债务。特点是：你根本不知道它存在。

区别在哪？

代码级债务就像待办清单上的任务。你知道有这件事，只是排不上优先级。哪天有空了，划掉就是。

系统级债务是另一回事。它是那些你都不知道应该写在清单上的任务。不是你懒，是你压根不知道还有这件事。

Buffer 的那 7 个废弃任务就是系统级债务。不是有人故意留着不清理。是没人知道它们还在运行。

代码级债务可以用工具扫描。Linting、静态分析、代码审查——工具能告诉你哪里写得不好。

系统级债务呢？工具扫不出来。它根本不在你的扫描范围内。

可怕的不是清单上的任务。是那些你都不知道存在的任务。

AI 时代的新型债务：验证债务

系统级债务不是新鲜事。但 AI 时代给它加了一个新品种。

Sonar（一家代码质量工具厂商）2026 年的开发者调研有一组数据：96% 的开发者不信任 AI 生成代码的功能准确性。

96%。几乎所有人都不信任。

但同一份调研还有另一个数字：只有 48% 的开发者会在提交代码前验证 AI 生成的内容。

不信任，但不验证。

换句话说，超过一半的代码，在没有被充分验证的情况下进入了生产环境。我给这种现象起了个名字：验证债务。

验证债务是系统级债务的 AI 时代变种——你知道代码存在（代码级），但你不知道它对不对（系统级）。它进入了生产环境，成为系统的一部分。

这不是代码质量问题——AI 写的代码可能语法完美、逻辑清晰。问题是你不知道它在特定场景下会不会出错。你签了合同但没读条款。哪天出事了，你才发现里面埋着一颗雷。

传统的系统级债务是"任务在跑但你看不见"。验证债务是"代码在跑但你不确定它对不对"。

本质一样：看不见的债务，是还不掉的债务。

你上周用 AI 写的代码，认真测过吗？

可观测性不等于加监控

回到 Buffer 的故事。7 个废弃任务为什么能跑 5 年没人管？

不是因为没有监控。Buffer 有日志，有告警，有 dashboard。那些 cron job 每天凌晨 3 点执行，大概率还在某个 log 里留下过痕迹。

但这不是监控能解决的问题。

这里有一个容易混淆的概念。说到"可观测性"，大多数工程师第一反应是 metrics、logs、traces——SRE 那套。发现异常、定位故障、追踪调用链。本文说的不是这个。

本文说的是一种更基础的东西：结构性可见度。你有没有一份清单，知道所有正在运行的东西？

监控回答的是"这个东西是否正常运行"。结构性可见度回答的是"有哪些东西在运行"。你没法监控一个你不知道存在的东西。

每个团队有自己的储物间，各自整理得井井有条，日志齐全，告警也设了。但没有人有"整栋楼所有储物间"的清单。角落里堆着什么，不是检测不到异常，而是压根没人知道那个角落归谁管、里面有什么。

单体仓库的价值就在这里——把所有储物间打通变成一个大仓库。东西还是那些东西，但现在你一眼能看到全貌，那些藏了 5 年的东西终于浮出水面。

这就是结构性可见度的价值。不是帮你"检测"问题，是给你"看见"的能力。看得见，才能上清单。上了清单，才会被清理。

清理代码是还利息，清理盲区才是还本金

到这里，技术债的图景清晰了。

代码级债务是你能看见的债务。命名混乱、重复代码、缺少测试——这些是利息。工具能扫，重构能修。还起来虽然费时间，但至少你知道要还什么。

系统级债务是你看不见的债务。废弃的任务、断连的服务、未验证的 AI 代码、过期的证书、废弃的环境变量、失效的告警规则——这些是本金。不是不想还，是不知道欠着。

清理代码是还利息。清理盲区才是还本金。

你可能觉得这是大公司才有的问题。其实不是。打开你的终端，花 5 分钟试试。

如果你用 Linux/macOS，crontab -l 列出当前用户的所有定时任务。你知道里面每一条都还在干什么吗？

如果你用 Docker，docker ps -a --filter "status=exited" 看看有多少已停止但未清理的容器。有些可能是几个月前调试时创建的，早就没用了，但它们的卷和网络配置还占着资源。

如果你管理 Kubernetes 集群，kubectl get cronjobs --all-namespaces 列出所有 CronJob，然后对照业务需求清单——有多少你认不出来？

如果你管 CI/CD 流水线，看看有多少 pipeline 配置指向已经不存在的分支或仓库。GitLab 和 GitHub Actions 不会自动清理这些。

大概率你会发现至少一两个"这玩意还在？“的东西。这就是本金。它就安静地待在你的开发环境里，等着哪天被人翻出来，或者永远不会被翻出来。

你的技术债清单里，有多少是这样的"未知债务”？

系列衔接：从可观测性到工程师机遇

Buffer 最后怎么样了？

那 7 个废弃任务被清理了。但更重要的不是清理本身——是他们通过这次迁移获得了一个东西：系统视角。

过去，每个团队只看自己的仓库。现在，终于能看到全貌。这个视角的转变，比清理那 7 个任务更有价值。

在 AI 工程时代，这种视角转变正在成为工程师的核心能力。

上一篇我们聊了 Agent 框架设计比模型选型更重要。这一篇的结论是：可观测性是框架设计的核心要求。

下一篇，我们来聊聊 Go 工程师在 AI 时代的机遇。剧透一下：AI 正在抹平"会写代码"的门槛，但系统设计、并发安全、性能优化——恰好是 Go 工程师最擅长，也是 AI 最难替代的能力。

技术债不只是代码写得差。看不见的债务比写得差的代码更难还。清理代码是还利息，清理盲区才是还本金——而大多数团队的债务清单上，只有利息。