错误模型设计实战：统一返回体、异常处理与错误码规范

聊到错误模型，绕不开三个词：数据、异常、正常返回。很多项目表面上功能齐全，一上线就原形毕露，问题大多出在“出错之后返回值怎么约定”上。有的接口返回 null，有的直接抛异常，前端要 try-catch 一层，还要再判断 code，偶尔堆栈信息还直接暴露给用户。这套东西如果没设计好，线上每次故障都像一次考古。这篇内容围绕错误模型怎么落地展开，核心解决三件事：正常返回该长什么样、异常什么时候该抛、错误码怎么设计。适合刚接手项目的新人，也适合正在重构老接口的负责人。

1. 错误模型到底是什么：先想清楚三条路

1.1 三类出口的语义边界

我见过太多团队在评审接口时只讨论“参数对不上怎么办”，从来没人先说清楚“系统到底有几条出口”。实际上，一个系统的对外输出只有三类：正常返回的数据、主动抛出的异常、以及给调用方看的错误码/错误响应。

这三类东西语义完全不同。正常返回处理的是“符合预期的业务结果”，比如查订单列表，查到 100 条是返回，查到 0 条也是返回。异常处理的是“当前流程无法继续执行”的情况，比如数据库连接断了、磁盘满了、代码里有个 bug 导致空指针。错误码处理的是“调用方需要自行判断和处理的业务失败”，比如参数不合法、订单不存在、余额不足。

一个简单判断标准：如果“用户查不到订单”也算一种业务结果，那它应该走正常返回，而不是抛异常。如果“用户提交了一个非法的日期格式”，这是调用方的问题，应该返回业务错误码。如果“数据库连接池被耗尽”，这是系统内部故障，应该抛异常并触发告警。

很多老项目的通病，就是这三条路没分开。查询结果为空时返回 null，同事调用时忘了判空就 NPE，于是又在外层包了一个 try-catch，把空值问题伪装成系统异常。最后整个代码库里全是 catch 块，没人敢删，也没人看得懂。

1.2 为什么“异常”不能当“返回”用

有些同学喜欢用异常表达一切错误，甚至在业务正常分支里也主动 throw。我在代码 review 里经常见到这样的写法：查订单，查不到就 throw new OrderNotFoundException，然后由全局异常处理器转成“订单不存在”返回给前端。

这么写看起来省事，但代价很高。第一，异常构造本身要抓取堆栈，比普通 return 慢几个数量级，虽然大多数业务系统不差这点性能，但高频接口会受影响。第二，异常的语义是“流程被打断”，如果用它传递预期业务结果，代码会被 try-catch 包得面目全非，后来的人根本分不清哪些 catch 是处理真正的故障，哪些只是在兜一个本可以走 return 的分支。第三，异常日志会被大量无效噪声淹没，告警失去意义。

真正应该抛异常的场景，是“你无法在当前代码层面恢复，必须让上层决定怎么处理”。比如连接数据库失败，底层不知道是该重试还是该降级，只能往上抛；再比如代码里数组越界，这是程序员写错了，应该尽早抛出、快速失败，而不是把越界当成一种“返回结果”静静吞掉。

1.3 关于热词里那些“异常”：从现象看本质

最近我整理了一批和异常相关的实际问题，表面看都是报错，但背后的分类完全不同。比如：

• 终端进程启动失败、注册表异常、驱动工作异常（代码 31）：这类属于环境健康问题，不是业务问题，错误模型里要单独归类，通常走系统异常加人工介入处理。
• 数组越界异常、非法参数异常：这类属于编码问题，大多发生在调用方没有做前置校验，或者索引计算有 bug，应该 fail-fast，让问题在开发阶段就暴露。
• 获取首页数据失败，伺服器错误 502：这类是外部依赖问题，可能是上游服务挂了，错误模型要考虑重试、熔断、超时，并明确告知调用方“这次失败是暂时的，可以稍后请求”。
• DataFrame 异常数据处理、Flink JDBC 连接器异常：这类是数据链路问题，要么是数据结构不合法，要么是连接资源占满，处理方式完全不同。

看到一条报错先别急着修，先问一句：它应该走哪条出口？分类清楚了，处理方案自然就出来了。

2. 数据、异常与正常返回：错误模型设计的关键决策

2.1 正常返回的自我修养：null、空集合与 Optional

正常返回这条路上，最容易埋雷的就是 null。Java 里一个接口返回 List，如果查不到数据就返回 null，调用方如果用 for 循环直接遍历，立刻 NPE。这种 NPE 极难查，因为堆栈里只有一行 “NullPointerException”，根本看不出是哪个列表为空。

我的原则很简单：集合查询结果永远返回空集合，不要返回 null。条件查询可能查不到单条记录时，用 Optional 包装，或者明确返回 null 并在字段注释里写清楚。Pandas 里也类似，一个 DataFrame 为空，它仍然有 columns 和 dtype，你在空 DataFrame 上做过滤、聚合都不会崩。这恰恰说明“空数据”和“无数据”是两个概念，好的数据模型会让空状态也变得可操作。

真正要避免的是“一层层传 null”。比如 methodA 调 methodB，methodB 内部判断某个字段为 null 就返回 null，methodA 又拿着这个 null 去调 methodC，methodC 再返回 null。这种 null 传播会把错误模型搅浑，最后所有判断都变成“if (xxx != null) 才继续”，代码可读性极差。

正确的做法是：在边界处就把空值语义定义清楚。查询结果没有数据，那就返回一个明确的结构，列表为空也好、Optional.empty 也好，不要让 null 在内部代码里到处飞。

2.2 错误码设计：从“散装”到“有结构”

错误码不是简单的“1 成功、0 失败”，而是要形成一套稳定、可扩展、可读的编码体系。我见过最乱的项目，错误码散落在各个服务里，有的用字符串 “SUCCESS”，有的用数字 200，有的用 -1，前后端对不上，出了问题只能全文搜索。

比较通用的做法是分段编码。比如五位数字错误码，前两位表示微服务编号或业务域编号，中间两位表示错误类型，后一位表示具体错误项。像 20000 表示通用成功，20001 表示参数为空，20002 表示参数格式错误，30001 表示订单不存在，30002 表示订单状态不允许操作。这样的好处是，看到错误码就能快速定位到是哪个域、哪类错误。

错误码一旦定下来，就不要轻易改语义。尤其不要用同一个 code 表示两种完全不同的含义，否则存量接口消费方会集体踩坑。每次新增错误码，都要记录下来，放到一个公共枚举或者错误码清单里，注释写清楚触发条件和返回给用户的文案。

2.3 异常体系：系统异常、业务异常、断言异常的区别

异常体系建议分三层。

业务异常，代码里叫 BizException，表示预期内的业务规则失败，比如余额不足、订单已取消。这类异常在 controller 层被捕获后，转换成对应的业务错误码返回给前端，不需要打完整堆栈，只需要记一条 warn 日志。

系统异常，代码里叫 SystemException，表示非预期故障，比如数据库连接超时、Redis 连接失败、外部接口调用超时。这类异常需要转成通用系统错误码，同时必须打 error 日志并触发告警，因为这是需要值班人员马上介入的。

断言异常，比如 IllegalArgumentException、IndexOutOfBoundsException，属于编程错误，理论上不应该暴露给用户。全局异常处理器里要兜住它们，返回通用参数错误或系统错误，但日志级别建议设为 error，方便开发尽快发现。

我见过一个很实用的扩展：在自定义异常里加时间戳或 traceId 字段。热词里有“java 自定义异常时间戳方便快递定位”，这个思路我很推荐。当一个异常在日志系统里被捞出来时，单独一个异常对象只能说明“哪里炸了”，加上时间戳和 traceId，才能快速还原“哪个请求、在哪个时刻、经过哪些服务炸了”。

3. 从零落地一套错误模型：以 Java 场景为例

3.1 统一返回体 Result 的定义与泛型设计

动手落地时，第一步是定义一个统一返回体。几乎所有现代 Web 项目都会做一个 Result 包装，把业务数据塞进 data 字段，旁边再放 code 和 message。

public class Result<T> { private int code; private String message; private T data; private String traceId; public static <T> Result<T> success(T data) { Result<T> result = new Result<>(); result.setCode(ErrorCode.SUCCESS.getCode()); result.setMessage(ErrorCode.SUCCESS.getMessage()); result.setData(data); return result; } public static <T> Result<T> error(int code, String message) { Result<T> result = new Result<>(); result.setCode(code); result.setMessage(message); return result; } // 省略 getter/setter }

为什么 code、message、data、traceId 缺一不可？code 给程序判断，message 给人看，data 放真正的业务数据，traceId 串起全链路日志。没有 traceId 的统一返回体，排查问题时每一条日志都要靠时间模糊匹配，效率极低。

还有一个设计细节容易被忽略：成功码要全局统一。有些人喜欢用 HTTP 200 表示成功，有些人用 0，有些人用 00000。我建议团队商定一个值后写进公共文档，前后端都按这个值判断。不要出现“接口返回 HTTP 200，但 body 里的 code 是 5001”这种双层状态，会让调用方不知道到底以谁为准。

3.2 全局异常处理器的实现与自动兜底

有了统一返回体，还需要一个全局异常处理器，把异常自动转换成 Result，避免每个 controller 自己写 try-catch。

用 Spring Boot 的话，@RestControllerAdvice 是最常用的方案：

@RestControllerAdvice public class GlobalExceptionHandler { @ExceptionHandler(BizException.class) public Result<Void> handleBizException(BizException e) { log.warn("业务异常: code={}, msg={}", e.getCode(), e.getMessage()); return Result.error(e.getCode(), e.getMessage()); } @ExceptionHandler(MethodArgumentNotValidException.class) public Result<Void> handleValidException(MethodArgumentNotValidException e) { String msg = e.getBindingResult().getFieldError().getDefaultMessage(); return Result.error(ErrorCode.PARAM_INVALID.getCode(), msg); } @ExceptionHandler(Exception.class) public Result<Void> handleException(Exception e, HttpServletRequest request) { log.error("系统异常: uri={}, traceId={}", request.getRequestURI(), TraceIdUtil.getTraceId(), e); return Result.error(ErrorCode.SYSTEM_ERROR.getCode(), ErrorCode.SYSTEM_ERROR.getMessage()); } }

这个兜底 Exception 是最关键的一层。它保证任何没有被框架识别的异常，都能转换成统一返回体，并且不会把异常堆栈直接暴露给前端。调试时可以临时打印堆栈到响应里，但线上必须关掉。

这里有一个经验：兜底异常处理里，日志要打出请求路径、traceId 和完整堆栈，而返回给用户的 message 只能是类似“系统繁忙，请稍后重试”的通用文案。否则用户会把内部方法名、SQL 片段、甚至文件路径全部截图发群里，既难看又不安全。

3.3 业务异常与错误码枚举的联动

业务异常类的设计，建议直接内置一个 ErrorCode 字段：

public class BizException extends RuntimeException { private final ErrorCode errorCode; public BizException(ErrorCode errorCode) { super(errorCode.getMessage()); this.errorCode = errorCode; } public ErrorCode getErrorCode() { return errorCode; } }

这样业务代码里只写一句：

if (order == null) { throw new BizException(ErrorCode.ORDER_NOT_FOUND); }

全局异常处理器拿到 BizException 后，直接从 errorCode 里取 code 和 message。链路从抛出到前端展示，全程走同一套错误码，谁都不会传错。

错误码枚举示例：

public enum ErrorCode { SUCCESS(0, "成功"), PARAM_INVALID(20001, "参数不合法"), ORDER_NOT_FOUND(30001, "订单不存在"), ORDER_STATUS_ERROR(30002, "当前订单状态不允许该操作"), SYSTEM_ERROR(50000, "系统繁忙，请稍后重试"); private final int code; private final String message; // 构造器和 getter 省略 }

很多人纠结业务异常是继承 RuntimeException 还是 Exception。我建议继承 RuntimeException，原因很简单：不强制调用方 catch，避免“checked exception 污染”。业务异常本质上不是让调用方恢复的，而是让上层统一处理的，用 unchecked 最省事。

3.4 日志打印与时间戳注入的一个实践

热词里提到“自定义异常时间戳方便快速定位”，这确实是我在线上踩过坑之后才加的设计。早期我们的异常对象只有 message，日志系统里同一个错误会出现几千条，每条都长得一模一样，根本不知道哪个用户、哪个请求触发的。

后来我做了两件事。第一，在 Result 和异常里都加 traceId；第二，用日志框架的 MDC 把 traceId 自动打印到每一条日志里。

public class TraceIdUtil { private static final String TRACE_ID = "traceId"; public static String getTraceId() { return MDC.get(TRACE_ID); } public static void setTraceId(String traceId) { MDC.put(TRACE_ID, traceId); } }

在请求入口的 Filter 里：

public class TraceIdFilter implements Filter { @Override public void doFilter(ServletRequest req, ServletResponse res, FilterChain chain) { String traceId = UUID.randomUUID().toString().replace("-", ""); TraceIdUtil.setTraceId(traceId); try { chain.doFilter(req, res); } finally { TraceIdUtil.clearTraceId(); } } }

日志配置里这样写：

<pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%X{traceId}] [%thread] %-5level %logger{36} - %msg%n</pattern>

这样每一条日志都会自动带上 traceId。线上出问题时，从前端报错拿到的 traceId 到日志平台一搜，整条请求链路的所有日志全部串起来，再配合异常对象里的时间戳字段，定位效率能提升一个量级。

3.5 移植到 Python/Pandas 场景时的变体

这套思想不只在 Java 里成立。热词里出现“python 结构化数据”“DataFrame 异常数据处理”，Python 项目同样需要错误模型。

Python 里没有统一返回体这个强制约束，很多脚本随手 return None，导致下游处理时到处判 None。我的习惯是：对外提供数据结构时，尽量返回空集合而不是 None；确实可能缺失的单值，用Optional[Any]明确标注；自定义异常类至少继承 Exception 或 RuntimeError，并在异常里带上错误码。

Pandas 处理脏数据时，反而要尽量少用异常。比如读取一列数据，里面有缺失值、非法格式，直接用pd.isna、pd.to_numeric(errors='coerce')这类方法把数据规范化，而不是用 try-except 一层层包。异常应该留给真正无法继续执行的故障，比如文件路径不存在、表结构对不上，而不是每个单元格的脏数据。

4. 常见问题与排查技巧实录

4.1 问题速查表：从热词中拎出来的典型错误

下面这段内容，很多真实报错案例可以直接归类到错误模型里去，我在表格里给出常见现象、归类和建议。

每条报错在动手处理前，先确定它是“业务失败”“系统故障”还是“环境问题”，再决定它在错误模型里对应哪个出口。很多排查白白浪费一个小时，就是因为把系统故障当成业务参数问题在查。

4.2 错误处理中的“吞异常”与“重复包装”问题

我见过最伤的代码，不是没处理异常，而是把异常吞了。

try { orderService.createOrder(orderDTO); } catch (Exception e) { // 什么也不做 }

这种代码上线后，线上会出现一个非常诡异的现象：订单没生成，但接口返回成功。用户没收到任何提示，运维也看不到错误日志，只能靠用户投诉才后知后觉。吞异常的危害比直接抛异常大得多，因为它把系统故障伪装成了正常流程。

另一种问题是重复包装。有的同事 catch 到异常后，又 new 了一个通用 Exception 抛出去，把原始堆栈覆盖掉。

catch (Exception e) { throw new RuntimeException("创建订单失败"); }

这样日志里只有一句“创建订单失败”，没有原始根因。正确做法是把原始异常作为 cause 传进去：

catch (Exception e) { throw new BizException(ErrorCode.ORDER_CREATE_FAILED, e); }

如果在自定义异常里没有接收 cause 的构造器，就加上去。排查线上问题时，“根因异常”和“业务包装信息”缺一不可。

4.3 调试技巧：没有日志就没有真相

最后分享一个排查链路。线上某个接口报错，我先不看代码，直接去日志平台做三件事。

第一，拿前端或网关返回的 traceId 去搜日志，把请求入口、服务内部调用、外部依赖调用全链路捞出来。第二，看错误日志的级别和时间，如果业务异常是 warn，系统异常是 error，一眼就能判断故障严重度。第三，看异常堆栈里最底层那个 cause，而不是最上层那个通用 message。很多时候真正原因是数据库死锁，被上层包装成了“操作失败”，不看 cause 根本猜不到。

热词里提到“graphlib 分析异常原因”，这个思路放在分布式系统里也很好用：把服务间的依赖关系画成一张有向图，异常沿着调用链反向追溯。A 服务报错，往往是因为 B 服务超时，B 服务超时又是因为 C 服务负载过高。错误模型如果在一开始就统一了 traceId，这张图的全链路日志就能自动串起来，分析异常原因就像沿着边在图上走一样顺畅。

我在实际项目中还有一个习惯：每个服务都要有一个“异常统计面板”，按错误码、异常类、traceId 出现次数聚合。哪类错误突然暴增，说明某个模块正在出问题，不用等用户投诉就能提前告警。这套机制依赖的底层，还是那个最朴素的错误模型：数据该走数据通道，异常该走异常通道，错误码该走错误码通道，三件事绝不混在一起。

最后再分享一个小细节：新项目启动的第一天，先把 Result、错误码枚举、全局异常处理、traceId 过滤器这四个文件建好，哪怕业务代码一行都没写。这四样东西就是整个系统错误处理的骨架。后期每加一个接口，每接一个前端页面，都是在这个骨架上生长。我见过太多项目上线一年后才想起来补统一错误模型，结果所有接口都已经写成了乱七八糟的 try-catch 和 null 返回，改起来伤筋动骨。错误模型的成本不是写代码的成本，而是决定“三条路分别怎么走”的思考成本，这步想清楚，后面全是顺水推舟。