我最近在带几个团队做项目重构发现一个特别有意思的现象大家用 AI 写代码的量上去了但代码质量反而有点尴尬——接口设计全靠拍脑袋异常处理永远是一串空的except。说到底不是 AI 不会是没人告诉它该往哪个方向补。这个标题是我小项目实战系列的第二篇。第一篇聊的是怎么用 AI 做整体技术方案这一篇专门讲清楚一件事怎么让 AI 帮你把接口设计和异常处理这两个最容易差不多得了的环节补到位。接口设计决定系统骨架异常处理决定系统下限这两个恰恰是最适合 AI 介入、也最能体现工程经验的环节。如果你正在用 AI 写业务代码、做内部系统或者想把自己从curd 工程师往上拉一拉这篇文章里的思路和提示词可以直接抄走。我会把上下文怎么组织、指令怎么下、生成结果怎么校验、踩过的坑怎么避全部摊开来讲。1. 为什么接口设计和异常处理是 AI 辅助的最佳切点先说个反直觉的结论AI 写接口逻辑经常比人更稳但前提是你得给它足够的上下文。很多开发者抱怨 AI 生成的接口不可用大部分时候不是模型能力问题是输入信息太稀薄。你只丢一句帮我写个用户注册接口它当然只能给你一个泛泛的版本。但如果你把表结构、调用场景、幂等要求、限流策略都讲清楚生成的接口质量会明显不一样。异常处理就更典型了。日常开发里异常处理往往是最容易被后面再补的部分。需求排期紧的时候先保证主流程能跑通异常分支能省则省。等系统上线线上日志开始刷报错才想起来当时没好好处理。AI 特别适合干这个活儿因为它不会累、不会烦可以从各个角度把异常分支铺开帮你织一张兜底的网。1.1 接口设计和异常处理难在哪接口设计的难点从来不是写那几行代码而是决策这个接口该用 POST 还是 PUT它们是存在幂等性差异的这个差异在重试场景下会被无限放大。参数是放路径、查询字符串还是请求体影响的不仅是风格还有缓存策略和安全性。返回结构怎么定才能在不破坏兼容性的前提下扩展错误码怎么编码才能让前端拿到后不用做一坨 switch-case这些决策需要你对手头业务有全局理解。但 AI 的强项恰恰是你只要把碎片化的业务信息喂给它它能把方案 理由 取舍一次性输出而且基于的训练数据里已经沉淀了大量一线互联网公司的接口规范。异常处理的难点则更多在想象力匮乏。写主流程代码的时候我们的大脑会自动进入乐观模式——数据库不会挂、Redis 不会超时、上游不会返回垃圾数据。但真实世界不是这样的。AI 不需要乐观模式它天生就会想这个参数如果传 null 呢如果并发来了呢如果下游超时呢第三个调用方如果返回了非法结构呢这种穷举能力恰好是人在高负荷工作时最容易被削减的部分。1.2 一个典型场景AI 补位后的差距我这段时间给人做代码评审发现同一套业务纯手写和 AI 补位后的差距特别明显。纯手写的版本接口只定义了成功路径。异常处理里只有一个except Exception: return error日志里什么都查不到。而让 AI 补过一轮的版本不仅把接口分了层还针对数据库连接、第三方调用、参数校验各写了独立异常分支日志里打的上下文信息可以直接用来定位问题。有个做支付的兄弟跟我讲他们团队切到 AI 辅助之后线上 bug 量没降多少但排查时间平均降了大概百分之四五十。原因特别简单AI 被要求在每个异常分支里输出结构化上下文日志维度齐全了告警就能直接跳转到问题点不用再靠猜。这就是我说这是 AI 的最佳切点的原因——接口设计和异常处理都是低创造性、高确定性的工程活恰好是 AI 最擅长补位的地方。2. 素材准备给 AI 一份能开工的业务上下文很多人用 AI 觉得不够聪明其实是上下文没喂够。你想让 AI 补接口设计和异常处理先得让它知道你面对的是什么规模的系统、什么风格的团队、什么约束条件。我建议你把下面几块信息提前整理好存在一个context.md里每次对话直接丢进去。2.1 必须提供的四类上下文信息其实就四类项目背景、技术栈、约束条件、已有的同类接口规范。项目背景这个模块是做什么的服务的用户是谁峰值流量大概多少。AI 知道这些之后对接口设计的权衡才会有方向。给内部管理系统做的接口和给 C 端开放平台做的接口复杂度和严谨度不是一个量级。技术栈框架、版本、ORM、序列化方案。不同技术栈的最佳实践差异很大Spring Boot 和 FastAPI 的异常处理机制从理念上就不同AI 需要知道这些才能给出贴合的建议。约束条件包括团队规范、部署方式、安全要求。比如你们规定所有写操作必须走 POST接口必须加X-Request-Id链路追踪这些必须要显式告诉 AI否则它可能会按照通用规范建议你上 RESTful 的全套设计。已有接口规范这是最容易被忽略的。如果你过往的接口返回格式是{code, message, data}但 AI 不知道它可能会给你设计一个{status, msg, result}。回头还得手动改浪费时间。把过往一个典型的接口定义贴在上下文里AI 生成的代码风格会立刻对齐团队规范。提示上下文不是越详细越好。AI 的注意力窗口有限信息密度过大会稀释关键约束。我的经验是把核心约束压缩成清单格式每条不超过一行效果最好。2.2 我在团队里落地的一套 context.md 模板直接上模板你可以复制后改成自己团队的# 项目上下文 ## 项目简介 - 模块用户中心 - 用途提供注册、登录、资料查询能力 - 用户规模注册用户 200 万日常 QPS 峰值 500 ## 技术栈 - 语言/框架Python 3.11 / FastAPI - ORMSQLAlchemy 2.0 - 鉴权JWT - 部署Docker K8s ## 约束条件 - 所有写操作必须考虑幂等性 - 返回结构统一为 {code: 0, msg: ok, data: ...} - 错误码 0 表示成功非 0 表示业务错误 - 所有异常路径必须记录 request_id - 外部 API 调用必须设置超时和重试上限 ## 参考接口示例已有规范 POST /api/v1/users/register 请求体{ username: ..., password: ..., email: ... } 成功响应{ code: 0, msg: ok, data: { user_id: 123 } } 失败响应{ code: 10001, msg: 用户名已存在, data: null }这个模板看起来简单但实际用起来你会发现一个明显差别加了约束和不加约束AI 生成代码的风格完全不一样。不加约束时它可能会自由发挥加了约束之后它产出的代码能直接过评审。整套模板我放在团队内部仓库里新同学上手也能直接用不需要每次重新敲一遍上下文。2.3 让 AI 先复述一遍需求这里有一个非常便宜的防呆技巧喂完上下文之后先让 AI 用自己的话复述一遍需求和约束再开始写代码。不要觉得这一步多余。AI 是会幻觉的它有概率把约束条件理解错或者干脆忽略了某一条。让它在动手前先复述一遍相当于给上下文做一次校验。如果复述漏掉了关键信息你可能需要把上下文整理得更紧凑。如果复述准确后面生成的代码质量会明显更稳。我用的提示词很简单我已经把项目上下文发给你了。请先用 200 字以内总结这个项目的技术栈和核心约束特别是接口返回格式和异常处理的硬性要求。确认无误后我们再开始具体的接口设计。这一步通常只要花十几秒钟能省掉后面大量返工。如果你发现 AI 连上下文里的关键约束都复述不出来大概率是上下文格式需要调整而不是模型的问题。然后接下来要提示你自己在等什么——它到底能输出什么你要怎么评估输出。3. 实战一让 AI 补齐接口设计上下文备好了现在进入正题。接口设计这事儿AI 能做的不只是按你的要求写代码而是先把方案A/B/C摆出来附带决策依据让你选。这一点很关键——大多数开发者把 AI 当成了高级自动补全工具只问怎么写但其实它的价值最高的时候是回答为什么这么写。3.1 用 AI 做接口设计的提示词逻辑我给团队定的提示词结构是四个部分背景、角色、任务、交付物。背景在前面的 context.md 里已经给了角色和任务其实可以合并成一句交付物一定要说得特别具体。像这样基于上面的项目上下文我要新增用户修改密码接口。请帮我完成接口设计输出包括 1. 接口路径、HTTP 方法以及选择这个方法的理由 2. 请求参数表参数名、类型、是否必填、校验规则 3. 成功响应和各类失败响应的示例 4. 需要处理的关键异常场景列表 5. 和已有 /register 接口在风格上的一致性说明 再补充一个 200 字左右的设计说明讲清楚这个接口在幂等性、防暴力破解上的考虑。你注意我说的这五条交付物前四条就是接口文档第五条是决策依据。有了第五条你才能看到 AI 的思考过程才能判断它是不是真的理解了你的业务。3.2 从生成结果看 AI 做得好的点方案罗列同一个需求让 AI 设计它一般会给你列出两到三种方案比如方案一修改密码必须携带旧密码校验走 POST/api/v1/users/password/change旧密码在请求体重传入。方案二支持忘记密码场景走验证码重置POST/api/v1/users/password/reset不需要旧密码。方案三两步操作先发验证码再提交新密码拆分两个接口。它还会给你标注各自的适用场景方案一适合用户主动改密、且能记住旧密码的情况方案二适合用户忘记密码需要自助找回的情况方案三适合安全要求较高的场景比如不允许前端直接拿到改密令牌。这个能力非常实用。你在评审的时候不需要自己脑补所有可能的方案直接基于 AI 的清单做取舍就行。而且它给的方案通常是比较主流的做法不至于给你扯一个冷门的野路子除非你让它充分发挥。3.3 从生成结果看 AI 做得好的点异常场景枚举接口设计里的异常场景枚举是 AI 的强项。你如果问一个开发者改密码接口要考虑哪些异常有些人会想到旧密码不对想不到以下几个用户不存在或已注销旧密码校验连续错误次数过多需要触发锁定新密码和旧密码相同有些安全规范不允许新密码在最近 N 次使用过防历史密码复用并发请求下旧密码校验通过但已被其他端修改请求体里新密码为空但被当作校验通过AI 一口气能把这类场景枚举得七七八八。我在团队里的做法是把 AI 枚举的异常场景粘贴到接口文档的异常清单章节然后再人工过一遍补几条业务特有的分支。这样出来的异常覆盖度比我以前纯靠 human review 高了一个档次。3.4 接口设计实测注册接口的案例这是我在内部系统里做过的一个真实案例。原本团队设计了一个POST /api/users/register参数直接塞了username、password、email返回就直接给用户的完整信息。我用 AI 重新设计了一遍。我给的指令是请审视这个注册接口的设计重点看三件事 1. 是否存在安全和越权风险 2. 返回的数据是否过于冗余 3. 并发注册场景下有没有竞态条件AI 的回审意见非常快几乎同一时间给了三个疑问注册接口的密码字段需要明确告诉它加密后再入库否则可能会以明文形式存进数据库。这是老生常谈但偏偏是最常见的。AI 建议显式在接口设计里注明password字段经过 BCrypt 哈希后入库不能直接存原始密码。注册成功的响应如果直接返回用户完整信息等于把user_id、created_at、email全暴露了。它建议瘦身只返回能公开的字段敏感信息留到登录后再给尽量减小攻击面。并发注册同一用户名在数据库层面可能没有唯一索引加了这个索引以后还会发生冲突。它建议接口层靠唯一索引来兜底而不是靠业务代码里的先查再插。那个批次做完之后团队把注册接口的响应体瘦身了并且补了一条数据库唯一约束。从这次开始我们定了规矩所有新增的外部接口都必须让 AI 过一遍安全和竞态检查然后再交给人审。3.5 从接口设计到文档的落地接口设计出来之后还有一步是把它变成文档。很多团队的接口文档是手写的维护成本偏高。我现在是让 AI 直接生成 OpenAPISwagger描述或者至少生成一个 Markdown 版本的接口说明。原因很简单接口文档和代码只要分家就一定会漂移。代码改了文档没改是常见的事故源头。你可以这么下指令基于上面的接口设计方案生成一份 OpenAPI 3.0 的 YAML 描述文件。要求 - 包含所有错误码的定义不要遗漏 - 请求和响应示例要和设计一致不能随便编 - 每个字段都要有描述特别是约束条件让 AI 生成这份 YAML然后丢给接口管理平台整个接口文档的维护成本会大幅下降。我见过不少团队把这个环节省掉然后线上接口和文档不一致联调的时候花了一天对接口。这个成本对比之下让 AI 生成文档几乎是零边际成本。4. 实战二让 AI 补齐异常处理接口设计是骨架异常处理是血肉。这一节我想围绕异常处理具体展开因为 90% 的 AI 辅助编程教程都在讲怎么生成正常流程讲异常处理的少之又少。4.1 应该给 AI 的异常处理指令下面是一个可以直接用的指令模板请为上面这个接口补充完整的异常处理逻辑要求 1. 覆盖参数校验异常类型错误、缺失、格式不合法 2. 覆盖业务异常资源不存在、状态非法、重复操作 3. 覆盖基础设施异常数据库连接失败、缓存超时、第三方API异常 4. 所有异常路径都必须记录结构化日志包含 request_id、用户上下文、异常堆栈 5. 需要给用户看的错误信息和需要记录到日志的详细错误信息必须分开这五条里的最后一条很多人容易忽略其实非常关键。AI 在生成异常处理时如果不说清楚它会倾向于把底层异常信息直接抛给前端。这是一个安全隐患——你永远不应该把数据库连接串、内部堆栈、第三方 API 的报错详情直接暴露给用户。这条约束必须在指令里写明AI 生成的代码才会把用户可读信息和内部诊断信息分开处理。4.2 不要让它吞异常很多初学 AI 编程的同学会让 AI 直接生成一个兜底异常处理然后 AI 给了一个全局捕获、空返回的版本。这在开发阶段跑通流程没问题但在生产环境就是个灾难。我自己的处理办法是在 AI 生成代码前明确加一条规则禁止在任何异常分支里使用空捕获except: pass或只打印堆栈而不做任何处理。每个异常分支必须说明 - 当前动作的类型 - 触发该异常分支的目的是降级、重试还是终止 - 什么时候该吞掉异常什么时候必须抛出这样 AI 就不会偷懒。它会在每个异常分支里给你写上标注帮你搞清楚这个异常在什么情况下被吞是合理的、什么情况下应该向上抛。你拿到代码之后直接检查这些标注即可补充缺失的分支即可。4.3 异常处理生成后的检查清单AI 生成异常处理代码之后不要直接复制进项目先过一遍检查清单是否有全局兜底异常处理器。比如 FastAPI 里的app.exception_handler(Exception)Spring 里的RestControllerAdvice。没有全局兜底漏网的异常会导致返回给用户一个默认的 500 页面或空响应。业务异常有没有统一错误码。我见过 AI 生成的代码里同一个业务错误在不同接口下用了不同的错误码这在联调的时候会造成混乱。日志里有没有足够上下文。异常日志至少应该包含 request_id、操作人、操作目标、失败原因。如果只有异常堆栈排查问题的时候可能无从下手。第三方调用有没有超时控制。AI 生成调用外部服务的代码时往往默认不写超时参数。让它补上连接超时和读取超时设成合理的值。这个清单我每次都让 AI 自己对照一遍然后再人工确认。不要完全信任 AI 的自查——它可能会顺着你说没问题但你拿着清单一条一条问它细节总能有发现。4.4 一个踩过的坑全局异常处理器里吞了不该吞的说一个我实际踩过的坑。之前让 AI 帮我写一个全局异常处理器它的初始版本是这样的app.exception_handler(Exception) async def global_exception_handler(request, exc): logger.error(funhandled error: {exc}) return JSONResponse(status_code500, content{code: 50000, msg: 服务器开小差了})这段代码对外表现没什么问题但它把所有异常都兜走了包括ProgrammingError、ConnectionRefusedError这类基础设施异常。这些异常应该被单独处理触发告警和重试机制而不是被当作普通 500 返回。我后来在指令里加了一条基础设施异常单独分类并且让它显式定义了一个中间件来区分业务异常和基础设施异常用户可感知的业务异常统一走 ExceptionHandler返回可读的 code 和 msg 基础设施异常数据库连接丢失、缓存不可用、上游超时必须单独捕获走告警通道并把原始异常记录到指标系统。改完之后全局异常处理器终于不再背锅了。这其实也和 AI 本身的训练数据有关——训练数据里好的全局异常处理器本来就不算特别多很多项目根本没写这部分AI 容易按最低标准生成。你必须把要求提上去它才给你高标准的产出。4.5 异常处理的分级思路补充一个我觉得很实用的思路异常处理分层级。让 AI 按照可降级可重试必须终止三个等级对异常分类然后分别用不同的策略处理。可降级比如推荐服务挂了可以返回一个默认推荐列表不影响主流程。记录降级日志。可重试比如数据库连接偶发超时可以采用指数退避重试。设定重试次数上限上限满之后再抛错。必须终止比如参数逻辑错误、权限不足、余额不足这些重试没有意义直接返回失败并记录上下文。这个分类思想我让 AI 在每个异常分支的注释里标注属于哪一类。上线之后处理线上问题分级标签一眼就能看出来。比一锅炖的return error要清晰很多。5. 实测验证AI 补出的代码不能直接上生产AI 生成的东西再好也不能直接当成生产代码。这一节说说怎么验证、怎么兜底。这也是网上很多 AI 编程教程不太会讲的部分。5.1 让 AI 自测不如人测让 AI 给自己生成的代码写测试天然有一个盲区它会下意识回避自己可能出错的地方。模型更倾向于生成和自己产出兼容的测试而不是找自己的 bug。所以我的建议是让 AI 写测试然后人审测试用例。你要拿到具体的测试用例清单检查它是不是覆盖了正常路径、边界路径和异常路径三级。指令可以这么下请为上面生成的接口和异常处理逻辑编写单元测试用例。要求 1. 覆盖正常路径、参数边界路径、异常路径 2. 至少有一个用例验证基础设施异常被正确转化为业务可读的错误 3. 使用 pytest 编写使用临时数据库或 Mock不允许污染开发库 4. 标注每个用例断言的关键行为而不是只写断言值AI 生成测试用例之后你重点要看第三条。AI 有时会生成直接连数据库的伪单元测试根本没走 Mock跑一次测试就给开发库写一堆脏数据。我在团队里专门加了个检查项测试代码不允许出现真实连接串。这能避免很多悲剧。5.2 让 AI 协助做 Code Review有了初步实现和测试下一步可以让 AI 扮演资深开发角色审一遍代码。这是我现在每天都在用的姿势非常好使请以资深后端开发的身份审查上面生成的接口实现和异常处理代码重点检查 1. 接口的输入校验是否完整有没有漏掉边界条件 2. 异常处理是否遗漏了某些失败场景 3. 代码里有没有隐藏的竞态条件或安全问题SQL注入、越权、敏感数据泄露 4. 日志记录是否足够排障有没有记录不必要的数据违反合规 5. 性能上有没有明显可以优化的地方AI 输出的审查意见可能有几条是常识性废话但也总有几条是我没注意的。只要你多问几轮它能帮你发现很多问题。有时候我问完这五个问题它甚至会主动接一句另外你的参数校验在 X 场景下会报 500 而不是 400这种反馈能让你在代码评审的时候更有的放矢。5.3 人机分工什么该让 AI 干什么必须自己拍板我反复跟团队强调一句话AI 能做的是补全不是决策。接口设计里的用方案一还是方案三这种业务决策AI 给不了最终答案。异常处理里的这笔订单失败后应该退款还是冻结AI 也拍不了板。它只能帮你把每条路线的利弊写清楚帮你把选项放在桌子上。最终的决策还是要基于你对自己业务的理解来做。这个边界如果不清楚团队容易走进一个误区把 AI 的答案当标准答案。AI 给了一个方案就直接照做。结果是业务逻辑和代码实现都跑偏了还怪 AI 不好用。其实不是 AI 不好用是你把职责交错了。我个人的分工是AI 负责产出候选方案、枚举边界条件、生成完整代码骨架、写测试用例人负责选型、拍板约束、审代码、定兜底策略。AI 是提效工具不是决策者更不是替罪羊。6. 边界、成本和最后的经验写到这里还得再讲一个容易被忽略的现实问题AI 补接口和异常处理不是零成本的。每一轮对话、每次生成校对都消耗时间和注意力。你得知道什么时候该停下来不要陷入无限优化的循环——接口设计得再严谨如果业务只有内部两个系统对接那过度设计就是纯浪费异常处理铺得再全如果场景规模很小、数据一致性要求不高那复杂的分级策略反而会成为维护负担。6.1 什么时候 AI 的补全是不必要的以下这些场景AI 补得再多也意义不大一次性脚本。跑完就扔的脚本接口设计完全没必要标准化异常处理做好主路径的外部依赖保护就足够了。纯内部调用且调用方确定的接口。如果只有一个内部系统调用且是可信环境接口设计和异常处理的繁杂程度可以大幅降低。原型验证阶段。这个阶段最重要的验证业务逻辑是否成立接口骨架和异常覆盖后面可以重构没必要在原型阶段花太多成本。没有日志系统的项目。异常处理设计得再完善日志没有任何采集和分析通道那异常处理的意义基本停留在代码层面没法发挥排除线上问题的价值。这里值得格外提醒——先把基础监控和日志链路搭好再谈异常处理的精细化。6.2 成本控制别陷入无限优化循环AI 辅助有个隐性成本它太容易生成内容了导致你总想着再多问一轮再优化一下。这在接口设计和异常处理上其实非常危险因为这两个环节根本没有绝对完善的状态。你问 AI还有没有遗漏的异常它总能再给你编出三个场景但有些场景在实际业务里出现的概率几乎为零。我的做法是给每个接口设定一个设计预算接口设计的迭代不超过三轮异常处理的补充不超过两轮。三轮之后如果还没满意说明问题不在 AI 的产出质量而在需求本身还没想清楚。这时候应该回去找业务方对需求而不是继续压榨 AI。6.3 个人的一点体会踩过这些坑之后我最大的感受是用 AI 做接口设计和异常处理本质上是把你的工程经验显性化。你越能把自己的业务约束、团队规范、踩坑记录清晰地表达给 AIAI 的产出就越贴近你想要的。反过来你对这些环节的经验越模糊AI 的产出就越平庸。AI 不是魔术师它是你经验的放大器——好的经验放大成好的代码模糊的经验放大成模糊的代码。如果你正在开始用 AI 辅助写接口我建议拿一个内部小项目先练手把前面说的 context.md 建好把方案列举 异常枚举 自测清单这个流程跑两遍。等你熟悉了这套协作方式再往核心系统推。第二个小项目能做到什么程度很大程度上取决于你的工程表达能力和对边界的判断而不是模型的版本号。