Result 仅含 code（自定义语义码）、message（纯文本提示）、data（泛型业务数据）三字段；提供泛型静态工厂方法 success/fail/empty 支持类型推导；Controller 统一返回 Result；异常由 @ExceptionHandler 全局转译，禁止手动封装。

设计一个基于泛型的通用 Result 对象，核心是让 code、message、data 三要素稳定可预期，同时确保泛型 T data 在各类业务场景下不破型、不报错、不丢失语义。关键不在“能封装”，而在“怎么封装才不踩坑”。

字段定义要精简且语义明确

只保留三个必选字段：int code（业务状态码）、String message（前端/日志可见提示）、T data（泛型业务数据）。避免堆砌 timestamp、extend、success 等冗余字段——它们要么可由网关补充，要么应交由具体业务子类扩展。code 不用 HTTP 状态码（如 200/404），而用自定义语义码（如 10000=成功，40001=参数缺失）；message 必须是纯文本，禁止拼接异常堆栈或敏感路径。

泛型方法必须支持类型推导

静态工厂方法不能返回固定类型（如 Result），否则在声明 Result 的接口中调用 error() 会编译失败。正确写法是泛型静态方法：

• public static Result success(T data)
• public static Result fail(int code, String message)
• public static Result empty() —— 显式表示 data 为 null 且合法

这样无论接口返回 Result 还是 Result>，所有分支路径都能自动适配 T 类型。

Controller 层强制统一返回类型

所有 @RestController 方法的返回值必须声明为 Result，禁用 void、Map、POJO 或 ResponseEntity 直接返回。好处有三：

• 前端始终解析同一结构，无需 if-else 判别响应格式
• Swagger 自动生成一致的 response schema
• 后续接入 API 网关时，签名、脱敏、审计等增强逻辑可集中注入

若已有部分接口未改造，可通过 @RestControllerAdvice 的 beforeBodyWrite 拦截非 Result 返回值，自动包装为 Result.success(value)，但需排除已返回 Result 或抛出异常的情况，保证两条通路互不干扰。

异常流转必须隔离且收敛

Result 类本身不处理异常，只负责承载结果。所有异常必须经由全局 @ExceptionHandler 统一捕获并转为标准 Result：

• MethodArgumentNotValidException → Result.fail(400, 校验字段提示)
• 自定义业务异常（如 InsufficientBalanceException）→ Result.fail(42001, "余额不足")
• 兜底 Exception → 记录日志 + Result.fail(500, "系统繁忙，请稍后再试")

禁止在 service 或 controller 中手动 try-catch 后 new Result，否则 code 定义易混乱、message 易泄露细节、日志埋点难统一。