Java 中怎么优雅封装统一的 API 响应结果-java教程-PHP中文网

核心是用不可变泛型result类封装code、message、data三要素，通过静态工厂方法与全局异常拦截实现业务逻辑与响应封装解耦；code为int型业务码，message为脱敏提示，data为泛型业务数据，禁用success字段；统一用errorcode枚举管理错误码，controller直返原始对象，由advice自动包装或转换。

java 中怎么优雅封装统一的 api 响应结果

核心是用一个不可变、泛型化的 Result 类承载 code、message、data 三要素，再通过静态工厂方法 + 全局异常拦截实现“写业务逻辑时完全不碰封装”。

定义精简且职责清晰的 Result 类

字段只保留真正必要的三个，避免语义重叠或冗余：

code（int）：业务错误码，数值型，如 200（成功）、1001（参数错误）、5001（库存不足）。不直接复用 HTTP 状态码，也不用字符串
message（String）：面向用户或调试人员的提示，需脱敏，例如“手机号格式错误”，而非“java.lang.NumberFormatException”
data（T）：泛型字段，成功时携带业务对象，失败时为 null；声明为 T 而非 Object，防止泛型擦除导致前端反序列化失败
可选但推荐添加：timestamp（毫秒时间戳，便于排查异步/重放问题）、requestId（用于链路追踪与日志串联）
禁用 success(boolean) 字段——它和 code 语义重复，容易引发前端双重判断出错

提供语义明确的静态工厂方法

让调用方一眼看懂意图，不靠注释猜行为：

Java Development Manual

Java开发手册规约集合，基于阿里巴巴Java开发手册（嵩山版）。涵盖7大维度：编程规约、异常日志、单元测试、安全规约、MySQL数据库、工程结构、设计规约。当用户需要：(1) 编写或审查Java代码 (2) 检查命名/代码规范 (3) 处理异常和日志 (4) 编写单元测试 (5) 安全编码 (6) 数据库设...

下载

Result.success(user) → code=200，message="OK"，data=user
Result.fail(404, "商品不存在") → 明确业务码与提示
Result.fail(ErrorCode.USER_LOCKED) → 错误码用 enum 管理，IDE 可补全、编译可校验
Result.of(217, "账号已停用", null) → 通用构造，适合动态组装场景

所有方法均声明为 <t> Result<t></t></t>，保障类型安全，不依赖运行时转型。

Controller 层彻底“无感”返回原始数据

Controller 不手动 new Result，也不写 try-catch：

Service 层抛出自定义 BusinessException（含 code、message、requestId），例如：throw new BusinessException(ErrorCode.ORDER_EXPIRED)
Controller 只写主逻辑，直接返回原始对象：return userService.findById(id);
用 @ControllerAdvice + @ExceptionHandler 拦截 BusinessException，统一转成 Result.fail(ex.getCode(), ex.getMessage())
用 ResponseBodyAdvice 对所有非 Result 类型的返回值，自动包装为 Result.success(body)

错误码必须集中管理，禁止硬编码

散落在各处的数字或字符串会迅速失控：

用 enum 定义错误码字典，每个枚举项自带 code 和 message，例如：

public enum ErrorCode {
  SUCCESS(0, "操作成功"),
  PARAM_ERROR(1001, "参数格式错误"),
  NOT_FOUND(404, "资源不存在");
  private final int code;
  private final String message;
  // 构造 + getter 略
}