如何设计一个优秀的接口？统一结果返回值

✨ 一、接口的统一返回值是什么？

它是一件外套，把所有接口的返回内容装进同一套格式里。无论请求成功还是出错，都给前端返回固定结构，比如：

{"code":200,"message":"OK","data":{...}}

像讲故事时总是用“开头、正文、结尾”一样，你的接口也需要固定的句式，让对方不用猜今天你会不会突然换腔调。

常见结构会包含：

• code业务状态码（不是 HTTP 状态码）

• message提示信息（成功/失败原因）

• data业务数据

• timestamp（可选）响应时间

• traceId（可选）链路追踪辅助

🎐 这让你的接口像带格式的礼物盒，不会乱七八糟。

✨ 二、为什么要统一返回值？

这一段像在写接口的“生存理由”：

1. 前端更好处理
   前端只需要写一套判断逻辑，比如code === 200 OK。如果每个接口都长得不一样，前端会像解一个拼不出来的拼图。

2. 调试更舒服
   报错结构一致，日志里查问题一眼看穿。

3. 团队协作不会混乱
   新人写接口也不用再纠结“到底怎么返回”。

4. 更适合大项目/中台
   各个服务统一语言，像所有人都用同一个字典。

5. 可以扩展功能
   比如自动加 traceId、自动包装异常、全局异常处理等等，统一返回是基础。

✨ 三、怎么做？（带代码实现）

这一步像搭一座小桥，把规范送到所有接口上。

1. 先定义统一返回体 ResponseResult

@DatapublicclassR<T>{privateIntegercode;privateStringmessage;privateTdata;publicstatic<T>R<T>success(Tdata){R<T>r=newR<>();r.setCode(200);r.setMessage("success");r.setData(data);returnr;}publicstatic<T>R<T>fail(Stringmessage){R<T>r=newR<>();r.setCode(500);r.setMessage(message);returnr;}}

2. 在Controller层中用

@GetMapping("/user/{id}")publicR<User>getUser(@PathVariableLongid){Useruser=userService.getById(id);returnR.success(user);}

3. 全局异常统一放回

@RestControllerAdvicepublicclassGlobalExceptionHandler{@ExceptionHandler(Exception.class)publicRhandleException(Exceptione){returnR.fail(e.getMessage());}}