1. 为什么接口设计和异常处理值得单独拎出来做一个小项目很多开发者写后端接口习惯是先把业务逻辑跑通接口能返回数据就算完事。至于参数校验、错误码设计、异常兜底往往是等线上出了问题才回头补。我自己早期做项目也是这个路子结果就是前端联调时反复来问“这个情况返回什么”测试提的 bug 里有一半是边界场景没处理运维半夜告警一看是某个空指针把整个请求打挂了。接口设计和异常处理这两件事单独看都不算“难”但它们是最容易被忽略、又最影响项目质量的部分。一个设计得好的接口前端拿到文档就能直接写代码不需要反复确认一套清晰的异常处理机制能让线上问题在日志里一眼定位而不是靠猜。这个实战项目的核心思路就是让 AI 来帮你把这两块补齐——不是让 AI 替你写业务逻辑而是让它帮你把那些“你知道该做但总是懒得做”的细节一次性补全。具体来说这个项目适合几类人一是刚入行不久、还没形成接口设计规范的开发者二是接手了老项目、接口风格混乱想统一的人三是想用 AI 提效但不知道怎么下手的同学。整个实战不需要复杂的框架一个普通的 Web 项目加上一个能对话的 AI 工具就够了。我会把完整的思路、提示词设计、落地步骤和踩过的坑都讲清楚你照着做就能复现。2. 接口设计的核心要素拆解与 AI 介入点2.1 一个合格接口到底要包含哪些信息在让 AI 帮忙之前得先明确“合格”的标准。我总结下来一个接口至少要说清楚这几件事请求方法、路径、请求参数含类型和是否必填、响应结构、成功和失败的判定方式、以及各种边界情况的返回。很多人写接口文档只写“成功返回什么”失败情况一笔带过这就是后面扯皮的根源。举个具体的例子。假设有个“查询用户订单列表”的接口光写GET /orders?userId1是不够的。你得说明userId 是必填还是可选如果传了不存在的 userId 返回什么分页参数默认值是多少订单为空时返回空数组还是 null这些细节不写清楚前端就得靠猜测试就得靠试。AI 在这个环节的价值是它能根据你给的业务描述快速生成一份覆盖全面的接口定义草案。你不需要从零开始想只需要在它给的草案上做增删改。这比对着空白文档发呆效率高得多。2.2 让 AI 生成接口草案的提示词怎么写提示词的质量直接决定输出质量。我试过很多种写法最后总结出一个比较稳的模板核心是给足上下文、明确输出格式、指定边界要求。你是一名资深后端工程师。请为以下业务场景设计 RESTful 接口 业务描述用户可以通过手机号查询自己的订单列表支持按时间范围筛选和分页。 要求 1. 列出所有相关接口查询列表、查询详情等 2. 每个接口说明请求方法、路径、请求参数名称/类型/是否必填/说明、响应字段 3. 明确列出所有可能的失败情况并给出对应的 HTTP 状态码和业务错误码 4. 分页参数的默认值和最大值要写清楚 5. 用表格形式输出这个提示词的关键点在于指定了角色资深后端、给了具体业务、明确了输出格式表格、强制要求覆盖失败情况。实测下来这样生成的草案基本能覆盖 80% 的场景剩下的 20% 是业务特有的逻辑需要你自己补。2.3 接口路径和命名的取舍逻辑AI 生成的路径有时候会偏“教科书”比如/api/v1/user/order/list这种层层嵌套的写法。实际项目里要不要加版本号、要不要加/api前缀取决于你的部署方式。如果是前后端分离且网关统一处理前缀那接口本身就不用再写/api。命名上我倾向于用复数名词表示资源集合比如/orders而不是/order用 HTTP 方法表达动作而不是把动词塞进路径。GET /orders是查列表GET /orders/{id}是查详情POST /orders是创建。这套约定 AI 是懂的但你得在提示词里明确要求它遵守否则它可能给你生成/getOrderList这种风格。提示如果你的项目已经有既定的接口风格一定要在提示词里把现有风格贴给 AI 看让它照着来。否则生成的东西和现有代码风格打架改起来比自己写还累。3. 异常处理体系的分层设计与错误码规划3.1 异常处理为什么要分层异常处理最容易犯的错是把所有异常都塞在一个 try-catch 里然后统一返回“系统错误”。这样做的后果是前端分不清是参数错了还是服务器挂了用户看到的是“操作失败请重试”而你在日志里也找不到具体原因。合理的做法是分层。我一般分成三层参数校验层、业务逻辑层、系统兜底层。参数校验层负责拦截格式错误、必填缺失这类问题返回 400 类错误业务逻辑层处理业务规则不满足的情况比如“余额不足”“订单已取消”返回对应的业务错误码系统兜底层捕获所有未预期的异常记录详细日志对外返回统一的 500 错误但不暴露内部细节。这个分层结构可以让 AI 帮你生成对应的异常类和处理框架。你只需要告诉它你的技术栈比如 Spring Boot、Express、FastAPI它就能给出对应的代码骨架。3.2 错误码怎么设计才不乱错误码设计有个常见的坑要么全用 HTTP 状态码要么自己造一套数字码但毫无规律。我的经验是两者结合——HTTP 状态码表达“请求层面”的结果业务错误码表达“业务层面”的具体原因。业务错误码我习惯用分段的方式比如错误码段含义示例10000-19999通用错误10001 参数缺失20000-29999用户相关20001 用户不存在30000-39999订单相关30001 订单不存在40000-49999支付相关40001 余额不足这样分段的好处是看到错误码就能大致定位问题模块。AI 生成错误码时你可以把这个分段规则告诉它让它按规则分配而不是随机给数字。3.3 用 AI 批量生成错误码和异常类有了分段规则就可以让 AI 批量生成了。提示词可以这样写基于以下错误码分段规则为订单模块生成完整的错误码枚举和对应的异常类 分段规则 - 30000-30999订单查询相关 - 31000-31999订单创建相关 - 32000-32999订单取消相关 技术栈Java Spring Boot 要求 1. 每个错误码包含 code 和 message 2. 生成对应的 BusinessException 异常类 3. 给出一个全局异常处理器示例AI 生成后你要做的是检查错误码有没有重复、message 是否清晰、异常类是否符合你项目的包结构。这一步不能省AI 偶尔会给出重复的 code 或者语义模糊的 message。4. 完整实操流程从零到可运行的接口与异常框架4.1 环境准备与项目初始化这个实战我用一个最小的 Web 项目来演示技术栈选 Python FastAPI原因是它自带请求校验和异常处理机制能直观看到效果。你用 Java、Node 或者 Go 都行思路是一样的。先建项目、装依赖mkdir api-demo cd api-demo python -m venv venv source venv/bin/activate pip install fastapi uvicorn pydantic项目结构我习惯这样组织api-demo/ ├── main.py ├── models/ │ └── order.py ├── schemas/ │ └── order.py ├── services/ │ └── order_service.py ├── exceptions/ │ ├── business.py │ └── handlers.py └── errors/ └── codes.py这个结构把数据模型、请求响应结构、业务逻辑、异常定义、错误码分开后面维护起来清晰。4.2 用 AI 生成接口定义并落地把前面 2.2 节的提示词跑一遍拿到接口草案后我把它转成 FastAPI 的代码。先定义请求和响应结构from pydantic import BaseModel, Field from typing import Optional, List from datetime import datetime class OrderQueryParams(BaseModel): user_id: int Field(..., gt0, description用户ID必填) start_time: Optional[datetime] Field(None, description开始时间) end_time: Optional[datetime] Field(None, description结束时间) page: int Field(1, ge1, description页码默认1) page_size: int Field(20, ge1, le100, description每页数量默认20最大100) class OrderItem(BaseModel): order_id: str amount: float status: str created_at: datetime class OrderListResponse(BaseModel): total: int page: int page_size: int items: List[OrderItem]这里有几个细节值得说。page_size我设了最大值 100这是防止有人传个 100000 把数据库拖垮。user_id加了gt0校验负数直接拦掉。这些约束在提示词里如果没写AI 可能不会主动加所以我在提示词里专门强调了“分页参数的默认值和最大值要写清楚”。4.3 异常处理框架的代码实现先定义错误码class ErrorCode: PARAM_MISSING (10001, 参数缺失) PARAM_INVALID (10002, 参数格式错误) USER_NOT_FOUND (20001, 用户不存在) ORDER_NOT_FOUND (30001, 订单不存在) ORDER_STATUS_INVALID (30002, 订单状态不允许此操作) SYSTEM_ERROR (50000, 系统内部错误)再定义业务异常class BusinessException(Exception): def __init__(self, error_code: tuple, detail: str None): self.code error_code[0] self.message error_code[1] self.detail detail super().__init__(self.message)然后是全局异常处理器from fastapi import Request from fastapi.responses import JSONResponse from fastapi.exceptions import RequestValidationError app.exception_handler(BusinessException) async def business_exception_handler(request: Request, exc: BusinessException): return JSONResponse( status_code200, content{ code: exc.code, message: exc.message, detail: exc.detail } ) app.exception_handler(RequestValidationError) async def validation_exception_handler(request: Request, exc: RequestValidationError): return JSONResponse( status_code400, content{ code: ErrorCode.PARAM_INVALID[0], message: ErrorCode.PARAM_INVALID[1], detail: str(exc.errors()) } ) app.exception_handler(Exception) async def global_exception_handler(request: Request, exc: Exception): logger.exception(未预期异常) return JSONResponse( status_code500, content{ code: ErrorCode.SYSTEM_ERROR[0], message: ErrorCode.SYSTEM_ERROR[1] } )这里有个设计决策需要解释业务异常我返回的 HTTP 状态码是 200而不是 400 或 500。原因是业务错误比如订单不存在在 HTTP 语义上请求是成功的只是业务结果不满足。前端拿到 200 后看code字段判断具体结果。这个做法在业界有争议有的团队坚持用 HTTP 状态码表达一切。我的建议是团队内部统一就行关键是别混着来——一会儿用状态码一会儿用业务码前端会疯。4.4 业务逻辑中如何抛出和处理异常在 service 层业务规则不满足时直接抛 BusinessExceptiondef get_order_detail(order_id: str, user_id: int): order db.query_order(order_id) if not order: raise BusinessException(ErrorCode.ORDER_NOT_FOUND, f订单 {order_id} 不存在) if order.user_id ! user_id: raise BusinessException(ErrorCode.ORDER_NOT_FOUND, 无权访问该订单) return order注意这里“无权访问”我也返回了 ORDER_NOT_FOUND而不是单独搞一个“无权限”错误码。这是安全考虑——如果返回“无权限”攻击者就能通过错误码判断哪些订单 ID 是存在的。这种细节 AI 一般不会主动想到需要你在提示词里点明“注意不要通过错误信息泄露资源是否存在”。5. 常见问题排查与避坑经验实录5.1 AI 生成内容不准确怎么办最常见的问题是 AI 生成的错误码重复或者 message 语义模糊。我的处理方式是分两步先让它生成然后单独发一轮对话让它自查——“请检查以上错误码是否有重复message 是否清晰无歧义列出所有问题”。这一轮自查能揪出大部分低级错误。另一个问题是 AI 会“过度设计”比如给你生成一大堆你用不上的错误码。这时候要果断删错误码不是越多越好只保留实际会触发的场景。我见过一个项目定义了 200 多个错误码结果实际用到的不到 30 个剩下的全是维护负担。5.2 异常处理里最容易踩的坑第一个坑是吞异常。except Exception: pass这种写法是灾难出了问题什么都查不到。至少要记录日志而且日志里要带上请求上下文比如 trace_id、用户 ID、请求参数。第二个坑是异常信息泄露。直接把数据库报错信息返回给前端可能暴露表结构甚至 SQL 语句。全局异常处理器里对外返回的 message 必须是预设的通用文案详细信息只写日志。第三个坑是异常层级混乱。自定义异常继承关系没理清导致 catch 的时候抓不到。建议所有业务异常继承同一个基类全局处理器只抓这个基类。5.3 接口联调阶段的典型问题速查问题现象可能原因排查方向前端收到 422请求体格式不符合 schema检查字段类型和必填项业务错误码返回但 HTTP 是 200业务异常处理器生效确认前端是否按 code 判断500 错误无详细信息全局兜底捕获查服务端日志找堆栈分页参数传大值导致超时缺少最大值限制在 schema 里加 le 约束时间范围筛选无效时区或格式问题统一用 ISO 8601 格式5.4 让 AI 帮你做接口自测用例接口和异常框架写完后可以让 AI 生成测试用例。提示词为以下接口生成测试用例覆盖正常场景和所有异常场景 [贴上接口定义] 要求 1. 每个用例说明输入、预期 HTTP 状态码、预期业务错误码 2. 覆盖边界值分页最大页、时间范围跨年、userId 为 0 等 3. 用表格输出生成的用例可以直接转成 pytest 或 JUnit 测试代码。我实测下来AI 生成的边界用例比我自己想的还全尤其是那些“传空字符串”“传超大数字”之类的场景人容易漏。6. 把这套方法沉淀成团队规范一个人用这套方法提效是一回事让整个团队都用起来是另一回事。我的做法是把提示词模板、错误码分段规则、异常处理骨架整理成一个内部文档新项目直接复制。AI 生成的接口草案必须经过 review 才能进代码库review 的重点是错误码有没有重复、边界场景有没有覆盖、异常信息有没有泄露风险。另外接口文档和代码要同步维护。我见过太多项目文档和实际返回对不上前端按文档写结果跑不通。用 AI 生成文档的好处是你可以把代码贴给它让它反向生成文档这样至少能保证文档和代码是一致的。每次接口变更后跑一遍比人工维护靠谱。这套流程跑顺之后一个新接口从设计到可联调时间能压缩一半以上而且质量比自己闷头写更稳定。关键是把 AI 当成一个不知疲倦的初级工程师它负责出草案和查漏你负责把关和决策。这个分工用好了接口设计和异常处理这两块最烦人的活就不再是负担了。 AI辅助接口设计与异常处理实战：从零搭建规范框架
1. 为什么接口设计和异常处理值得单独拎出来做一个小项目很多开发者写后端接口习惯是先把业务逻辑跑通接口能返回数据就算完事。至于参数校验、错误码设计、异常兜底往往是等线上出了问题才回头补。我自己早期做项目也是这个路子结果就是前端联调时反复来问“这个情况返回什么”测试提的 bug 里有一半是边界场景没处理运维半夜告警一看是某个空指针把整个请求打挂了。接口设计和异常处理这两件事单独看都不算“难”但它们是最容易被忽略、又最影响项目质量的部分。一个设计得好的接口前端拿到文档就能直接写代码不需要反复确认一套清晰的异常处理机制能让线上问题在日志里一眼定位而不是靠猜。这个实战项目的核心思路就是让 AI 来帮你把这两块补齐——不是让 AI 替你写业务逻辑而是让它帮你把那些“你知道该做但总是懒得做”的细节一次性补全。具体来说这个项目适合几类人一是刚入行不久、还没形成接口设计规范的开发者二是接手了老项目、接口风格混乱想统一的人三是想用 AI 提效但不知道怎么下手的同学。整个实战不需要复杂的框架一个普通的 Web 项目加上一个能对话的 AI 工具就够了。我会把完整的思路、提示词设计、落地步骤和踩过的坑都讲清楚你照着做就能复现。2. 接口设计的核心要素拆解与 AI 介入点2.1 一个合格接口到底要包含哪些信息在让 AI 帮忙之前得先明确“合格”的标准。我总结下来一个接口至少要说清楚这几件事请求方法、路径、请求参数含类型和是否必填、响应结构、成功和失败的判定方式、以及各种边界情况的返回。很多人写接口文档只写“成功返回什么”失败情况一笔带过这就是后面扯皮的根源。举个具体的例子。假设有个“查询用户订单列表”的接口光写GET /orders?userId1是不够的。你得说明userId 是必填还是可选如果传了不存在的 userId 返回什么分页参数默认值是多少订单为空时返回空数组还是 null这些细节不写清楚前端就得靠猜测试就得靠试。AI 在这个环节的价值是它能根据你给的业务描述快速生成一份覆盖全面的接口定义草案。你不需要从零开始想只需要在它给的草案上做增删改。这比对着空白文档发呆效率高得多。2.2 让 AI 生成接口草案的提示词怎么写提示词的质量直接决定输出质量。我试过很多种写法最后总结出一个比较稳的模板核心是给足上下文、明确输出格式、指定边界要求。你是一名资深后端工程师。请为以下业务场景设计 RESTful 接口 业务描述用户可以通过手机号查询自己的订单列表支持按时间范围筛选和分页。 要求 1. 列出所有相关接口查询列表、查询详情等 2. 每个接口说明请求方法、路径、请求参数名称/类型/是否必填/说明、响应字段 3. 明确列出所有可能的失败情况并给出对应的 HTTP 状态码和业务错误码 4. 分页参数的默认值和最大值要写清楚 5. 用表格形式输出这个提示词的关键点在于指定了角色资深后端、给了具体业务、明确了输出格式表格、强制要求覆盖失败情况。实测下来这样生成的草案基本能覆盖 80% 的场景剩下的 20% 是业务特有的逻辑需要你自己补。2.3 接口路径和命名的取舍逻辑AI 生成的路径有时候会偏“教科书”比如/api/v1/user/order/list这种层层嵌套的写法。实际项目里要不要加版本号、要不要加/api前缀取决于你的部署方式。如果是前后端分离且网关统一处理前缀那接口本身就不用再写/api。命名上我倾向于用复数名词表示资源集合比如/orders而不是/order用 HTTP 方法表达动作而不是把动词塞进路径。GET /orders是查列表GET /orders/{id}是查详情POST /orders是创建。这套约定 AI 是懂的但你得在提示词里明确要求它遵守否则它可能给你生成/getOrderList这种风格。提示如果你的项目已经有既定的接口风格一定要在提示词里把现有风格贴给 AI 看让它照着来。否则生成的东西和现有代码风格打架改起来比自己写还累。3. 异常处理体系的分层设计与错误码规划3.1 异常处理为什么要分层异常处理最容易犯的错是把所有异常都塞在一个 try-catch 里然后统一返回“系统错误”。这样做的后果是前端分不清是参数错了还是服务器挂了用户看到的是“操作失败请重试”而你在日志里也找不到具体原因。合理的做法是分层。我一般分成三层参数校验层、业务逻辑层、系统兜底层。参数校验层负责拦截格式错误、必填缺失这类问题返回 400 类错误业务逻辑层处理业务规则不满足的情况比如“余额不足”“订单已取消”返回对应的业务错误码系统兜底层捕获所有未预期的异常记录详细日志对外返回统一的 500 错误但不暴露内部细节。这个分层结构可以让 AI 帮你生成对应的异常类和处理框架。你只需要告诉它你的技术栈比如 Spring Boot、Express、FastAPI它就能给出对应的代码骨架。3.2 错误码怎么设计才不乱错误码设计有个常见的坑要么全用 HTTP 状态码要么自己造一套数字码但毫无规律。我的经验是两者结合——HTTP 状态码表达“请求层面”的结果业务错误码表达“业务层面”的具体原因。业务错误码我习惯用分段的方式比如错误码段含义示例10000-19999通用错误10001 参数缺失20000-29999用户相关20001 用户不存在30000-39999订单相关30001 订单不存在40000-49999支付相关40001 余额不足这样分段的好处是看到错误码就能大致定位问题模块。AI 生成错误码时你可以把这个分段规则告诉它让它按规则分配而不是随机给数字。3.3 用 AI 批量生成错误码和异常类有了分段规则就可以让 AI 批量生成了。提示词可以这样写基于以下错误码分段规则为订单模块生成完整的错误码枚举和对应的异常类 分段规则 - 30000-30999订单查询相关 - 31000-31999订单创建相关 - 32000-32999订单取消相关 技术栈Java Spring Boot 要求 1. 每个错误码包含 code 和 message 2. 生成对应的 BusinessException 异常类 3. 给出一个全局异常处理器示例AI 生成后你要做的是检查错误码有没有重复、message 是否清晰、异常类是否符合你项目的包结构。这一步不能省AI 偶尔会给出重复的 code 或者语义模糊的 message。4. 完整实操流程从零到可运行的接口与异常框架4.1 环境准备与项目初始化这个实战我用一个最小的 Web 项目来演示技术栈选 Python FastAPI原因是它自带请求校验和异常处理机制能直观看到效果。你用 Java、Node 或者 Go 都行思路是一样的。先建项目、装依赖mkdir api-demo cd api-demo python -m venv venv source venv/bin/activate pip install fastapi uvicorn pydantic项目结构我习惯这样组织api-demo/ ├── main.py ├── models/ │ └── order.py ├── schemas/ │ └── order.py ├── services/ │ └── order_service.py ├── exceptions/ │ ├── business.py │ └── handlers.py └── errors/ └── codes.py这个结构把数据模型、请求响应结构、业务逻辑、异常定义、错误码分开后面维护起来清晰。4.2 用 AI 生成接口定义并落地把前面 2.2 节的提示词跑一遍拿到接口草案后我把它转成 FastAPI 的代码。先定义请求和响应结构from pydantic import BaseModel, Field from typing import Optional, List from datetime import datetime class OrderQueryParams(BaseModel): user_id: int Field(..., gt0, description用户ID必填) start_time: Optional[datetime] Field(None, description开始时间) end_time: Optional[datetime] Field(None, description结束时间) page: int Field(1, ge1, description页码默认1) page_size: int Field(20, ge1, le100, description每页数量默认20最大100) class OrderItem(BaseModel): order_id: str amount: float status: str created_at: datetime class OrderListResponse(BaseModel): total: int page: int page_size: int items: List[OrderItem]这里有几个细节值得说。page_size我设了最大值 100这是防止有人传个 100000 把数据库拖垮。user_id加了gt0校验负数直接拦掉。这些约束在提示词里如果没写AI 可能不会主动加所以我在提示词里专门强调了“分页参数的默认值和最大值要写清楚”。4.3 异常处理框架的代码实现先定义错误码class ErrorCode: PARAM_MISSING (10001, 参数缺失) PARAM_INVALID (10002, 参数格式错误) USER_NOT_FOUND (20001, 用户不存在) ORDER_NOT_FOUND (30001, 订单不存在) ORDER_STATUS_INVALID (30002, 订单状态不允许此操作) SYSTEM_ERROR (50000, 系统内部错误)再定义业务异常class BusinessException(Exception): def __init__(self, error_code: tuple, detail: str None): self.code error_code[0] self.message error_code[1] self.detail detail super().__init__(self.message)然后是全局异常处理器from fastapi import Request from fastapi.responses import JSONResponse from fastapi.exceptions import RequestValidationError app.exception_handler(BusinessException) async def business_exception_handler(request: Request, exc: BusinessException): return JSONResponse( status_code200, content{ code: exc.code, message: exc.message, detail: exc.detail } ) app.exception_handler(RequestValidationError) async def validation_exception_handler(request: Request, exc: RequestValidationError): return JSONResponse( status_code400, content{ code: ErrorCode.PARAM_INVALID[0], message: ErrorCode.PARAM_INVALID[1], detail: str(exc.errors()) } ) app.exception_handler(Exception) async def global_exception_handler(request: Request, exc: Exception): logger.exception(未预期异常) return JSONResponse( status_code500, content{ code: ErrorCode.SYSTEM_ERROR[0], message: ErrorCode.SYSTEM_ERROR[1] } )这里有个设计决策需要解释业务异常我返回的 HTTP 状态码是 200而不是 400 或 500。原因是业务错误比如订单不存在在 HTTP 语义上请求是成功的只是业务结果不满足。前端拿到 200 后看code字段判断具体结果。这个做法在业界有争议有的团队坚持用 HTTP 状态码表达一切。我的建议是团队内部统一就行关键是别混着来——一会儿用状态码一会儿用业务码前端会疯。4.4 业务逻辑中如何抛出和处理异常在 service 层业务规则不满足时直接抛 BusinessExceptiondef get_order_detail(order_id: str, user_id: int): order db.query_order(order_id) if not order: raise BusinessException(ErrorCode.ORDER_NOT_FOUND, f订单 {order_id} 不存在) if order.user_id ! user_id: raise BusinessException(ErrorCode.ORDER_NOT_FOUND, 无权访问该订单) return order注意这里“无权访问”我也返回了 ORDER_NOT_FOUND而不是单独搞一个“无权限”错误码。这是安全考虑——如果返回“无权限”攻击者就能通过错误码判断哪些订单 ID 是存在的。这种细节 AI 一般不会主动想到需要你在提示词里点明“注意不要通过错误信息泄露资源是否存在”。5. 常见问题排查与避坑经验实录5.1 AI 生成内容不准确怎么办最常见的问题是 AI 生成的错误码重复或者 message 语义模糊。我的处理方式是分两步先让它生成然后单独发一轮对话让它自查——“请检查以上错误码是否有重复message 是否清晰无歧义列出所有问题”。这一轮自查能揪出大部分低级错误。另一个问题是 AI 会“过度设计”比如给你生成一大堆你用不上的错误码。这时候要果断删错误码不是越多越好只保留实际会触发的场景。我见过一个项目定义了 200 多个错误码结果实际用到的不到 30 个剩下的全是维护负担。5.2 异常处理里最容易踩的坑第一个坑是吞异常。except Exception: pass这种写法是灾难出了问题什么都查不到。至少要记录日志而且日志里要带上请求上下文比如 trace_id、用户 ID、请求参数。第二个坑是异常信息泄露。直接把数据库报错信息返回给前端可能暴露表结构甚至 SQL 语句。全局异常处理器里对外返回的 message 必须是预设的通用文案详细信息只写日志。第三个坑是异常层级混乱。自定义异常继承关系没理清导致 catch 的时候抓不到。建议所有业务异常继承同一个基类全局处理器只抓这个基类。5.3 接口联调阶段的典型问题速查问题现象可能原因排查方向前端收到 422请求体格式不符合 schema检查字段类型和必填项业务错误码返回但 HTTP 是 200业务异常处理器生效确认前端是否按 code 判断500 错误无详细信息全局兜底捕获查服务端日志找堆栈分页参数传大值导致超时缺少最大值限制在 schema 里加 le 约束时间范围筛选无效时区或格式问题统一用 ISO 8601 格式5.4 让 AI 帮你做接口自测用例接口和异常框架写完后可以让 AI 生成测试用例。提示词为以下接口生成测试用例覆盖正常场景和所有异常场景 [贴上接口定义] 要求 1. 每个用例说明输入、预期 HTTP 状态码、预期业务错误码 2. 覆盖边界值分页最大页、时间范围跨年、userId 为 0 等 3. 用表格输出生成的用例可以直接转成 pytest 或 JUnit 测试代码。我实测下来AI 生成的边界用例比我自己想的还全尤其是那些“传空字符串”“传超大数字”之类的场景人容易漏。6. 把这套方法沉淀成团队规范一个人用这套方法提效是一回事让整个团队都用起来是另一回事。我的做法是把提示词模板、错误码分段规则、异常处理骨架整理成一个内部文档新项目直接复制。AI 生成的接口草案必须经过 review 才能进代码库review 的重点是错误码有没有重复、边界场景有没有覆盖、异常信息有没有泄露风险。另外接口文档和代码要同步维护。我见过太多项目文档和实际返回对不上前端按文档写结果跑不通。用 AI 生成文档的好处是你可以把代码贴给它让它反向生成文档这样至少能保证文档和代码是一致的。每次接口变更后跑一遍比人工维护靠谱。这套流程跑顺之后一个新接口从设计到可联调时间能压缩一半以上而且质量比自己闷头写更稳定。关键是把 AI 当成一个不知疲倦的初级工程师它负责出草案和查漏你负责把关和决策。这个分工用好了接口设计和异常处理这两块最烦人的活就不再是负担了。