用AI补齐接口设计与异常处理：FastAPI项目实战

1. 这个项目到底在解决什么问题

先说一件我自己经历过的尴尬事。之前接手一个内部数据同步服务，接口文档几乎没有，异常处理全靠调用方自己try-catch，然后调用方又把异常吞掉，只打一行log。线上出了故障，排查了三个小时，最后发现是上游接口返回了一个意料之外的字段类型，直接把下游整个链路打崩了。那种感觉就像你辛辛苦苦把一栋楼盖起来了，结果楼里的水管、电线全部乱接，最后漏水跳闸，你还得拿着手电筒一层层去翻。

这个“小项目实战 2”的标题，本质上是想解决两件事：接口设计和异常处理。这两个东西在项目里看起来是“边角料”，实际上它们是整个系统能不能抗住真实流量、真实业务复杂度的地基。接口设计没做好，前后端联调就是互相甩锅现场；异常处理没做好，线上故障定位就是一场灾难。

为什么这事儿要交给AI来“补齐”？因为接口设计和异常处理在很多项目里属于“意识问题”而不是“能力问题”——不是不会写，是没想过要写，或者不知道哪里该写、怎么写才算到位。AI在这里起到的作用，是帮你把那些“默认应该有人做但经常没人做”的事情补上，相当于一个永远在线的代码评审搭档，专门盯着你代码里最容易偷懒的部分。

这个内容适合谁来参考？两大类人。第一类是刚工作一两年的后端开发，你写业务功能可能已经很顺手了，但让你独立设计一个接口，或者系统性地做异常处理，你可能会卡壳。第二类是那些“一个人就是一支队伍”的全栈开发者、独立开发者，你一个人同时写前端、后端、数据库、部署脚本，项目代码能跑通已经很不容易了，但要让代码达到“抗造”的标准，就需要有人帮你查漏补缺。

做个明确区分：AI不是来替你做设计的，AI是来给你铺一条更靠谱的设计思路。真正动手写代码的是你，真正做技术决策的也是你，AI负责在“你没想到”的那些角落，给你递一块补丁。

2. 整体设计思路拆解：为什么接口设计和异常处理是“一对活宝”

2.1 接口设计：你先要有一个“契约思维”

接口设计最核心的问题不是“用什么框架写接口”，而是“接口的契约到底怎么定”。现实中常见的接口设计方式，基本是“写代码的人顺手定义返回结构”，比如一个用户查询接口，有人返回{ "code": 0, "data": { "user_info": {...} } }，有人返回{ "status": "success", "result": {...} }，还有人直接就把数据库的字段原样抛出去了。前端调用方根本没法统一处理。

接口设计的关键词是“稳定”和“可预期”。一个合格的后端接口，需要对外承诺三件事：请求参数怎么传，返回数据长什么样，出错的时候外面能拿到什么信息。这三件事一旦定下来了，契约就建立了，前后端才能各自干活。这种契约思维的养成，恰恰是AI能帮你拆解的地方——你只需要把接口的功能描述清楚，AI就能帮你把请求、响应、错误码的结构化设计草稿列出来，你再按照项目实际情况调整。

我实际用下来的体感是：AI给接口设计做“骨架”是非常擅长的，但AI不擅长帮你做业务取舍。比如一个接口该不该加权限校验、字段要不要脱敏、分页上限设多少，这些要靠你对业务的理解去拍板。

2.2 异常处理：AI帮你找到“你根本没想过的崩溃点”

异常处理的本质，是回答一个问题：**当事情不像预期那样发展时，你的系统会变成什么状态。**很多开发者的代码默认“事情会按照预期发展”，所以一旦出现超时、网络抖动、数据倾斜、非法参数，系统就以一种很难看的方式崩溃。

AI在异常处理上能发挥的作用，不是帮你写几个try-catch，而是帮你“穷举异常场景”。你把一个函数的输入、输出、操作步骤描述给它，它能把各种边界情况、依赖服务的失败模式、数据异常、并发问题等全部列出来，然后你再针对这些场景一个个补齐处理逻辑。这个“穷举异常场景”的动作看起来简单，但恰恰是很多人写代码时最欠缺的——因为人脑一次只能装下有限的复杂度，而AI不会漏项。

接口设计和异常处理之所以要放在一起做，是因为它们天然是配套的。接口设计里面得有出错返回的设计，异常处理里面得知道接口的却是怎么暴露错误的。你只做接口设计不做异常处理，前端根本不知道什么时候该弹窗什么时候该重试；你只做异常处理不梳理接口契约，错误码东一个西一个，日志全是乱写的。

2.3 这个系列项目的推进节奏

既然是“小项目实战 2”，说明前面还有“小项目实战 1”，大概率是做基础功能开发，比如搭了个服务的骨架、跑通了主流程。到了这一篇，任务就变成了“给已经能跑的代码做加固”。

我建议的整体节奏是这样：先梳理现有的接口清单，找出哪些接口是“裸奔”的——没有定义统一返回结构、没有错误码、没有参数校验；然后把异常处理的骨架搭好，包括全局异常拦截、错误码枚举、日志记录规范；最后用AI做一轮“找茬”，让它以代码评审的视角看一遍你的接口和异常处理代码，看哪里还有漏洞。

3. 实操过程与核心环节实现：怎么用AI补齐接口设计和异常处理

3.1 场景假设：先承认我的项目是个什么状态

为了把这件事讲清楚，我假设一个具体的项目背景：我用FastAPI写了一个简单的“用户笔记管理系统”后端，已经有了几个接口，比如创建笔记、查询笔记列表、获取笔记详情、删除笔记。代码能跑通，数据库用的是SQLite，认证用的是最简单的API Key。

这个项目“能跑通”是真的，但“能上线”是假的。我复盘了一下典型问题：

• 接口返回结构不统一，有的直接返回数据，有的包了一层{"msg": "success"}
• 没有全局异常处理，数据库操作异常直接返回500，前端拿到的是一段HTML
• 参数校验全靠手写if-else，而且校验逻辑不完整，比如title字段忘了校验长度
• 错误信息没有日志记录，出了问题根本不知道谁在什么时候调用了什么接口

这就是典型的“能用但没法维护”的状态。如果直接把这种代码交付出去，试用一两天可能没事，一旦开始接真实前端，联调阶段就会陷入混乱。

3.2 第一步：用AI梳理现状接口清单，确定契约骨架

我没有上来就让AI生成一大堆新代码，而是先让它帮我“盘点资产”。我写了一段描述：

我有一个FastAPI项目，文件结构是main.py（包含路由和启动逻辑）、models.py（SQLAlchemy模型）、schemas.py（Pydantic模型）。现在有4个接口：创建笔记、查询笔记列表、获取笔记详情、删除笔记。请帮我梳理每个接口的请求参数、返回数据结构、潜在异常场景。

AI输出了一张结构化表，里面把每个接口的请求方式、路径、参数格式列了出来，然后补充了每个接口可能的异常场景。这一轮的价值在于：把“我脑子里的接口”变成了“纸面上的接口契约”，后面所有的改进都基于这个清单来推进。

然后我再让它进一步输出“建议的返回结构设计”，它给了一个推荐方案：统一返回{"code": 0, "message": "success", "data": {...}}，其中code=0表示成功，非0表示业务错误码。这个方案很常规，但我实际采用了。注意，这里并没有涉及任何配置或第三方服务，纯粹是代码层面的规范统一。

这一步的实操要点是：把AI的输出当成初稿，而不是终稿。因为AI会根据你给的描述推测接口语义，如果你的接口文档描述不够准确，它推测出来的设计就会偏离实际。我给AI描述接口时，尽量写清楚“这个接口是给谁用的”“它期望的输入是什么”“它应该返回什么给调用方”。

3.3 第二步：用AI生成异常处理框架，建立全局兜底机制

异常处理在FastAPI里的核心是中间件和异常处理器。我之前最头疼的一点是：业务代码和异常处理逻辑混在一起，每个接口都要手动try-except，写出来的代码很臃肿。AI帮我做的一件事是：把所有异常处理收敛到一个地方。

我让AI帮我生成一个全局异常处理器，覆盖以下几类：

• HTTPException：FastAPI自带的路由异常
• RequestValidationError：参数校验失败时触发
• SQLAlchemyError：数据库层面异常（类型是数据库错误，属于ORM层，不是网络安全问题）
• 兜底Exception：以上都没覆盖到的未知异常

AI生成的代码大约四十行，核心逻辑是：每个异常处理器捕获异常后，统一记录日志、返回标准错误结构。我对它做了一些调整：最终返回的字段名统一为code、message、data，错误日志里强制带上请求路径和请求参数。

这是最关键的一步调试细节：日志里必须带上下文。因为一旦线上出现异常，没有请求路径和参数的日志就是在裸奔。我让AI在处理函数里增加request: Request参数，然后在日志里格式化输出了request.method和request.url。

注意：全局异常处理的粒度要控制好，不是所有异常都应该被吞掉然后返回一个友好消息。那些属于系统级故障的（比如数据库连接断开），应该记录完整的异常堆栈；而那些业务参数错误，只需要返回一个明确的错误码即可。

这一步做完之后，我把接口里的try-except全部删掉了，业务代码变得非常干净。接口只需要关心“正常逻辑怎么写”，异常处理全部交给全局拦截器。这个模式就是“集中式异常处理”，对付中小型项目很够用，而且代码看起来舒服很多。

3.4 第三步：用AI逐个补齐接口的参数校验和错误码

这一步是“补全”的核心。有了全局异常处理和统一返回结构，接下来就是给每个接口加上参数校验和明确的错误码。我的操作方式是：把需要做的接口清单发给AI，让它针对每个接口生成“校验清单 + 错误码表格”。

比如创建笔记接口，AI给出的建议是：

• title必须是非空字符串，长度在1到100之间
• content可以是空字符串，但不能为None，长度上限20000
• tag可选，若提供必须是字符串列表，列表长度不超过5
• 当参数校验失败时，返回code=1001，message里注明具体是哪个字段出错

这里要补一个背景说明：参数校验在FastAPI里有Pydantic这个既有的校验机制，所以不需要手动写一堆if-else。我让AI把Pydantic模型重新生成了一遍，加上了字段约束，然后路由函数里直接声明payload: CreateNotePayload即可。校验失败的异常由RequestValidationError处理器统一接管。

错误码设计这一块，AI给了一套结构，我又自己调整了一下，按“模块”做了分区：

这个分区的价值在于：调用方（特别是前端）可以通过错误码范围快速判断错误属于什么类别，然后决定是提示用户修改输入、还是直接隐藏加载状态、还是弹一个“系统繁忙”。如果没有这种分区，前端就只能对着错误信息文本做字符串匹配，那体验就太糟糕了。

3.5 第四步：用AI模拟“故意搞破坏”来补漏

这是我觉得最有价值的一个环节。代码改完之后，我没有直接上线，而是让AI扮演一个“恶意调用方”，故意用各种刁钻的方式调用接口，然后看系统是否能够正确响应。我把项目代码的关键部分贴给它，让它帮我列出可能的攻击面（指异常情况逻辑，不是网络安全测试的范畴），比如：

• 传入超长字符串
• 请求一个不存在的笔记ID
• 删除一个已经被删除的笔记
• 缺失必填参数
• 传入负数分页页码
• 请求体格式正确但字段类型错误

AI列出的测试场景帮我发现了两个此前漏掉的bug：

第一个是“删除一个不存在的笔记”时，我的代码返回的是404，但错误码被全局异常处理器改成了9000（系统错误）。前端看到9000会以为系统挂了，实际上这只是业务逻辑错误。修复方式：在路由里捕获业务异常，转换为code=2002并返回明确消息。

第二个是分页查询接口，当page传一个很大的数字时，偏移量计算会溢出。AI提示我应该对分页参数做上限限制，比如单次查询最多返回100条、页码最大10000。我又让AI帮我生成了对应的校验逻辑。

这一步的实际体验是：AI模拟异常调用的时候，比我手动测试覆盖到的场景多得多。我自己测试的时候大概率只会测“正常请求”和“简单错误”，而AI会把那些“你觉得不会有人这么调用但实际上真的会有人这么调用”的场景全部翻出来。

这里有个操作技巧值得分享：不要一次性把整个项目代码全贴给AI，而是按接口逐个贴。一次性给太多代码，AI反而抓不住重点，生成的测试场景会非常泛泛。我按接口拆开，一个接口一个接口地让它找茬，测试建议的质量高很多。

4. 工具选型与提示词技巧：怎么让AI真正帮你干活

4.1 AI工具的差异化选择

我现在的实操环境里，几种AI工具是混着用的：

• IDE内AI插件（比如GitHub Copilot、通义灵码、Fitten Code等）：适合编码过程中的实时补全，缺点是“主动性太强”——你要什么它给什么，但你根本不知道要什么的时候，它不会主动帮你发现盲区
• 在线大模型对话（ChatGPT、Claude、通义千问或国内其他大模型平台）：适合做方案讨论、架构梳理、测试场景穷举
• 本地大模型（如果有条件部署的话）：适合对数据隐私有要求的场景，但对代码生成质量通常不如在线大模型

对这个项目的需求来说，真正的主力是“在线大模型对话”。因为“补齐接口设计和异常处理”这个任务需要的是宏观审视、场景穷举、代码生成，不是逐行的语法补全。而IDE插件适合在明确“我要写一个函数”的时候用，不太适合帮你想“哪里还需要一个函数”。

4.2 一套好用的提示词模板

我整理了几个实际用过的提示词模板，直接复制就能用。这些模板的设计原则是：给足上下文、明确输出格式、要求它先列思路再写代码。

接口梳理提示词：

我现在在某项目中有以下接口：xxx。请输出一张表格，包含每个接口的请求方式、路径、请求参数、返回字段、潜在异常场景。表格之外不要写多余的内容。

异常场景穷举提示词：

下面是我某个接口的实现代码：[粘贴代码]。请从调用方的视角，列出20个可能的异常调用场景或失败场景。不要给出解决方案，只需要场景清单，按严重程度排序。

代码评审提示词：

请对我下面的接口代码做一次代码评审，只关注接口契约一致性、异常处理完整性、参数校验全面性这三个方面。输出三个清单：问题清单、建议修改清单、优先级排序。

错误码设计提示词：

我的项目包含以下业务模块：xxx。请帮我设计一套错误码枚举结构，要求：按模块分区、每个错误码有明确说明、预留扩展空间。输出为表格。

我特别想强调一下“只要场景清单不要方案”这个tips。如果你让AI既列场景又给方案，它的注意力会被分散，方案写得很潦草，场景也没穷举完整。先让它穷举场景，然后你再挑出其中需要补处理的，二次对话让它给方案。分两轮走，质量明显高一个档次。

4.3 一个容易被忽略的点：AI需要“业务认知”

AI做接口设计和异常处理时有一个天然短板：它不了解你的业务背景。同样是“删除笔记”，如果AI不知道这个笔记系统是个人用的还是团队协作的、删除是物理删除还是逻辑删除，它就很容易给出和你预期不符的设计。

所以我的做法是：在让AI输出接口设计方案之前，先给它一段“业务上下文描述”，内容包括：这个项目的使用者是谁、核心业务流程是什么、哪些操作是高风险的、哪些操作是低价值的。这段描述不需要很长，三五行就行，但能让AI的输出质量提升很多。

举个实际例子：我告诉AI“这个笔记系统支持多用户，用户只能删自己的笔记”，它就会在接口设计里面自动加上鉴权校验逻辑的提示。如果我不说，它可能会默认谁能删谁不能删都没关系，那设计就漏掉了一块。

5. 实际踩过的坑与排查记录

5.1 坑一：全局异常处理器把业务异常吞成了系统异常

这个我在前面顺带提了一下，但值得展开说。我最初让AI写全局异常处理器，它给了一个很“标准”的写法：捕获所有异常，返回500和兜底消息。但实际跑起来之后发现，业务逻辑里主动抛出的ValueError、KeyError也被拦截成了系统错误，前端一律认为服务器挂了。

这个问题怎么排查的？我直接看测试结果：删除一个不存在的笔记时，前端收到了一个code=9000。随后我从日志里找线索，发现全局异常处理器在Exception分支里接了所有异常。修复方案分两层：业务逻辑里抛异常时，统一抛自定义的BizException，并携带错误码和消息；全局异常处理器里，优先处理BizException，把它转换为对应的业务错误响应。

这个模式其实就是Java里很常见的“自定义业务异常 + 全局拦截器”思路，在Python里同样适用。建议所有小项目都提前把这层做上，不要等到业务代码写了几千行再回头改。

5.2 坑二：AI生成的Pydantic校验规则太严

AI生成校验规则时倾向于“过度校验”。比如我给它的描述是“title是笔记标题”，它就默认加上min_length=1，这没问题；但它还会加max_length=50这种假设，而我的业务里标题明明可以更长。如果直接采用AI生成的模型，真实用户传一个80字符的标题就会被拒绝，而且报错信息还不明白。

排查这个问题的线索很简单：我用一个80字符的标题测试创建笔记，发现返回了参数校验错误。然后我就去翻AI生成的Pydantic模型，果然发现它自己设了一个max_length=50。修复方式：把所有AI生成的硬编码校验上限删掉，只在“确有业务必要”的地方加限制。

这里有个实用建议：AI生成校验规则后，你要全部检查一遍，保留必要的、删掉多余的。校验的目的是防止垃圾数据入库，不是为了限制正常用户的合理操作。

5.3 坑三：日志记录信息不足，问题定位还得靠猜

最开始AI给我的全局异常处理器只记录了异常本身，没有记录请求信息。后来我在调试过程中发现，日志里只有一行Exception: xxx，根本不知道是哪个接口、哪个人、传了什么参数触发的问题。这种日志的价值极低。

修复方式很简单：异常处理函数里增加请求上下文记录，把method、url、query_params、body、用户ID（如果有认证）全部写到日志里。我用的是Python标准库的logging模块，加了格式化输出。这样之后再出问题，日志里一条链路信息全齐了。

5.4 坑四：AI给出错误码设计后，我没做“变更成本评估”

AI给的错误码分区方案很好，但忽略了一个现实约束：项目里已有的前端代码只认两种状态：成功和失败。如果直接把新错误码体系推到线上，前端需要同步改逻辑，联调成本不低。

我的处理方式是：在引入新错误码体系时，保留一个“兼容模式”——code=0还是成功，非0还是失败，前端只要判断code===0就能正常工作。新错误码提供的细分信息是可选的，前端后续再逐步接入。这个渐进式替换的策略，避免了同一时间前后端同时大改的风险。

6. 实操中的人机协作边界：哪些事该交给AI，哪些事必须自己拍板

这是我在这个项目里耗费比较多时间想清楚的一件事。AI工具能帮的忙非常多：写代码、列场景、设计错误码结构、生成测试用例，但我确实遇到了很多“AI替代不了”的环节。

第一，接口的语义边界必须由业务方定义。比如“获取笔记详情”这个接口，到底要不要返回笔记的评论数？AI不知道你的前端页面长什么样，不知道哪些信息在列表页已经展示过，它只能根据“详情”这个词做推断。这个决定只能由真正知道产品形态的人来做。

第二，错误信息要不要暴露给最终用户，必须由产品定位决定。个人开发者的工具类产品，错误信息可以稍微技术化一些，用户可能就是懂技术的同行；面向普通用户的产品，错误信息必须是人话，“数据库连接失败”这种原文不能直接展示给用户，你要做的处理是“系统繁忙，请稍后再试”。这个取舍AI做不了。

第三，策略性判断必须自己来。比如某个接口到底要不要做幂等设计，AI会告诉你“建议做”，但它的建议是基于通用最佳实践，而不是基于你项目的真实调用频率和复杂度。如果你的项目是内部工具，一天调用量几百次，那做幂等的收益很低，不如把时间花在更有价值的事情上。AI给的建议是“参考值”，不是“指令”。

这不是说AI没用，而是说要给AI设定正确的预期：它负责解决“怎么做”的问题，而“做什么”和“为什么做”的决策权始终在你手里。这种协作模式下，AI能帮你节约大量机械性工作，但你不会因此失去对项目的掌控力。

7. 这套流程的完整执行顺序：从零到上线的可复用模板

到现在为止，我把每一步都拆开了讲，最后我再整合一下，形成一套可以复用的完整流程。你下次接到一个新项目或者要重构一个老项目的时候，可以严格按照这个顺序走一遍。

第一轮：梳理现状。把项目里所有接口列出来，标注每个接口的输入、输出、依赖、异常场景。这一步用清单式提示词让AI帮你整理。

第二轮：制定规范。确定统一返回结构、错误码分区方案、日志记录规范。这一步一定要自己画决策边界，AI生成的规范草稿只做参考。

第三轮：补齐骨架。写全局异常处理器，把参数校验、业务异常、系统异常三条链路分开。这一步AI能帮忙生成大部分代码，但你得逐行过一遍。

第四轮：逐个接口加固。按照接口清单，逐个补参数校验、补业务异常断言、补错误码。这一步是体力活，AI能快速生成，你也得快速检查。

第五轮：AI找茬。把单个接口的代码发给AI，让它按照调用方的视角穷举异常场景。选其中值得处理的场景，补齐处理逻辑。

第六轮：回归测试。跑一遍正常路径、异常路径、边界值测试，确认全链路符合预期。这一步AI也能帮忙生成测试用例，但执行测试和判断结果得自己来。

这套流程前前后后加起来，差不多一两天时间就能走完。投入产出比非常值得，因为你换来的是一套“抗造”的接口层，后续开发新功能的时候，不需要回头再补这些基础建设。

我在实际做这个项目时最深的体会是：真正的问题从来不是“不会写接口”或者“不会处理异常”，而是“意识不到哪里需要处理、哪里需要设计”。AI在这里的最大价值，不是替代思考，而是强迫你把这些角落看一遍。它就像一个经验丰富的同事，坐在你旁边，你在写代码的时候它时不时来一句“这里是不是漏了？”不过这个“同事”从来不烦躁，你问多少遍它都愿意帮你列，这就很值得。