统一返回Result-前后端契约第一课

05-统一返回Result-前后端契约第一课大家好我是黒漂技术佬。前面四篇把工程骨架、依赖、配置、启动类都讲完了。本篇是「后端工程篇」的收官也是你和前端同学「打交道的第一课」——统一返回体ResultT。为什么把它单独拎出来讲因为但凡正经的后端项目第一件事就是定「我和前端怎么对话」。URM Ultra 用ResultT做这件事。咱们不光看它怎么写还要聊一个老生常谈的争论成功到底用code0还是code200一、什么是「统一返回体」没有统一返回体时后端接口想返回啥就返回啥// 接口 A 返回{id:1,name:可乐}// 接口 B 返回{success:true,data:[...]}// 接口 C 出错返回error: 库存不足前端每接一个接口都要重新猜「这次字段叫啥、成功怎么判断」。这就是灾难。统一返回体的作用是所有接口无论成功失败都长的同一个样子前端写一套解析逻辑通吃全部。URM Ultra 的约定长这样{code:0,message:success,data:{...}}二、Result 源码级拆解项目源码packagecom.urm.ultra.common;importio.swagger.v3.oas.annotations.media.Schema;importlombok.AllArgsConstructor;importlombok.Data;importlombok.NoArgsConstructor;/** * 统一响应体。 */DataNoArgsConstructorAllArgsConstructorSchema(description统一响应体)publicclassResultT{publicstaticfinalintCODE_OK0;Schema(description业务码0 表示成功)privateintcode;Schema(description提示信息)privateStringmessage;Schema(description业务数据)privateTdata;publicstaticTResultTok(){returnnewResult(CODE_OK,success,null);}publicstaticTResultTok(Tdata){returnnewResult(CODE_OK,success,data);}publicstaticTResultTerror(intcode,Stringmessage){returnnewResult(code,message,null);}}逐行讲。2.1 三个字段字段类型含义codeint业务状态码。0代表成功非 0 代表各类错误messageString给人看的提示语成功时success失败时告诉前端/用户原因dataT真正的数据载体T是泛型可以是任意类型单个对象、列表、分页对象2.2 泛型T的意义ResultT的T是「数据部分的类型参数」。好处ResultProductr1;// data 是单个商品ResultListProductr2;// data 是商品列表ResultPageResultOrderr3;// data 是分页订单编译器帮你保证data的类型安全前端拿到的 JSON 结构始终一致只是data里的内容不同。这就是「统一壳子 可变内容」。2.3 Lombok 三个注解注解生成的东西Data所有字段的 getter/setter toStringequalshashCodeNoArgsConstructor无参构造器JSON 反序列化必需AllArgsConstructor全参构造器上面三个静态方法里new Result(...)靠它没有 Lombok这三行要手写几十行样板代码。Schema是 springdoc 的注解用于给 Swagger 文档标注字段说明联调时文档里能看到「业务码0 表示成功」这种中文释义。2.4 三个静态工厂方法注意Result的成功/失败不是靠new出来的而是靠语义化静态方法// 成功、无数据Result.ok()// 成功、带数据Result.ok(data)// 失败、带错误码和消息Result.error(code,message)为什么用静态方法而不是new看对比写法可读性return new Result(0, success, product);谁知道 0 是啥、顺序对不对return Result.ok(product);一眼懂成功了数据是 productreturn Result.error(400, 参数非法);一眼懂失败400 业务码静态工厂让「成功」和「失败」变成自解释的句子调用方和阅读者都省心。这是 URM Ultra 在 common 包里埋的编码规范。三、CODE_OK 0成功的约定源码里写死publicstaticfinalintCODE_OK0;所有ok()方法内部都用CODE_OK而不是魔法数字0。这样万一哪天约定变了基本不会只改一处常量。阅读代码时CODE_OK比0语义清晰。配合全局异常处理器GlobalExceptionHandler同处 common 包业务里抛BusinessException或参数校验失败都会被统一捕获并转成Result.error(code, message)前端永远收到规范结构不会收到一堆 Spring 的红色异常堆栈。四、核心争论code0 还是 code200这是后端圈经久不衰的「信仰之争」。先把两种风格摆出来。4.1 风格 AURM Ultra 用的业务码与 HTTP 码分离HTTP200{code:0,message:success,data:{id:1}}失败时HTTP200{code:400,message:库存不足,data:null}特点HTTP 状态码永远 200请求本身到了、被正确处理了业务成功失败靠code字段区分。4.2 风格 B很多人习惯的用 HTTP 状态码表达业务结果HTTP200← 成功{data:{id:1}}HTTP400← 参数错{message:参数非法}HTTP500← 服务器错{message:系统异常}特点把「成功/失败/错误类型」直接塞进 HTTP 状态码响应体里不包code。4.3 两种风格对比表维度code0 业务码风格URM Ultra用 HTTP 码风格响应体结构永远统一三层code/message/data成功/失败结构可能不同前端判断成功看res.code 0看 HTTP 状态码或 fetch 是否抛错混合业务错误好处理库存不足code 400余额不足code 401互不冲突难HTTP 400 既能是参数错也能是库存错网关/中间件兼容稳定HTTP 永远是 200不会被网关当失败拦截某些网关对 4xx/5xx 有重试/熔断策略调试直观性需看 body看状态码即可适合场景中大型、多业务码、前后端解耦严的项目简单 CRUD、REST 纯风格项目4.4 黒漂技术佬的观点两种都没错关键看谁来判断「成功」、错误有多少种。如果你的错误类型简单就成功/失败两种用 HTTP 码够清爽。但 URM Ultra 这种业务同一笔下单可能失败在「设备不存在」「未识别到商品」「支付失败」「库存不足」——它们是不同的业务语义可 HTTP 400/500 装不下这么多细分。用code字段就能自由扩展400参数错、1001设备不存在、1002未识别、1003支付失败……业务码是「无限可扩展」的命名空间HTTP 状态码是「有限且被协议规定」的。所以我更推荐 URM Ultra 这种「HTTP 200 打底 业务 code 细分」的写法网络层归网络层请求到没到业务层归业务层业务成没成各司其职前端一套解析逻辑走天下。这也是阿里、字节等大厂内部规范的主流选择。小提醒也有团队走「折中」——业务失败也返回对应 HTTP 码如 400同时 body 里仍有code/message/data。这吸收两家之长但实现稍复杂。URM Ultra 选了最简洁的「HTTP 恒定 200 body 带 code」。五、在 URM Ultra 里它怎么被用举几个真实调用场景来自调研报告梳理的链路场景返回查询在售商品Result.ok(ListProduct)创建订单成功Result.ok(order)库存不足Result.error(..., 库存不足)参数校验失败Result.error(400, 字段 xxx 不能为空)系统异常Result.error(500, 系统异常: ...)全局异常处理器RestControllerAdvice会把这些异常自动包成统一结构Controller 里你基本只需要return Result.ok(data)出错交给框架。六、新手怎么照着写自己的 Result给你一个最小可用模板思路同 URM Ultra可照搬DataNoArgsConstructorAllArgsConstructorpublicclassResultT{publicstaticfinalintCODE_OK0;privateintcode;privateStringmessage;privateTdata;publicstaticTResultTok(){returnnewResult(CODE_OK,success,null);}publicstaticTResultTok(Tdata){returnnewResult(CODE_OK,success,data);}publicstaticTResultTerror(intcode,Stringmessage){returnnewResult(code,message,null);}}然后约定所有 Controller 返回值都是Result具体类型。成功用ok()失败用error(code, msg)。业务码建个常量类集中管理别到处写魔法数字。七、本篇小结统一返回体让「所有接口同一种形状」前端一套解析通吃。URM Ultra 的ResultT三字段code/message/dataT是泛型数据Data等 Lombok 注解省样板。成功约定CODE_OK 0用ok()/error()静态工厂而非new语义清晰。关于code0vscode200前者把「业务成败」放进可无限扩展的code字段适合多错误类型的项目后者把成败交给 HTTP 协议。URM Ultra 选了「HTTP 恒 200 body 带业务码」这条大厂主流路线。实际写Controller 统一返回Result?异常交给全局处理器。到这里「URM Ultra 后端工程篇」五篇就讲完了。你已掌握工程怎么搭、依赖怎么配、yml 怎么读、启动类怎么回事、前后端契约怎么定。下一系列「商品设备订单支付视觉实战篇」会带你真正写业务看 JPA 怎么把一个个实体变成 15 张表、订单怎么走通「识别→下单→扣款→扣库存」。咱们下篇见。