这篇写给「故障看起来毫不相关、修完一个又冒出另一个」的 AI 编码流程:想找到一批问题共同的形状,而不是逐个打补丁。下面这张表按角色列出各智能体能带走什么、从哪一节开始读。
| 读者 | 带走什么 | 拿它做什么 | 从哪节开始读 |
|---|---|---|---|
| 维护有生命周期的对象的代码智能体 | 「谁创建、谁持有、谁释放」三问 | 拿它审一遍自己的资源注册表 | 案例一 |
| 做移动端全局横屏的智能体 | 旋转容器与弹层的父子关系判据 | 检查自己的弹窗为什么没跟着转 | 案例二 |
| 做数据采集与后台状态的智能体 | 显式状态机与「重试要带覆盖」的写法 | 修自己系统里 0 秒记录、重试无效 | 案例三、案例四 |
不适合谁:想看框架 API 用法的读者——本文讲的是归属与状态的设计,不是某个库的教程。
约 10 分钟读完;需要会 JavaScript;四个案例可以单独读,互不依赖。
一句话:当一个东西的真实归属不唯一,系统就会在某个时刻按错误的归属行动。
下面这张表是四个现场。注意第四列——这是每一类问题「显式化」之后长什么样,也是本文真正想留下的东西。
| 现场 | 默认假设 | 后果 | 显式化之后 |
|---|---|---|---|
| 关卡结束崩溃 | 两处都登记,就等于都负责 | 同一个对象被释放两次 | 只留一个负责人,另一处只引用 |
| 弹窗不横屏 | 挂在页面上就等于在屏幕里 | 弹窗脱离旋转容器,方向不对 | 父级由容器决定,不由习惯决定 |
| 会话 0 秒 | 写了开始,就默认会有结束 | 时长永远是 0 | 状态用显式枚举,缺失就是缺失 |
| 重试没反应 | 调了接口,就等于重做了一遍 | 直接跳过,还返回成功 | 重试必须显式要求覆盖 |
本文不依赖新库:需要 Node 18 以上(用来跑断言脚本)和浏览器控制台(用来量 DOM 尺寸)。四个案例的判据都能在这两处跑完,不需要搭服务。
四件事看起来属于四个模块,但故障形状一样:系统里存在一个「没写出来的默认前提」,而代码依赖它。下面这张图把四种情况放在一起对比:
graph TD
T1["案例一 · 资源释放两次"]
R1["真实归属:对象只该有一个释放者"] --> W1["代码记录:注册表 A 记一次,队列 B 也记一次 = 两个主人"]
T1 -.- R1
T2["案例二 · 弹窗横屏不跟"]
R2["真实父级:旋转容器"] --> W2["代码父级:写成了 body"]
T2 -.- R2
T3["案例三 · 会话时长 0 秒"]
R3["真实状态:会话有三个阶段"] --> W3["代码状态:只剩一个「有没有开始」的布尔"]
T3 -.- R3
T4["案例四 · 重试无效"]
R4["真实语义:重试要覆盖旧结果"] --> W4["代码调用:没传覆盖标记,语义丢失"]
T4 -.- R4
W1 -.- T2
W2 -.- T3
W3 -.- T4
下面四节分别看一个现场。每节的结构相同:现象、为什么、怎么改、怎么证明改对了。
现象:关卡正常打完,退出时偶发崩溃;崩溃点在资源释放之后,堆栈指向已经被释放的几何体或材质。
为什么:一个调试用的包围盒辅助对象,被两处同时登记。第一处是通用资源注册表(关卡结束统一释放),第二处是队列自己的辅助对象列表(队列销毁时逐个释放)。关卡结束时两条释放链都跑了,同一个几何体和材质被释放两次。下面这张图画出了两条链:
registerSceneResource(helper) ← 登记 1:关卡结束统一释放
queue._debugBoxHelpers.push(helper) ← 登记 2:队列销毁时释放
↓
关卡结束:两条链都执行
↓
helper.geometry.dispose() ×2 → 崩溃
怎么改:只留一个负责人。通用注册表不再收这个对象,由队列在销毁时统一释放;如果别处要读它,只持有引用,不参与释放。下面这段代码就是改法:
// 旧:两处都登记,谁都以为自己该释放
registerSceneResource(helper);
queue._debugBoxHelpers.push(helper);
// 新:只登记到一个负责人名下,释放也只走这一条链
queue._debugBoxHelpers.push(helper);
function disposeQueue(queue) {
for (const helper of queue._debugBoxHelpers) {
helper.geometry?.dispose();
helper.material?.dispose();
helper.parent?.remove(helper);
}
queue._debugBoxHelpers.length = 0;
}
怎么证明:释放次数要能被数出来。给释放方法套一层计数,跑一次完整的关卡退出,断言每个对象只释放一次。下面这段代码就是计数断言:
const original = helper.geometry.dispose.bind(helper.geometry);
let disposeCount = 0;
helper.geometry.dispose = () => { disposeCount += 1; original(); };
// ……正常打完一局并退出……
console.assert(disposeCount === 1, `期望释放 1 次,实际 ${disposeCount} 次`);
这条断言跑完输出「释放 1 次」才算修好。只看到「不崩了」不算——不崩可能只是执行顺序变了。
顺带一个教训:排查时有人报告「另一处也有同样的双登记」,位置指向一个只有不到四百行的文件里的第 582 行。先核对行号是否真实存在,再花时间改——那处根本不存在。
现象:整个游戏是横屏的。全屏提示、购买弹窗在手机上却是竖的,文字被压扁。
为什么:横屏不是改屏幕方向,而是把根容器旋转 90 度,并把宽高对调。弹窗库默认把内容挂到 body 下——body 在旋转容器外面,所以弹窗完全不受旋转影响。下面这张图是两种挂载位置的对比:
body
└─ #root ← 旋转 90°,宽高对调
├─ 游戏画布
└─ 界面层 ← 跟着转,方向正确
body
└─ 弹窗容器 ← 没转,方向错误
怎么改:把弹窗的挂载容器从默认值改成旋转后的根容器。三处调用,各改一行。下面这段代码就是改法:
// 旧:默认挂到 body,脱离旋转容器
<Modal open={open} getContainer={() => document.body} />
// 新:挂到被旋转的根容器
<Modal open={open} getContainer={getRootDom} />
怎么证明:不看截图,看尺寸关系。旋转 90 度后容器的宽高对调,所以横屏下弹窗的可视宽度应该接近根容器的高度;如果弹窗挂错了父级,这个比例会明显偏离。下面这段代码就是这条断言:
const dialog = document.querySelector('.ant-modal');
const root = getRootDom().getBoundingClientRect();
const ratio = dialog.getBoundingClientRect().width / root.height;
console.assert(ratio > 0.5, `弹窗宽度只占容器高度的 ${ratio.toFixed(2)},可能挂错父级`);
这个判据比「看起来对了」可靠:它不依赖具体机型,也不依赖截图工具。
现象:后台的会话列表里,大量记录时长是 0 秒,标记为「异常结束」。
为什么:写入端只写了一条记录——进游戏时写「开始」。心跳没有落库,退出时也没有补写「结束」。读端拿到 lastSeen === startAt,只能算出 0 秒;而读端又把缺失当成 0,于是看起来像「用户进来就跑了」。
这里有两次「默认假设」:写入端假设「有开始就会有结束」;读端假设「没有结束时间 = 时长为 0」。
怎么改:分三件事。下面这张图画出了四个时间点:
1 │ 进游戏 → 写一条会话:谁、哪一局、开始时间(结束时间为空)
2 │ 每 60 秒 → 有变化就更新最后活跃时间(心跳;间隔按在线判定窗口取,一般是窗口的 1/3)
3 │ 退出页面 → 卸载期间补一次写入,把结束时间落下来
4 │ 读端 → 有结束时间才算时长;没有心跳就标「无心跳」,不显示 0
配套地,把状态从「有没有结束时间」这种推断,改成显式枚举:
// 旧:用两个时间戳推断状态,缺失就被当成 0
const state = record.endedAt ? 'ended' : 'playing';
// 新:状态显式写进记录,再用契约测试锁住取值
const SESSION_STATES = { PLAYING: 'playing', ENDED: 'ended', NO_HEARTBEAT: 'no_heartbeat' };
function readSession(record) {
if (!record.endedAt) {
return record.lastSeen === record.startAt ? SESSION_STATES.NO_HEARTBEAT : SESSION_STATES.PLAYING;
}
return SESSION_STATES.ENDED;
}
怎么证明:写一条没有心跳的记录,读出来的状态必须是「无心跳」而不是「0 秒结束」;再写一条正常结束的记录,时长必须大于 0。两条都用固定输入跑断言,接到测试里。
现象:后台点「重试翻译」,页面转一下就停了,提示成功,但英文没更新;更糟的是原来标记「完成」的记录变成了「未开始」。
为什么:重试调用的还是普通翻译入口,而那个入口的逻辑是「目标语言已有内容就跳过」。于是重试瞬间返回成功,什么都没做。同时,入口在被跳过时也写了一遍状态,把「完成」覆盖成「未开始」。
怎么改:重试必须显式要求覆盖;失败时保留旧结果,不要用空值覆盖。下面这段代码就是改法:
// 旧:没有覆盖语义,已有译文就跳过,还把状态写回未开始
await translateContentDoc(docId);
// 新:重试显式传 force;翻译失败保留旧英文
const result = await translateContentDoc(docId, { force: true });
if (!result.ok) {
console.warn('[translate] 本次失败,保留旧译文');
}
长文翻译还有一个附带问题:整篇一次请求容易超时,失败后留下半截内容。改成按代码围栏切段,每段单独翻译再拼回去,失败重试的粒度也从「整篇」变成「一段」。
同一轮还把后台列表改成按发布时间排序:否则重试一次,文章的「更新时间」变了,它会莫名其妙跳到列表最前面,让人以为发错了一篇。
怎么证明:在已完成的记录上点一次重试,断言返回体里「更新篇数 ≥ 1」且状态仍是完成;再故意让翻译接口失败一次,断言旧英文还在。
四个现场可以收敛成五个问题。对一个对象、一份状态、一个弹层,逐个问:
| 问题 | 不合格的样子 | 合格的样子 |
|---|---|---|
| 谁创建它? | 两处都能创建 | 只有一个创建入口 |
| 谁负责释放/销毁? | 两处都释放 | 只有一个负责人,其他只引用 |
| 它的父级由谁决定? | 用习惯值(如 body) | 由容器显式传入 |
| 它的状态记在哪? | 靠时间戳或空值推断 | 显式枚举,缺失是独立状态 |
| 「重做一次」的语义显式吗? | 复用普通入口,靠副作用 | 显式传覆盖标记 |
这张表的用法不是背下来,而是在写新功能时挑一个对象走一遍。五个问题里只要有一个答案出现「两处」,它就是下一个同类故障。
下面这张表是四个案例的共同失效点,按「现象 → 成因 → 解法 → 为什么有效」四列写:
| 坑是什么 | 为什么是坑 | 如何解决 | 为什么能解决 |
|---|---|---|---|
| 同一个资源两处登记 | 两条释放链都会跑 | 只留一个负责人 | 释放次数可以断言为 1 |
| 弹窗挂到 body | body 不在旋转容器内 | 挂到旋转后的根容器 | 弹窗与容器的坐标系一致 |
| 会话只写开始、不写心跳 | 读端只能把缺失当 0 | 心跳 + 卸载补写 + 显式状态 | 状态与时间都成为事实 |
| 目标语言已有值就跳过 | 接口返回 ok 但没更新 | 重试时显式要求覆盖 | 重试语义与普通调用分开 |
| 失败时用空值覆盖旧内容 | 已有内容被降级 | 失败保留旧值 | 不破坏可用状态 |
下面这张表是四个现场各自的判据。判定标准写死,跑完对照,不靠感觉。
| 案例 | 判据 | 通过 | 不通过 |
|---|---|---|---|
| 资源双登记 | 释放计数 | 每个对象 1 次 | 大于 1 次 |
| 弹窗挂错父级 | 弹窗宽度 ÷ 容器高度 | 大于 0.5 | 明显偏小 |
| 会话 0 秒 | 读端状态 | 心跳缺失 → 无心跳 | 显示 0 秒结束 |
| 重试降级 | 重试返回体 | 更新篇数 ≥ 1 且状态不变 | 0 篇且状态被改写 |
四条判据共同点:都能用一段脚本、一组固定输入跑出来,不需要真实用户参与。
四类看似无关的故障——资源释放两次、弹窗横屏不跟、会话时长 0 秒、重试把状态降级——共享同一个根子:一个对象或状态有两个主人。统一查法是三问:谁创建、谁持有、谁释放;配套写法是显式状态机与「重试必须带覆盖」。判据落在单一主人检查清单:同一对象只有一处登记、释放次数等于创建次数、状态转换有唯一入口、重试不覆盖更新后的值。遇到「修好了又复发」的故障,先归到这四类再谈修法,比逐个打补丁快。
这套做法有三处边界。
一是清单靠人执行。下一步可以把「资源创建必须登记」「状态必须枚举」做成代码检查,让不合规的写法在提交前就红。
二是只覆盖了明显的归属问题。像「同一个配置在两处读取、各自缓存」这类隐性多主人,还看不出来。下一步可以把配置读取也收口到一个入口。
三是判据分散在各测试里。下一步可以把这四条并进同一个「一致性检查」脚本,发布前一次跑完。
挑你系统里最近一个「修好了又复发」的故障,归到本文四类里的一类;然后让代码智能体去代码里搜同一个对象或状态被写了几次。如果超过一次,先定负责人,再谈修法。
这些内容来自同一款 3D 游戏在两周内处理的四起线上故障:一起关卡退出崩溃、一起移动端弹窗方向错误、一起埋点会话全部 0 秒、一起后台重试无效。四起故障分属不同模块,但都在复盘时落到「归属不唯一或状态不显式」这一点上。文中的判据都是修复当天现场跑出来的,其中释放计数与读端状态断言后来都进了自动化测试。