Java统一API响应的核心是用不可变泛型Result类封装code、message、data三要素，辅以静态工厂方法和全局异常处理实现无感封装。
Java 中实现 API 统一响应，关键不是堆字段，而是让 状态码、提示信息、泛型数据 三者职责清晰、组合灵活、不重复不遗漏。核心是用一个不可变的泛型类承载结构，再通过构造方式和拦截机制自动适配各种返回场景。
定义精简但可扩展的 Result 类
这个类是统一响应的骨架，必须只含必要字段，避免语义冗余：
- code（int）：业务错误码，数值型，便于前端 switch 判断和监控告警；不用字符串，也不绑定 HTTP 状态码（如 2001 表示登录失败，而非直接用 401）
- message（String）：面向用户或调试人员的提示语，脱敏处理（如“手机号格式错误”，而非“phone does not match regex”）
-
data（T）：泛型字段，成功时携带业务对象，异常时为 null；声明为
T而非Object，避免泛型擦除导致前端反序列化失败 - 可选但推荐增加 timestamp（long） 和 requestId（String）：前者用于排查异步/重放问题，后者串联日志与链路追踪
- 禁用 success（boolean）字段：它和 code 语义重叠，容易引发前端双重判断（比如先判 success 再判 code），增加出错概率
用静态工厂方法支持多种业务语义
不要只提供 success(data) 和 fail(code, msg) 两种写法。应覆盖真实业务中常见的返回分支：
-
Result.success(user)：常规成功，code=200，msg="OK" -
Result.fail(404, "用户不存在")：明确业务码+提示 -
Result.fail(ErrorCode.ORDER_PAID)：传入枚举，code 和 msg 由枚举内聚管理，IDE 可提示、编译可校验 -
Result.of(217, "账号已停用", null)：通用构造，适合条件分支中动态组装 - 所有方法均声明为
<T> Result<T>，保证类型安全，不依赖运行时转型
让 Controller 返回更干净，异常处理更集中
Controller 层不该手动 new Result，也不该到处 try-catch。理想流程是：
立即学习“Java免费学习笔记（深入）”；
- Service 层按需抛出自定义
BusinessException（带 code、message、requestId），例如：throw new BusinessException(ErrorCode.USER_LOCKED) - Controller 只写主逻辑，返回原始对象（如
User或List<Order>），不关心封装 - 通过
@ControllerAdvice + @ExceptionHandler拦截BusinessException，统一转成Result.fail(ex.getCode(), ex.getMessage()) - 配合
ResponseBodyAdvice对非 Result 类型的返回值自动包装为Result.success(body)，真正实现“无感封装”
错误码必须集中管理，不能散落在代码各处
硬编码数字或字符串会迅速失控。正确做法是：
- 定义
ErrorCode枚举，每个项包含code、message，可选httpStatus - 命名采用层级结构，如
AUTH_TOKEN_EXPIRED、ORDER_PAYMENT_TIMEOUT，便于归类和搜索 - 自定义异常类（如
BusinessException）构造时只接收枚举，内部自动提取字段，避免重复传参 - 日志记录时带上
requestId和code，方便运维快速定位问题类型
