Python错误码设计教程_接口异常统一规范

Python接口错误码需语义明确、层级分明、可扩展、不重复，推荐三位或四位分段编码（如2001表示用户模块参数错误），首位数字标识大类（1系统/2用户/3数据/4参数/5服务端/6第三方），后位标识具体场景；须用Enum定义并继承统一异常基类，配合HTTP状态码协同使用（如400+4001），禁止魔数硬写或滥用200响应业务错误，且需文档化、版本化管理。

Python接口开发中，错误码不是随便编个数字就行，关键是要让前后端协作高效、排查问题快速、后期维护清晰。核心原则是：语义明确、层级分明、可扩展、不重复。

错误码结构设计：三位或四位分段式编码

推荐采用 三位十进制数（如 100、401、503）或 四位分段编码（如 2001 表示「用户模块-参数错误」），兼顾HTTP状态码习惯与业务可读性。

• 首位数字表示错误大类：1=通用/系统级，2=用户/权限类，3=数据类（查不到、冲突），4=参数/客户端错误，5=服务端异常，6=第三方调用失败
• 后两位（或后三位）标识具体场景：例如 401 是标准未授权，但业务中可定义 2001（用户不存在）、2002（密码错误）、2003（账号被禁用）
• 避免使用纯顺序编号（如 1001、1002…），否则无法一眼识别归属模块；也别直接复用HTTP状态码做全部业务码（比如用 404 表示“订单不存在”可以，但不能用 404 表示“库存不足”）

统一异常基类 + 枚举管理错误码

不靠字符串拼接或魔法数字硬写，而是用 Python 枚举（Enum）定义所有错误码，并继承一个自定义异常基类，确保抛出、捕获、序列化行为一致。

• 定义 ErrorCode 枚举，每个成员包含 code（数字）、message（中文提示）、http_status（对应HTTP状态，如400/401/500）
• 实现 APIException 基类，接收枚举实例初始化，自动携带 code/message/status
• 全局异常处理器（如 FastAPI 的 @app.exception_handler(APIException) 或 Flask 的 errorhandler）统一返回 JSON 格式：{"code": 2001, "message": "用户不存在", "data": null}

错误码与 HTTP 状态码协同，不强行一一映射

HTTP 状态码表达的是通信/协议层语义（如 400=请求无效，500=服务炸了），而业务错误码表达的是领域逻辑结果（如“优惠券已用完”“实名认证未通过”）。二者应配合，而非替代。

• 参数校验失败 → HTTP 400 + 业务码 4001
• 未登录/Token过期 → HTTP 401 + 业务码 2004
• 数据库唯一约束冲突 → HTTP 409 + 业务码 3002
• 下游服务超时 → HTTP 503 + 业务码 6003
• 绝不用 200 响应体里塞一个 "code": 500 —— 这会绕过前端的网络错误拦截逻辑

配套文档与演进管理：错误码不是写完就扔

错误码是接口契约的一部分，必须和 OpenAPI 文档、SDK、前端常量表同步更新。

• 用 pydantic 模型定义标准响应结构，把 code 字段类型设为 Literal 或关联枚举，支持 IDE 提示和校验
• 在 Swagger / Redoc 文档中标注每个接口可能返回的错误码及含义（可用 x-code-samples 或自定义字段）
• 新增错误码必须走 CR（Code Review），禁止私下添加；废弃错误码保留历史记录，标记 deprecated，至少保留一个大版本
• 建议生成一份可搜索的 error_codes.md，按模块/场景分类，附 HTTP 状态、典型触发条件、建议前端处理方式

不复杂但容易忽略：错误码的价值不在定义那一刻，而在每一次被准确抛出、被前端友好展示、被日志精准归因、被新同学快速看懂。从第一个接口开始就定好规范，后面省下的调试时间远超初期多写的那几十行代码。