1. 从一个真实的小项目说起为什么接口设计和异常处理值得单独拎出来讲做过几个小项目之后你会发现一个规律功能代码写得再漂亮只要接口设计得随意、异常处理得潦草这个项目基本就活不过第二次迭代。我自己就踩过这个坑。早些年做一个内部用的数据同步小工具功能很简单就是定时从几个数据源拉数据、清洗、入库。当时想着“小项目嘛能跑就行”接口参数随手定错误处理就是一层try...except包住整个流程出错就打印一行日志。结果上线第三天上游一个字段类型变了整个任务静默失败日志里只有一句KeyError排查花了整整一个下午。那次之后我就明白了一件事接口设计和异常处理不是“大项目才需要讲究”的东西恰恰相反小项目因为人手少、没有专门的测试和运维更需要把这两块做扎实。接口设计决定了你的模块之间怎么对话、别人怎么调用你、你自己三个月后还看不看得懂异常处理决定了出问题的时候你是五分钟定位还是五小时抓瞎。这篇内容就是围绕“让 AI 帮你补齐接口设计和异常处理”这个实战主题展开的。我会把一个小项目从“能跑”到“跑得稳”的完整过程拆开讲包括接口怎么定、状态码和错误码怎么设计、异常怎么分层捕获、AI 在这个过程中具体能帮上什么忙、哪些地方 AI 给的方案不能直接抄。适合有一定编程基础、正在做或者刚做完一个小项目、想让代码质量上一个台阶的朋友。哪怕你之前没系统学过接口设计跟着走一遍也能落地。核心关键词会贯穿全文接口设计、异常处理、API、HTTP状态码、错误码。这几个词不是孤立的它们是一条链上的东西——接口设计是骨架异常处理是保险HTTP状态码和错误码是这套保险对外沟通的语言。2. 接口设计到底在设计什么先想清楚再动手2.1 接口设计的本质是“契约”不是“函数签名”很多人一提到接口设计脑子里第一反应就是“这个函数要传几个参数、返回什么类型”。这只是最表层的东西。接口的本质是一份契约调用方和被调用方之间约定好的规则。这份契约至少包含四层信息。第一层是输入约定需要哪些参数、每个参数的类型和取值范围、哪些必填哪些可选、默认值是什么。第二层是输出约定正常返回什么结构、字段含义是什么、有没有分页、时间格式统一不统一。第三层是错误约定什么情况下会失败、失败时返回什么、调用方怎么区分“参数错了”和“服务挂了”。第四层是行为约定这个接口是幂等的吗调用两次会不会产生两条数据有没有副作用我见过太多小项目的接口只做了第一层第二层勉强凑合第三层第四层完全空白。结果就是调用方只能靠“猜”和“试”一出错就抓瞎。所以让 AI 帮忙之前你自己得先知道要让它帮你补什么。我的做法是先手写一版“最小契约”把输入输出列清楚然后让 AI 基于这个骨架去补错误约定和行为约定——这部分恰恰是人最容易漏、AI 最擅长的。2.2 小项目接口设计的三个务实原则大厂那套 RESTful 规范、版本管理、HATEOAS 之类的小项目真没必要全盘照搬。我总结下来小项目接口设计守住三条线就够了。第一条命名要能自解释。别用doStuff、handleData这种名字。用fetchUserProfile、syncOrderStatus这种“动词名词”的结构一看就知道干什么。参数名同理id不如userIddata不如orderPayload。这条看着简单但它是后面所有工作的基础——名字清晰AI 补出来的错误处理才有针对性。第二条返回结构要统一。不管成功失败返回的 JSON 外壳保持一致。我习惯用这样的结构{ code: 0, message: success, data: { ... } }成功时code为 0data放业务数据失败时code为非 0message放人类可读的说明data为 null 或者放调试信息。这样调用方永远只需要判断一个code字段不用去猜这次返回的是数组还是对象还是错误字符串。第三条错误要分类不要一锅炖。参数错误、权限不足、资源不存在、服务内部错误这是四类完全不同的东西调用方的处理方式也完全不同。参数错误应该提示用户改输入权限不足应该引导登录资源不存在可能是正常的业务分支服务内部错误才需要报警。如果全都返回一个500加一句“出错了”调用方根本没法做差异化处理。2.3 让 AI 介入接口设计的最佳时机AI 不是用来替你从零设计接口的那样出来的东西往往“正确但不对味”——规范是规范但不符合你项目的实际情况。我的经验是AI 最适合在三个节点介入。第一个节点是你写完接口草稿之后。把你手写的接口定义参数、返回值、简单说明丢给 AI让它帮你检查有没有遗漏的边界情况、命名是否一致、返回结构是否统一。这一步 AI 经常能揪出你自己没注意到的坑比如“这个接口在资源不存在时返回什么没定义”。第二个节点是设计错误码体系的时候。错误码这东西人写容易写乱要么重复要么遗漏。让 AI 基于你的业务场景生成一套分类清晰的错误码表效率极高。后面会详细讲怎么让 AI 生成可用的错误码。第三个节点是写接口文档的时候。AI 把接口定义转成 Markdown 表格或者 OpenAPI 描述比手写快得多而且格式统一。提示让 AI 参与接口设计时一定要把项目的业务背景、技术栈、调用方是谁说清楚。你给的信息越具体AI 补出来的东西越贴合。只说“帮我设计一个用户接口”出来的必然是网上随处可见的模板。3. 异常处理的分层思路别让一个 try 包住全世界3.1 异常处理的核心是“分层”不是“捕获”新手写异常处理最常见的模式就是整个函数体外面套一个大tryexcept里打印日志返回错误。这种写法的问题在于你根本不知道错误是从哪一层冒出来的。是参数解析错了是数据库连不上还是业务逻辑里某个字段为空全被同一个except吞掉了。正确的思路是分层捕获、逐层处理。一个典型的请求处理流程可以分成四层参数校验层、业务逻辑层、数据访问层、外部调用层。每一层负责捕获和处理自己范围内的异常处理不了的往上抛由上层决定是转成业务错误还是系统错误。参数校验层的异常比如类型不对、必填缺失应该在进入业务逻辑之前就拦下来直接返回“参数错误”类的错误码。业务逻辑层的异常比如“订单状态不允许取消”这是业务规则应该返回明确的业务错误码。数据访问层的异常比如连接超时、唯一键冲突一部分可以重试一部分要转成系统错误。外部调用层的异常比如第三方 API 返回了非预期结果需要做超时控制和降级处理。这样分层之后每一层的try...except范围都很小职责很清晰。出问题的时候看日志里的层级标记就能快速定位。3.2 HTTP 状态码和业务错误码的分工这里有个很多人搞混的点HTTP 状态码和业务错误码是两套东西各管各的。HTTP 状态码是传输层和协议层的语言它告诉调用方“这次 HTTP 请求本身成没成功”。200 表示请求被正常处理了400 表示请求本身有问题参数格式错误等401 表示没认证403 表示没权限404 表示路径或资源不存在500 表示服务端内部错误。它是给 HTTP 客户端、网关、负载均衡这些基础设施看的。业务错误码是应用层的语言它告诉调用方“请求虽然被处理了但业务上没成功”。比如“余额不足”“库存不够”“订单已取消”这些情况下 HTTP 状态码可能还是 200但业务错误码是非 0 的。我见过两种极端。一种是所有错误都返回 200业务错误码里区分一切结果监控系统完全看不出服务健康度。另一种是滥用 HTTP 状态码把业务错误也映射成 4xx、5xx导致调用方分不清到底是网络问题还是业务问题。正确的做法是HTTP 状态码反映请求处理的技术结果业务错误码反映业务执行结果。两者配合使用。举个具体的例子。用户调用“取消订单”接口传了一个不存在的订单号。HTTP 层面请求是合法的返回 200业务层面订单不存在返回业务错误码比如40001。如果用户传的订单号格式都不对比如应该是数字却传了字母那 HTTP 层面就该返回 400因为请求本身就不合法。3.3 错误码设计的实用规范错误码设计没有绝对标准但有几条经验值得参考。用数字分段不要用字符串。数字错误码便于比较、便于日志检索、便于国际化映射。我习惯用五位数字第一位表示错误大类后面四位表示具体错误。比如1xxxx是参数类错误2xxxx是权限类3xxxx是资源类4xxxx是业务规则类5xxxx是系统类。这样一看错误码就知道大概是什么方向的问题。错误码要稳定message 可以变。错误码一旦发布就不要改因为调用方可能已经基于它写了判断逻辑。但 message 可以优化措辞、可以做多语言。所以调用方判断逻辑应该基于 code展示给用户的文案基于 message。每个错误码都要有明确的触发条件。不要设计“通用错误”这种万能码。每个码对应一种明确的场景这样排查问题的时候才能精准定位。下面这张表是我在一个项目里实际用的错误码分类可以参考错误码段类别示例典型 HTTP 状态码10000-19999参数错误10001 必填参数缺失40020000-29999认证授权20001 未登录40130000-39999资源相关30001 资源不存在40440000-49999业务规则40001 状态不允许操作20050000-59999系统错误50001 数据库连接失败500这张表的价值在于它把“HTTP 状态码”和“业务错误码”的映射关系也定下来了。调用方拿到响应先看 HTTP 状态码判断技术层面再看业务 code 判断业务层面两层信息都有。4. 让 AI 补齐接口设计和异常处理的完整实操4.1 第一步把手写草稿整理成结构化输入AI 的输出质量取决于你的输入质量。我一般会准备一份这样的草稿包含接口清单和每个接口的基本信息项目背景一个订单管理小工具Python FastAPI调用方是内部前端和定时任务。 接口1创建订单 输入userId(必填,字符串), items(必填,数组), remark(可选,字符串) 输出orderId, status, createdAt 接口2查询订单 输入orderId(必填,字符串) 输出orderId, userId, items, status, createdAt 接口3取消订单 输入orderId(必填,字符串), reason(可选,字符串) 输出orderId, status这份草稿很粗糙但信息是准的。接下来我会让 AI 做三件事补全每个接口的错误场景、生成统一的错误码表、给出异常处理的分层建议。4.2 第二步让 AI 补全错误场景我给 AI 的提示词大概是这样基于上面的接口清单帮我列出每个接口可能出现的错误场景按参数错误、权限错误、资源错误、业务规则错误、系统错误分类。每个场景说明触发条件和建议的 HTTP 状态码。AI 返回的结果通常会覆盖得比较全。比如“创建订单”接口它会列出userId 为空参数错误、userId 格式不对参数错误、items 为空数组参数错误、items 里商品不存在资源错误、用户被禁用权限错误、库存不足业务规则错误、数据库写入失败系统错误。这些场景我自己写的时候大概率会漏掉“用户被禁用”和“库存不足”这两个业务场景。但 AI 的结果不能直接抄。它有时候会过度设计比如给一个内部小工具加上“请求频率限制”这种根本用不上的错误场景。我的做法是过一遍把不符合项目实际的删掉把遗漏的补上。这一步花十分钟能省后面几个小时的调试。4.3 第三步生成错误码表并人工校准拿到错误场景清单后让 AI 生成错误码表基于上面的错误场景生成一套五位数字错误码按类别分段。输出 Markdown 表格包含错误码、类别、含义、触发条件、建议 HTTP 状态码。AI 生成的表格通常结构不错但有几个地方需要人工校准。一是错误码的粒度AI 有时候会把很细的场景都单独给一个码导致码表膨胀有时候又合并得太粗一个码对应好几种情况。我的标准是调用方需要做不同处理的场景才给独立错误码。如果两种场景调用方都是“提示用户重试”那可以共用一个码。二是 HTTP 状态码的映射AI 有时候会把业务规则错误也映射成 4xx这是不对的。业务规则错误比如库存不足HTTP 层面应该还是 200因为请求本身是合法的只是业务没成功。4.4 第四步生成异常处理代码骨架错误码表定下来之后让 AI 生成异常处理的代码骨架基于上面的错误码表用 Python 写一套异常处理骨架。要求自定义业务异常类包含 code 和 message分层捕获参数校验层、业务层、数据层分别处理统一异常处理器把异常转成标准响应结构。AI 生成的骨架大概长这样class BusinessError(Exception): def __init__(self, code: int, message: str): self.code code self.message message super().__init__(message) class ParamError(BusinessError): pass class ResourceNotFoundError(BusinessError): pass class BizRuleError(BusinessError): pass然后是一个统一异常处理器把BusinessError转成{code: ..., message: ..., data: null}的响应把未预期的异常转成50000系统错误并记录完整堆栈。这个骨架直接可用但我会做两处调整。一是加上日志分级业务异常记warning系统异常记error并带堆栈。二是加上请求上下文信息比如requestId方便串联日志。4.5 第五步用 AI 做“对抗性检查”代码写完之后我会让 AI 扮演一个“挑剔的调用方”专门找接口设计和异常处理的漏洞假设你是一个要调用这些接口的前端开发者你会对哪些地方感到困惑哪些错误场景的处理方式不明确哪些返回结构不一致这一步经常能发现意想不到的问题。比如 AI 会指出“取消订单接口在订单已经取消的情况下返回什么没定义”或者“创建订单成功但库存扣减失败时订单状态是什么”。这些问题在写代码的时候很容易忽略但上线后一定会遇到。5. 常见问题与排查技巧实录5.1 异常处理里最容易踩的五个坑坑一捕获了异常但没记录足够信息。except Exception as e: return error(str(e))这种写法日志里只有一句错误消息没有堆栈、没有请求参数、没有用户标识。出问题的时候根本没法复现。正确做法是记录完整堆栈加关键上下文。坑二用异常做流程控制。比如用try...except来判断一个 key 存不存在而不是用if key in dict。异常的开销比正常分支大得多而且可读性差。异常应该只用于“真正异常”的情况。坑三吞掉异常。except: pass是万恶之源。哪怕你暂时不知道怎么处理至少也要记一条日志。吞掉异常等于把问题埋起来早晚会以更严重的形式爆发。坑四异常信息泄露敏感数据。直接把数据库错误、文件路径、内部 IP 返回给调用方既不安全也不专业。对外返回的错误信息应该是脱敏的、面向用户的详细技术信息只记在服务端日志里。坑五错误码和 HTTP 状态码映射混乱。前面讲过这两套东西各管各的。我见过一个项目所有错误都返回 200然后业务码里既有“参数错误”又有“服务不可用”监控系统完全没法用。也见过所有错误都返回 500 的调用方根本分不清是自己传错了还是服务挂了。5.2 接口设计常见问题速查表问题现象可能原因排查方向解决建议调用方说“返回看不懂”返回结构不统一检查成功和失败的返回外壳是否一致统一为 code/message/data 结构错误信息对用户不友好直接透传了技术异常检查异常处理器是否做了脱敏对外 message 面向用户技术细节记日志分不清错误类型错误码粒度太粗检查是否所有错误共用一个码按调用方处理方式拆分错误码接口行为不明确缺少行为约定检查文档是否说明幂等性、副作用补充行为说明必要时加幂等键参数校验散落各处没有统一校验层检查校验逻辑是否混在业务代码里抽出独立校验层进入业务前完成校验5.3 我个人的几条实操心得第一错误码表要当成代码一样维护。放在版本控制里改动要走 review。我见过错误码表散落在各个文件里、互相冲突的项目维护起来是灾难。第二每个接口至少写三个测试用例一个正常路径、一个参数错误、一个业务错误。这三个用例能覆盖大部分异常处理逻辑写起来也快。AI 可以帮你生成这些用例的骨架。第三日志里一定要有 requestId。从请求进来生成一个唯一 ID贯穿整个处理链路所有日志都带上。排查问题时用 requestId 一搜整条链路清清楚楚。这个习惯在小项目里尤其重要因为小项目往往没有完善的链路追踪系统。第四AI 生成的错误码表要人工过一遍。AI 有时候会生成一些你项目里根本不会出现的错误场景也会漏掉一些你业务特有的场景。把它当草稿不要当成品。第五异常处理的代码量应该和业务代码量成正比。如果一个项目业务代码一千行异常处理只有十行那基本可以断定异常处理是不到位的。当然也不是越多越好关键是覆盖到所有关键路径。6. 把 AI 用成“结对伙伴”而不是“代码生成器”回到最开始那个数据同步工具的例子。如果当时有现在这套方法我会这么做先把接口草稿整理出来让 AI 补全错误场景和错误码表然后基于错误码表生成异常处理骨架最后让 AI 做对抗性检查。整个过程大概多花两个小时但能省下后面无数个排查问题的下午。AI 在这个流程里的角色不是“替你写代码”而是“帮你查漏补缺”。它最擅长的是穷举——把所有可能的错误场景列出来把错误码分类分好把异常处理的模板生成出来。这些工作人做起来费时费力还容易漏AI 做起来又快又全。但最终的判断和校准必须由你来做因为只有你知道项目的实际边界在哪里。接口设计和异常处理这两件事说到底是一种“防御性思维”的体现。你在写代码的时候多问一句“这里如果出错了会怎样”多定义一条“这种情况返回什么错误码”后面就少一次半夜被叫起来排查的经历。小项目资源有限更要把这种思维刻进习惯里。AI 能帮你把这种思维落地得更快更全但思维的起点还是得你自己迈出那一步。