藏在 API 层里的那个 Bug

桌子视图加载了。Canvas 渲染了。桌子在数据库里存在。

但当前端向服务器请求当前桌子的状态时 —— 座位、stack、谁坐在哪里 —— 服务器返回了 404。什么都没有。没有座位,没有游戏数据,没有任何东西让 renderer 去画。

Canvas 一片空白,因为它没有任何东西可画。

这里是技术解释,尽量短:在 table engine 前面的 API 网关在转发每个请求之前会从 URL 上剥掉一个前缀。/api/v1/tables/... 到达 table engine 时变成 /tables/...。Table engine 的路由,正如构建会话写的那样,是按完整前缀注册的 —— 所以服务器在监听 /api/v1/tables/...,但接收到的是 /tables/...。每个请求都打不中。

不是逻辑错误。不是坏掉的算法。一张地址写错了的路由表。这种事只有在你把整个 stack 一起跑起来测试时才会冒出来。

找到它花了多久?

从开始到修复:不到一小时。

这是快的。让它快的是:debugging 方法论。

跟一个 AI agent 一起搞这件事,不是问"哪里出错了?"然后等答案。是同时把对的上下文给 agent —— 处理这个前缀的代理配置、table engine 里路由注册的文件、显示 404 的请求日志 —— 然后让它去追这个不一致。

当这些片段同时可见时,agent 可以在一个对人类工程师来说光是导航就要二十分钟的表面上做 pattern-matching。Agent 用大约三分钟找到了代理 rewrite 规则和 table engine 路由注册之间的 mismatch。

Bug 背后的 Bug

找到路由 bug 暴露了下一个。

端点现在响应了。但它返回的数据格式不对。

Table engine 内部说一种语言:座位号,像 occupied 这种状态码,作为简单整数的原始筹码数。前端 renderer 说另一种:座位索引,像 $235.50 这种格式化的货币字符串,以及它根据写它时所依据的类型定义按合约期望的特定字段名。

没人写翻译层。构建会话写了端点,它返回了内部格式。Renderer 收到不认识的数据,然后悄悄地什么都不产生。

这是那种出了名地难提前写测试的 bug。你必须让两个系统都跑起来、连起来、互相试着说话才能看到。当两个系统各自都没 bug 时,没有任何 unit test 能覆盖两个系统之间的间隙。

这对构建方法论意味着什么

测试阶段不意味着方法论失败了。它意味着方法论把我们带到了测试。

每个软件平台都有一层集成层,各个部分必须在现实世界里碰头。Spec-driven 开发让你更快到那一层。它不跳过它。

这个系列的下一篇覆盖了我们应用修复之后发生了什么 —— 而浏览器依然显示了同样坏掉的结果。

要看我们怎么构建背后的工程方法论 —— spec、session、agent 在 session 期间做什么、架构师做什么 —— 完整的写作在 The Salty Korean 上。

Stay salty.