接口设计这件事很多人觉得是架构师才需要操心的活儿写业务代码的时候随手定义几个字段、返回个 200 就完事了。但真正做过线上项目的人都知道接口设计不到位、异常处理没跟上后期排查问题的时间成本能占到整个开发周期的四成以上。我最近在做一个中小型项目的时候尝试换了个思路——把接口设计和异常处理的初稿交给 AI 来补全自己只负责审核和调整。实测下来这个做法在效率上的提升非常明显但前提是你得知道怎么给 AI 下指令、怎么判断它给的东西能不能用。这篇内容就是把这套流程完整拆开从为什么要让 AI 介入、怎么设计提示词、生成结果怎么验证、到最终落地时踩过的坑全部讲清楚。适合有一定开发基础、正在做中小型项目、想让 AI 真正帮上忙而不是帮倒忙的开发者参考。1. 为什么接口设计和异常处理值得交给 AI 打初稿1.1 这两件事的共同特点模式化程度高但细节繁琐接口设计和异常处理有一个非常明显的共性——它们的核心逻辑是高度模式化的但具体到每个字段、每个状态码、每条错误信息又特别琐碎。比如一个标准的 RESTful 接口无非就是定义请求方法、路径、请求参数、响应结构、状态码这几样东西。异常处理也类似无非是捕获、分类、记录、返回。这些事情的骨架是固定的但血肉需要根据具体业务来填。人在做这类工作的时候最容易出现的问题不是不会做而是做着做着就烦了。定义到第五个接口的时候开始偷懒错误码直接复用上一个的写到第八个异常分支的时候干脆一个 catch 全兜住返回个系统错误了事。这种偷懒在当时看不出问题等上线后用户反馈操作失败但不知道什么原因的时候你回头查日志发现所有异常都长一个样那才叫绝望。AI 恰好擅长这种模式化但繁琐的工作。你给它一个清晰的接口列表和业务背景它能在几十秒内把每个接口的请求响应结构、状态码、错误信息全部补齐而且不会因为写到第十个累了就降低质量。这是我认为 AI 在这个场景下最大的价值——不是它比你聪明而是它比你耐烦。1.2 AI 补全的边界在哪里但这里必须说清楚一个前提AI 补的是初稿不是终稿。它生成的接口定义和异常处理逻辑大概能覆盖 70% 到 80% 的常规场景剩下 20% 到 30% 跟你的具体业务强相关的部分必须你自己来。举个例子你让 AI 设计一个用户下单的接口它会给你标准的参数校验、库存检查、订单创建、支付调用这些环节的异常处理。但它不知道你的业务里库存检查是同步的还是异步的不知道你的支付回调是走消息队列还是直接 HTTP 回调不知道你的订单状态机有几个状态、状态之间的流转规则是什么。这些只有你自己清楚。所以正确的用法是你把业务约束和关键流程告诉 AI让它基于这些约束去补全细节。而不是扔一句帮我设计一个下单接口就完事。前者是协作后者是甩锅结果完全不一样。1.3 什么样的项目适合这种玩法不是所有项目都适合让 AI 来补接口设计和异常处理。根据我的实际经验以下几种情况效果最好中小型项目接口数量在 10 到 50 个之间接口太少没必要自己写更快接口太多 AI 一次处理不过来需要分批。业务逻辑相对标准没有太多历史包袱如果你的项目里有大量遗留代码、特殊的兼容逻辑AI 很难理解这些上下文。团队有明确的接口规范AI 需要知道你的规范才能生成符合要求的内容如果你的团队连状态码用 200 还是 201 都没统一那先统一规范再说。你本人对业务足够熟悉这是最重要的一条。AI 生成的东西对不对你得有能力判断。如果你自己都不清楚这个接口应该怎么设计那 AI 给的你也看不懂。反过来如果你的项目是那种高度定制化、业务逻辑极其复杂、或者涉及大量遗留系统对接的AI 能帮上的忙就比较有限了。它更适合做从零开始或者推倒重来的场景。2. 给 AI 下指令的正确姿势提示词结构拆解2.1 一个完整的接口设计提示词应该包含什么我试过很多种提示词写法最后总结出一个比较稳定的结构。你给 AI 的输入应该包含以下几个部分第一项目背景和业务领域。用两三句话说明这个项目是做什么的目标用户是谁核心业务流程是什么。这部分不需要太详细但必须让 AI 建立起基本的业务认知。比如这是一个面向小型餐饮商家的库存管理工具核心流程是进货录入、库存盘点、临期预警。第二接口清单和功能描述。把你要设计的接口一个一个列出来每个接口用一句话说明它的功能。比如POST /api/inventory/purchase - 新增一条进货记录。不需要写参数AI 会根据功能描述自己推断。第三技术栈和框架约束。你用的是 Spring Boot 还是 Express 还是 FastAPI返回结构是统一包装还是直接返回数据状态码是用 HTTP 标准状态码还是自定义业务码。这些必须提前告诉 AI否则它生成的东西跟你的项目对不上。第四异常处理的特殊要求。比如你是否需要区分客户端错误和服务端错误是否需要记录详细的错误堆栈是否需要支持多语言错误信息是否有特定的错误码规范。这些约束越明确AI 生成的结果越可用。第五输出格式要求。你希望 AI 以什么形式输出是表格、JSON、还是代码我一般要求它先用表格列出所有接口的概要再逐个展开详细的请求响应结构和异常分支。这样方便我快速浏览和审核。2.2 异常处理提示词的关键差异接口设计的提示词偏描述性异常处理的提示词偏规则性。什么意思呢接口设计你只需要告诉 AI做什么异常处理你需要告诉 AI在什么情况下做什么。我在写异常处理提示词的时候会额外加上这几类信息业务异常的分类哪些是参数校验失败哪些是业务规则不满足哪些是外部依赖出错哪些是系统内部错误。每一类的处理策略是什么。错误码的编码规则比如前两位表示模块中间两位表示错误类型后两位表示具体错误。有了规则AI 生成的错误码才不会乱。日志记录的粒度什么级别的异常记 WARN什么级别记 ERROR是否需要记录请求参数和用户信息。对外暴露的信息边界哪些错误信息可以返回给前端哪些只能记在日志里。这个特别重要搞不好会泄露敏感信息。提示异常处理的提示词里一定要明确说不要把所有异常都用一个 catch 兜住否则 AI 很可能会给你生成一个全局异常处理器就完事了。你需要的是分层的、有区分的异常处理。2.3 我实际用的提示词模板下面是我在这个项目里实际用的提示词模板你可以直接参考调整项目背景这是一个面向小型餐饮商家的库存管理工具核心流程包括进货录入、库存盘点、临期预警、报表导出。技术栈是 Spring Boot 3 MyBatis Plus返回结构统一用 ResultT 包装包含 code、message、data 三个字段。 请帮我完成以下接口的设计 1. POST /api/inventory/purchase - 新增进货记录 2. GET /api/inventory/list - 分页查询库存列表 3. PUT /api/inventory/{id} - 修改库存信息 4. DELETE /api/inventory/{id} - 删除库存记录 5. GET /api/inventory/expiring - 查询临期商品 6. POST /api/inventory/check - 提交盘点结果 7. GET /api/report/export - 导出库存报表 要求 - 每个接口列出请求方法、路径、请求参数含类型和是否必填、响应结构 - 每个接口列出所有可能的异常分支包括参数校验失败、业务规则不满足、资源不存在、权限不足、外部依赖失败 - 错误码规则前两位模块码01库存02报表中间两位错误类型01参数错误02业务错误03系统错误后两位序号 - 对外返回的 message 要用户友好不要暴露技术细节 - 先用表格列出所有接口概要再逐个展开这个模板我用了大概五六个项目效果比较稳定。关键点在于业务背景简洁但完整接口清单明确约束条件具体输出格式清晰。3. AI 生成的接口设计稿里哪些能直接用哪些必须改3.1 可以直接用的部分标准 CRUD 和通用校验AI 生成的接口设计里标准 CRUD 操作的部分基本可以直接用。比如分页查询的参数pageNum、pageSize、keyword、新增操作的必填字段校验、删除操作的 ID 校验这些是行业通用模式AI 见过大量的类似案例生成的质量很高。参数校验部分也是 AI 的强项。它会自动帮你补上非空校验、长度校验、格式校验比如手机号、邮箱、范围校验比如数量不能为负数。这些如果让你自己写很容易漏掉几个。AI 生成后你过一遍把不符合业务实际的删掉就行。响应结构的设计AI 一般会遵循你给的统一包装格式。如果你没给它可能会生成一个比较通用的结构。我建议在提示词里明确给出你的 Result 类结构这样 AI 生成的响应字段名跟你的项目完全一致省去手动调整的功夫。3.2 必须人工调整的部分业务规则和状态流转AI 最不擅长的就是你的具体业务规则。比如库存数量不能超过仓库容量这条规则AI 不知道你的仓库容量是怎么算的是固定值还是动态计算是单个商品的容量还是整体容量。它可能会生成一个库存数量不能为负数的校验但更复杂的业务规则它猜不到。状态流转也是重灾区。如果你的库存记录有待审核、已入库、已出库、已盘点这些状态AI 可能会生成一个状态字段但它不知道状态之间的流转规则。比如已出库的记录不能再次修改这种规则必须你自己补上。我的做法是AI 生成初稿后我拿一支笔或者打开一个空白文档把每个接口的业务规则单独列出来然后逐条对照 AI 的生成结果看哪些规则它覆盖了、哪些没覆盖、哪些覆盖错了。这个过程大概每个接口花两三分钟但能避免后期大量的返工。3.3 异常分支的覆盖度检查方法AI 生成的异常分支覆盖度大概在 70% 左右。剩下的 30% 需要你根据实际业务来补。我总结了一个检查清单每次审核 AI 生成的异常处理时按这个清单过一遍检查项AI 通常覆盖需要人工补充参数非空校验是特殊字段的业务含义校验参数格式校验是自定义格式规则资源存在性校验是软删除资源的处理权限校验部分细粒度的数据权限业务规则校验部分复杂业务逻辑并发冲突处理很少乐观锁/悲观锁策略外部依赖失败部分降级和重试策略幂等性处理很少重复请求的识别和处理这张表里并发冲突处理和幂等性处理是 AI 最容易漏掉的两块。比如盘点提交这个接口如果两个管理员同时提交盘点结果怎么处理AI 一般不会主动考虑这个。你需要自己补上版本号校验或者分布式锁的逻辑。3.4 错误码和错误信息的审核要点AI 生成的错误码如果你给了编码规则它一般能遵守。但错误信息message部分需要仔细审核。AI 倾向于生成比较技术化的错误信息比如数据库连接失败、空指针异常这些直接返回给前端是不合适的。审核错误信息的时候我遵循两个原则用户能看懂错误信息应该是给最终用户看的不是给开发看的。比如库存数量不足当前库存 5 件请求出库 10 件就比库存校验失败好得多。不暴露技术细节不要出现数据库表名、字段名、堆栈信息、服务器 IP 这些内容。AI 有时候会生成违反唯一约束 uk_inventory_code这种信息必须改成该库存编码已存在请更换后重试。4. 异常处理的落地从 AI 初稿到可运行代码4.1 全局异常处理器的骨架搭建AI 生成的异常处理设计稿最终要落地成一个全局异常处理器。在 Spring Boot 项目里通常是一个带有 RestControllerAdvice 注解的类。这个骨架可以让 AI 帮你生成但有几个关键点需要你自己把控。首先是异常的分类。我一般把异常分成三大类业务异常BusinessException、参数异常MethodArgumentNotValidException 等、系统异常Exception。业务异常返回具体的错误码和用户友好的提示参数异常返回字段级的校验错误系统异常统一返回系统繁忙请稍后重试并记录完整日志。其次是异常的优先级。Spring Boot 的异常处理是有优先级的越具体的异常越先被匹配。所以你的 ExceptionHandler 方法要按照从具体到宽泛的顺序排列。AI 生成的时候可能会打乱这个顺序你需要手动调整。最后是日志的记录策略。不是所有异常都需要记 ERROR 级别。业务异常记 WARN 就够了参数异常记 INFO 或者不记只有系统异常才需要记 ERROR 并打印堆栈。这个策略要在提示词里明确告诉 AI否则它可能把所有异常都记成 ERROR导致日志文件迅速膨胀。4.2 业务异常类的设计细节业务异常类是整个异常处理体系的核心。AI 生成的业务异常类通常长这样public class BusinessException extends RuntimeException { private String code; private String message; public BusinessException(String code, String message) { this.code code; this.message message; } }这个结构能用但不够好。我在实际项目中会做几个增强增加错误码枚举不要让调用方直接传字符串 code而是传一个枚举值。这样能避免拼写错误也方便统一管理。增加上下文信息有时候光有错误码和消息不够还需要携带一些上下文数据。比如库存不足这个异常最好能带上当前库存数量和请求数量方便前端展示。增加异常链支持业务异常有时候是由底层异常引起的需要保留 cause 信息方便排查。增强后的业务异常类大概是这样public class BusinessException extends RuntimeException { private final ErrorCode errorCode; private final MapString, Object context; public BusinessException(ErrorCode errorCode) { super(errorCode.getMessage()); this.errorCode errorCode; this.context new HashMap(); } public BusinessException(ErrorCode errorCode, Throwable cause) { super(errorCode.getMessage(), cause); this.errorCode errorCode; this.context new HashMap(); } public BusinessException withContext(String key, Object value) { this.context.put(key, value); return this; } }这个设计让异常的使用更加灵活也更容易在全局处理器里统一处理。4.3 参数校验异常的统一处理参数校验异常是日常开发中最常见的异常类型。Spring Boot 提供了 Valid 和 Validated 注解来做参数校验校验失败会抛出 MethodArgumentNotValidException 或 ConstraintViolationException。AI 生成的全局处理器一般会覆盖这两种但细节上需要调整。关键点在于错误信息的提取。MethodArgumentNotValidException 里包含的是字段级的错误信息你需要把它们提取出来组装成一个对前端友好的结构。我一般会返回一个字段名到错误信息的映射比如{ code: 010101, message: 参数校验失败, data: { quantity: 数量不能为空, purchaseDate: 进货日期格式不正确 } }这样前端可以精确地知道哪个字段出了问题直接在对应的输入框旁边显示错误提示。4.4 系统异常的兜底与告警系统异常是最后一道防线。当所有具体的异常处理器都没匹配上时兜底的 Exception 处理器会接管。这里有几个必须做的事记录完整的请求信息包括请求路径、请求方法、请求参数、用户标识。这些信息在排查问题时至关重要。记录完整的堆栈信息用 log.error 打印异常堆栈确保日志里有足够的信息定位问题。返回统一的用户提示不要返回具体的异常信息统一返回系统繁忙请稍后重试。触发告警如果系统异常频繁出现应该有告警机制。可以接入邮件、短信或者企业内部的告警平台。AI 生成的兜底处理器通常会包含前三点但告警机制一般不会主动生成。你需要根据自己项目的实际情况补上。5. 实测中踩过的坑和应对方案5.1 AI 生成的错误码重复问题这是我在第一个项目里踩的最大的坑。AI 生成错误码的时候如果你没有给它一个全局的分配表它会在不同的接口里生成重复的错误码。比如库存模块的参数错误用了 010101报表模块的参数错误也用了 010101。上线后排查问题的时候看到 010101 根本不知道是哪个模块出的错。解决方案很简单在提示词里给 AI 一个错误码分配表明确每个模块、每种错误类型对应的码段。或者更省事的做法是让 AI 先生成所有错误码你审核一遍去重再让它基于去重后的错误码生成异常处理代码。5.2 异常信息泄露敏感数据AI 生成异常信息的时候有时候会把请求参数直接拼接到错误信息里。比如用户 13800138000 不存在这本身没问题但如果参数里包含密码、身份证号这些敏感信息直接返回给前端就出事了。我的应对方案是在全局处理器里加一层脱敏逻辑。对于已知的敏感字段password、idCard、bankCard 等在记录日志和返回信息之前先做脱敏处理。这个逻辑 AI 不会主动帮你加必须自己补上。5.3 异常处理导致的性能问题这个坑比较隐蔽。AI 生成的异常处理代码里有时候会在异常处理器里做比较重的操作比如查询数据库、调用外部接口。异常处理本身应该是轻量的如果里面做了耗时操作在高并发场景下会拖慢整个系统的响应。我的建议是异常处理器里只做日志记录和信息组装不要做任何 IO 操作。如果确实需要查询额外信息比如根据用户 ID 查用户名应该在业务代码里提前查好通过异常上下文传进来。5.4 前后端对错误码的理解不一致这个问题在前后端联调的时候最容易暴露。AI 生成的错误码和错误信息前端同学可能不理解它的含义。比如010201这个错误码前端不知道它代表什么只能根据 message 来判断但 message 有时候会变。解决方案是维护一份错误码文档前后端共同遵守。文档里明确每个错误码的含义、触发条件、前端应该如何处理是弹提示、跳转页面、还是刷新数据。这份文档可以让 AI 根据你的错误码枚举自动生成但需要人工审核一遍。6. 让 AI 持续帮你维护接口文档和异常处理6.1 接口变更时的同步更新项目迭代过程中接口变更是常态。每次变更后接口文档和异常处理代码都需要同步更新。这个过程如果全靠人工很容易遗漏。我的做法是每次接口变更后把变更内容整理成一段简短的描述发给 AI让它帮我更新接口文档和异常处理代码。比如库存查询接口新增了一个 warehouseId 参数用于按仓库筛选。请更新接口文档并补充相应的参数校验和异常处理。AI 会基于这个描述生成更新后的文档片段和代码片段。我审核后直接替换到项目里。6.2 用 AI 做异常处理的代码审查除了生成代码AI 还可以用来做代码审查。我会把写好的异常处理代码发给 AI让它帮我检查有没有遗漏的异常分支、有没有不合理的错误码、有没有敏感信息泄露的风险。AI 在这方面的表现还不错经常能发现一些我忽略的细节。不过要注意AI 的审查结果不能全信。它有时候会过度审查把一些正常的代码标记为问题。你需要自己判断哪些是真问题、哪些是误报。6.3 建立异常处理的检查清单经过几个项目的积累我整理了一份异常处理的检查清单。每次新项目上线前我都会按这个清单过一遍。清单的内容包括所有接口是否都有对应的异常处理分支错误码是否全局唯一且符合编码规则错误信息是否用户友好且不包含敏感信息系统异常是否有兜底处理和告警机制异常日志是否包含足够的排查信息前后端错误码文档是否同步更新这份清单也可以让 AI 帮你生成初稿然后你根据项目实际情况调整。有了清单之后异常处理的遗漏率明显下降。6.4 把常用提示词沉淀成模板最后一个经验是把常用的提示词沉淀成模板。我在这个项目里用的接口设计提示词、异常处理提示词、代码审查提示词都已经整理成了模板文件。下次新项目启动的时候直接复制模板改一下业务背景和接口清单就能用。这样能省去大量重复思考提示词的时间。模板不需要很复杂关键是结构清晰、约束明确。我一般会把模板分成项目背景、接口清单、技术约束、输出要求四个部分每个部分用注释标明需要替换的内容。用的时候填空就行。这套方法我在三个项目里跑过接口设计和异常处理的初稿时间从原来的两三天缩短到了半天左右而且质量更稳定不容易出现遗漏。当然AI 生成的东西永远需要人工审核但这个审核的时间成本远低于从零开始写。如果你也在做中小型项目不妨试试这个思路把 AI 当成一个不知疲倦的初级开发来用你负责把关和决策它负责填充和执行。