# 实现层：幂等与退化——AI 挂了，业务不能停

> **AI Harness Engineering 系列 · 第六篇** · 王海涛（GitHub：derekwang85 · 腾讯云 TVP / 架构师名人堂）

![00-intro.jpg](https://developer.qcloudimg.com/http-save/yehe-11918656/fe58f17cf7a076495bc32dda5bf970b4.jpg)

民航客机有两个引擎，不是为了让飞机飞得更快，是为了让一个引擎失灵时，飞机还能飞。现代客机的适航标准里有一条硬规矩：单发失效后，飞机必须还能继续爬升、巡航、降落。工程师花在"第二个引擎"上的心思，不比重写第一个引擎少——因为飞行安全的底线从来不是"引擎不会坏"，而是"坏了以后怎么办"。

软件系统从电气工程里借来了同一个思路，叫冗余设计；又借来了断路器的概念——电路过载时，不是让整栋楼停电，而是先切断这一路，保住其他路。

AI 编码项目比传统项目更需要这套"坏了以后怎么办"的设计，理由很残酷：**AI 会挂，而且挂得比人干脆。** 人不舒服了会慢下来，会求救，会留下半句话；AI 挂掉的方式是直接停摆、静默、或者假装自己还活着。前面五层约束（战略、架构、契约、门禁、执行前宣言）管的是"AI 产出什么"，这一篇讲的是约束金字塔的最底层——**实现层**：当一切约束都失效、当 AI 真的挂了，你的业务怎么不跟着停。

---

## 一、实现层为什么是最后一道防线

![01-last-line.jpg](https://developer.qcloudimg.com/http-save/yehe-11918656/27a32301e5a84d58ccd4c13c205fd11c.jpg)

约束金字塔五层，越往上越抽象，越往下越具体。战略层是一句话，架构层是一份 ADR，契约层是一份 Spec，门禁层是一个脚本，实现层是一行行代码。前四层决定了代码"应该长什么样"，实现层决定代码"实际长什么样"。

但实现层有一个前四层都没有的性质：**它是唯一直接面对用户和业务的层。** 约束写错了，表现为代码质量差；实现层写错了，表现为业务直接中断。所以这一层的问题，永远是最急的——你可以在周一修 ADR，但你不能让交易系统到周一再恢复。

更关键的是，实现层是上行反馈的起点。第一篇讲过双向反馈：实现层暴露的问题，流回门禁层、契约层、架构层、战略层，逐层修正约束。这一篇要补上它的另一半：**实现层自己的问题，得自己在实现层解决**——用幂等、用退化、用失败可见、用快速恢复。约束能防止大部分错误，但防不住全部；剩下的那些，实现层要自己兜住。

## 二、幂等：同一个请求，执行两次只能有一个结果

![02-idempotency.jpg](https://developer.qcloudimg.com/http-save/yehe-11918656/8a14ddbf759fc27401cf923878e70f8b.jpg)

实现层第一个兜底手段，是幂等（idempotency）。概念一句话：**幂等要回答的问题只有一个——同一个操作，重复执行那么多遍，会不会制造出第二个真实结果？**

为什么要跟 AI 强调这个？因为 AI 编码项目里，"重复执行"是常态，不是意外。AI 跑一个脚本，网络抖了一下，它不知道刚才那步到底成没成功，于是重跑一遍——这是最常见的情景。传统系统里，重复执行顶多多一条日志；AI 系统里，重复执行可能多一笔订单、多发一条通知、多扣一次钱。幂等就是给"重试"上保险：**你尽管重试，我保证结果只有一个。**

TradeOMS 里最典型的幂等设计，是测试数据的播种脚本。UAT 测试要反复跑，每跑一轮都要重新准备数据。最早的时候，测试脚本里全是硬编码 ID——`orders/1`、`kyc/1`、`quotes/1`——种子数据每轮重建后 ID 全变了，这些硬编码参考全废，测试脚本一轮就崩。

修复的方案不复杂，但很能说明幂等的思路：种子脚本全部改成 `INSERT ... ON DUPLICATE KEY UPDATE`——**有这条记录就更新，没有就插入**。不管脚本跑几遍，数据库里始终是同一套数据。配合动态 SQL 查询真实 ID，硬编码引用全部消失。从 0 个 seed 脚本到 3 个（ops / buyer / integration），全部幂等可复现，UAT 从此可以放心地反复跑。

幂等设计的判断标准只有一条：**把同一个请求发给系统两次，观察它是不是做了两遍。** 如果做了两遍，就是幂等缺失——不管它是 AI 发起的还是人发起的，都是隐患。给接口加个 `idempotencyKey`（幂等键），请求第一次来记下结果，重复的键直接返回第一次的结果，这是实现层成本最低、收益最直接的加固。

## 三、退化：主路不通，走辅路

![03-degradation.jpg](https://developer.qcloudimg.com/http-save/yehe-11918656/09dcbc294f74ad84f47e4bfdf05fbf95.jpg)

幂等管"重复执行"，退化管"部分失效"。

退化（degradation）的意思是：**核心功能不可用时，不是整个系统停摆，而是降到次一级的可用状态继续服务。** 用户要的是"系统还在"，至于精度打折扣，是第二位的。

TradeOMS 里有一个真实的退化案例。交易系统依赖外部汇率源（NCC）提供实时汇率，而汇率是报价功能的前置依赖。FMEA 分析时发现一个高风险的故障模式：NCC 不可用时，系统直接把错误暴露给用户——报价功能整段不可用。对策是两条：**兜底汇率缓存 + 降级提示**。NCC 正常时，汇率照常实时获取，同时缓存最近一份；NCC 挂掉时，报价功能用缓存汇率继续服务，页面上明确标注"汇率数据可能延迟"。用户照样能报价，只是精度降级——系统没停，业务没断。

这个案例里的"降级提示"是画龙点睛的一笔。**降级可以接受，静默的降级不可接受。** 如果系统悄悄用了一份过期汇率而不告诉任何人，比直接报错更危险——因为下游会基于错误数据做决策。降级必须可见：要么用户看到提示，要么监控看到告警。不可见的降级，等于没降级。

## 四、失败必须可见：一次全员暴毙的教训

![04-failure-visible.jpg](https://developer.qcloudimg.com/http-save/yehe-11918656/402ddcc0a7cddb8fe2e5a1efe91f38e9.jpg)

幂等和退化都是"设计"出来的，但实现层还有一个更朴素、也更要命的点：**失败本身必须可见。** 这一条，我们是用一次事故换来的。

那天，多 Agent 系统里的所有 worker 突然同时死掉了。排查了很久才发现根因：所有 worker 的启动脚本都用了 `set -e`——遇到任何错误立即退出——配合 flock 文件锁竞争，一个 worker 因锁竞争退出后，留下的锁状态让后续所有 worker 在启动阶段全部异常退出。同一时间，全员死亡，而且因为脚本设定是"静默失败"，没有任何一个进程发出告警。

这次事故有两个教训，一个技术、一个认知：

**技术教训**：后台守护进程不能用 `set -e`。`set -e` 适合"一条命令失败就整体失败"的前台脚本；后台守护进程需要的是显式错误控制——`set +e` + 独立的异常处理路径。守护进程的天职是"活着"，不是"严格"。

**认知教训**：静默失败比失败本身更贵。失败会触发告警、触发重试、触发人工介入；静默失败什么都不触发——系统假装一切正常，直到用户发现业务已经坏了很久。修好后我们加了两道保险：所有后台进程强制显式错误控制，再加一个看门狗（watchdog），每 5 分钟巡检一次进程健康，死了就自动拉起——人工重启要 30 分钟以上，看门狗自动恢复不到 5 分钟。

这就是实现层的第一性原理：**系统可以被杀死，但不能被静默。**

## 五、恢复要快：14 个文件的连锁崩溃

![05-recovery.jpg](https://developer.qcloudimg.com/http-save/yehe-11918656/441eb83fdd28419747a56d898c06d113.jpg)

兜住了"重复执行"、"部分失效"、"静默失败"，还剩最后一个场景：系统真的挂了，怎么最快恢复。

一次真实事故：MySQL 的 Docker 容器挂掉后，服务全部不可用。恢复 Docker、启动后端——14 个文件的编译错误像多米诺骨牌一样依次暴露：import 缺失（移除了废弃 Controller 但 Service 没删）、类型不匹配（DTO 重构后老字段名残留）、`@ConditionalOnProperty` 链式爆炸（一个 bean 的 condition 依赖另一个 bean 的 condition，形成循环）。每一个错误都不难修，但 14 个错误排队出现，恢复启动花了 45 分钟以上，而且全程是人工逐文件排查。

修复的方案是给恢复过程装一个"快速定位器"：`pre-compile-check.sh` 门禁上线，专门检测三类问题——stale import、conditional bean 循环、启动 smoke test。此后同样的场景，恢复时间从 45 分钟以上压缩到 5 分钟以内，编译恢复从 14 次 mvn compile 变成 1-2 次。

这个案例的价值不在那个脚本，而在一个判断：**恢复的瓶颈往往不是"修"，是"找"。** 系统挂掉后，最快的恢复路径不是让人一个个文件排查，而是让一个自动化检查器先报出"问题都在这三类里"，人只做定点修复。AI 挂了以后，恢复速度取决于你的系统里有没有"找得快"的工具，而不是"修得好"的人。

## 六、活的注脚：derekinside 的检索降级

这套"挂了业务不停"的设计，在我那个本地知识库副脑 **derekinside** 里有个干净的对应物——检索降级。

derekinside 依赖语义搜索做知识检索，有一次嵌入模型切换后，`memory_search` 索引失效，语义搜索整段不可用。但系统没有瘫痪：HTTP API 的搜索功能依然正常，检索自动降级到备用路径，核心功能继续服务。知识检索是 derekinside 的心脏，但心脏停跳时，它没有选择整体停摆——它选择了带着一个降级的心脏继续跑。

幂等、退化、失败可见、快速恢复，这四样东西在 derekinside 里不是一个设计文档，是它活着的状态。

---

## 七、第一天就能用的清单

![06-checklist.jpg](https://developer.qcloudimg.com/http-save/yehe-11918656/65d331ec789e1c8aa6b382b27e75266f.jpg)

如果你的项目正在用 AI 编码，今天就能给实现层上四道保险：

- [ ] 找出你系统里**最常被重试的操作**（订单、通知、扣款），给它加一个幂等键：同一个键只执行一次，重复请求返回第一次的结果
- [ ] 列一个**降级清单**：你的核心依赖里，哪个挂了会导致整段功能不可用？给它准备一条降级路径（缓存兜底 / 备用源 / 降级提示）
- [ ] 检查你的**后台脚本**有没有 `set -e`——守护进程必须改成显式错误控制，再加一个 5 分钟巡检的看门狗
- [ ] 做一次**静默失败排查**：翻一翻日志，有没有"看起来正常、实际没干活"的任务？把它们的失败变成可见的告警
- [ ] 给恢复过程写一个检查脚本（参考正文的 `pre-compile-check.sh`）：启动时先扫三类已知问题——stale import、condition bean 循环、smoke test——脚本先把"问题属于哪几类"报出来，再让人定点去修，恢复时间能省一个数量级

五条里做到三条，你的系统就从"AI 挂了业务跟着停"变成了"AI 挂了，业务自己想办法继续"。实现层是约束金字塔的底座，也是最容易被低估的一层——前四层决定系统能长多高，实现层决定它摔下来的时候摔得多难看。下一篇，我们回到金字塔的侧面，讲一个贯穿所有层的顺序问题：执行前宣言——先立规约，再写代码。

---

*（《驾驭 AI · AI Harness Engineering》系列第六篇。下一篇：执行前宣言——先立规约，再写代码。）*

---



AI Harness Engineering 系列 · 第六篇 · 王海涛（GitHub：derekwang85 · 腾讯云 TVP / 架构师名人堂）

驾驭 AI · AI Harness Engineering ·实现层设计

幂等、退化、失败可见、快速恢复，这四样东西在项目要处于“活着”的状态，产品就能青春永驻

 CTO

人工智能

后端

架构设计

AI编码项目的实现层需以幂等、退化、失败可见与快速恢复为兜底，确保AI故障时业务不中断。幂等键防重复执行，降级路径加缓存提示，显式错误控制替代静默失败，自动化检查脚本加速恢复。四道保险可落地，核心是系统能被杀死但不能静默。

2026上云采购 | AI焕新·智启新局

coding

lexiang

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

驾驭 AI · AI Harness Engineering ·实现层设计-腾讯云开发者社区-腾讯云

驾驭 AI · AI Harness Engineering ·实现层设计

驾驭 AI · AI Harness Engineering ·实现层设计

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐