假如现在有一个Java项目,老板让你做项目组长,定义项目基础框架,系统技术架构选型,
你应该如何设计一个规范的统一的Restful API 响应框架呢
思考
目前项目开发,都是基于前后端分离模式开发的,基于后端模板引擎那一套,可能已经不适用一些项目开发流程,和当下开发模式了,尤其在要写比较大型项目,前后端项目拆分,团队共同开发那是必不可少的
目前的前后端开发大部分数据的传输格式都是json，因此定义一个统一规范的数据格式有利于前后端的交互与UI的展示。
返回的统一接口形式应该包含这些内容
- 是否响应成功
- 响应状态码
- 状态码描述
- 响应数据
- 接口调用时间
- 其他标识符
按照这些我们可以定义统一的标准结果返回
响应枚举
前三者可以定义为 success,code,message
package cn.soboys.springbootrestfulapi.common.resp;
import lombok.Data;
import lombok.Getter;
import org.springframework.web.bind.annotation.GetMapping;
/**
* @author 公众号 程序员三时
* @version 1.0
* @date 2023/4/28 22:39
* @webSite https://github.com/coder-amiao
* 响应结果枚举
*/
@Getter
public enum ResultCodeEnum{
SUCCESS(true, 200, "成功"),
FAIL(false, 400, "请求失败"),
NOT_FOUND(false, 404, "接口不存在"),
FORBIDDEN(false, 403, "资源拒绝访问"),
UNAUTHORIZED(false, 401, "未认证（签名错误）"),
INTERNAL_SERVER_ERROR(false, 500, "服务器内部错误"),
NULL_POINT(false, 200002, "空指针异常"),
PARAM_ERROR(false, 200001, "参数错误");
/**
* 响应是否成功
*/
private Boolean success;
/**
* 响应状态码
*/
private Integer code;
/**
* 响应信息
*/
private String message;
ResultCodeEnum(Boolean success, Integer code, String message) {
this.success = success;
this.code = code;
this.message = message;
}
}
统一结果类
- 外部返回调用类统一的结果方法
success,failure因此构造器私有 - 内置静态方法，直接返回对象
- 便于自定义统一结果信息，使用链式编程，返回对象类本身
return this - 响应数据为json格式，可定义为
JsonObject或Map形式
package cn.soboys.springbootrestfulapi.common.resp;
import lombok.Data;
import java.util.HashMap;
import java.util.Map;
/**
* @author 公众号 程序员三时
* @version 1.0
* @date 2023/4/28 22:47
* @webSite https://github.com/coder-amiao
* 统一响应结果处理 使用链式编程 返回类本身
*/
@Data
public class R {
private Boolean success;
private Integer code;
private String message;
/**
* 接口请求时间戳
*/
private Long timestamp;
private Map data = new HashMap<>();
private R setSuccess(Boolean success) {
this.success = success;
return this;
}
private R setMessage(String message) {
this.message = message;
return this;
}
private R setData(Map data) {
this.data = data;
return this;
}
private R setCode(Integer code) {
this.code = code;
return this;
}
private R() {
}
private R(Long timestamp) {
this.timestamp = timestamp;
}
/**
* 通用返回成功
*
* @return
*/
public static R success() {
return new R(System.currentTimeMillis())
.setSuccess(ResultCodeEnum.SUCCESS.getSuccess())
.setCode(ResultCodeEnum.SUCCESS.getCode())
.setMessage(ResultCodeEnum.SUCCESS.getMessage());
}
/**
* 通用返回失败
*
* @return
*/
public static R failure() {
return new R(System.currentTimeMillis())
.setSuccess(ResultCodeEnum.FAIL.getSuccess())
.setCode(ResultCodeEnum.FAIL.getCode())
.setMessage(ResultCodeEnum.FAIL.getMessage());
}
/**
* 设置结果，形参为结果枚举
*
* @param result
* @return
*/
public static R setResult(ResultCodeEnum result) {
return new R(System.currentTimeMillis())
.setSuccess(result.getSuccess())
.setCode(result.getCode())
.setMessage(result.getMessage());
}
// 自定义返回数据
public R data(Map map) {
return this.setData(map);
}
// 通用设置data
public R data(String key, Object value) {
this.data.put(key, value);
return this;
}
// 自定义状态信息
public R message(String message) {
return this.setMessage(message);
}
// 自定义状态码
public R code(Integer code) {
return this.setCode(code);
}
// 自定义返回结果
public R success(Boolean success) {
return this.setSuccess(success);
}
}
控制层调用返回
package cn.soboys.springbootrestfulapi.controller;
import cn.soboys.springbootrestfulapi.common.resp.R;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import java.util.HashMap;
import java.util.Map;
/**
* @author 公众号 程序员三时
* @version 1.0
* @date 2023/4/28 23:58
* @webSite https://github.com/coder-amiao
*/
@RestController
public class IndexController {
@GetMapping("/index")
public R index() {
Map m = new HashMap();
m.put("name", "Tom");
m.put("age", 25);
m.put("sex", "男");
return R.success().data(m);
}
@GetMapping("/home")
public R home() {
Student s = new Student();
s.setUserName("Tom");
s.setBalance(2229891.0892);
return R.success().data("user", s).message("查询用户详情信息");
}
/**
* 异常返回模拟
*
* @return
*/
@GetMapping("/exception")
public R exception() {
Map m = null;
m.put("name", "Jack");
return R.success().data("user", m).message("查询用户详情信息");
}
}
统一结果类的使用参考了mybatis-plus中R对象的设计。
问题思考
使用统一返回结果时，还有一种情况，就是程序由于运行时异常导致的结果，有些异常我们可
能无法提前预知，不能正常走到我们return的R对象返回。
这个时候该如何处理
下一篇文章会继续分享，留下你的思考
准备从零做一套自己的开发脚手架模板 ，关注公众 程序员三时