如何优雅地写后端API接口

缺乏、安全感 2022-12-29 14:28 164阅读 0赞

在移动互联网，分布式、微服务盛行的今天，现在项目绝大部分都采用的微服务框架，前后端分离方式。前后端的工作职责越来越明确，现在的前端都称之为大前端，技术栈以及生态圈都已经非常成熟；以前后端人员瞧不起前端人员，那现在后端人员要重新认识一下前端，前端已经很成体系了

# **1.接口交互** #

前端和后端进行交互，前端按照约定请求URL路径，并传入相关参数，后端服务器接收请求，进行业务处理，返回数据给前端。

针对URL路径的restful风格，以及传入参数的公共请求头的要求（如：app\_version,api\_version,device等），这里就不介绍了，小伙伴们可以自行去了解，也比较简单。

着重介绍一下后端服务器如何实现把数据返回给前端？

# **2.返回格式** #

**后端返回给前端我们采用json格式**

{
      "success": boolean,
      "code": int,
      "data": object,
      "msg": string
    }

*  success是否成功

最简单的判断，前端直接取该值判断是否操作成功，成功为true，失败为false

*  code状态码

当一个操作会因为多种因素失败的情况下，每种失败的原因进行设置不同的状态码。可以按照业务区分，例如用户的错误状态码在101-199之间，系统的错误状态码在201-299之间，可以按照自己的业务进行设置，我们参考下http状态码：

200 - 请求成功
    301 - 资源（网页等）被永久转移到其它URL
    404 - 请求的资源（网页等）不存在
    500 - 内部服务器错误

*  data数据

这里是具体要返回的数据，数据格式可以为数组、对象、字符串等格式

*  msg消息

这个字段相对理解比较简单，就是发生错误时，如何友好的进行提示。一般的设计是和code状态码一起设计。如登陆失败> code:203，msg:登陆失败，账号或者密码有误

## 2.1.返回样例 ##

这就是一个操作成功返回的例子

{
      "success": true,
      "code": 1,
      "data": {"k": "v"},
      "msg": "操作成功"
    }

# 3.实现 #

## 3.1.定义状态码枚举类 ##

package com.niu.demo.util;
    
    /**
     * @description: 状态吗设置
     * @author: nxq email: niuxiangqian163@163.com
     * @createDate: 2020/12/21 7:46 下午
     * @updateUser: nxq email: niuxiangqian163@163.com
     * @updateDate: 2020/12/21 7:46 下午
     * @updateRemark:
     * @version: 1.0
     **/
    public enum ResultCode {
    	/* 通用状态码 成功与失败 */
    	SUCCESS(1,"ok"), FAILED(-1,"操作失败"),
    	/* 参数错误  101 - 199*/
    	PARAM_IS_INVALID(101,"参数无效"),
    	PARAM_IS_BLANK(101,"参数为空"),
    	/* 用户错误  201 - 299  */
    	USER_NOT_LOGIN(201,"未登录"),
    	USER_NOT_EXIST(202,"用户不存在"),
    	USER_LOGIN_ERROR(203,"登陆失败，账号或者密码有误"),
    	NOT_PERMISSION(204,"无权限访问"),
    	/* 业务错误 301 - 399*/
    	DATA_NOT_FOUND(301,"没有数据"),
    	//.......更多
    	;
    	private Integer code;
    	private String msg;
    
    
    	ResultCode(Integer code, String msg) {
    		this.code=code;
    		this.msg=msg;
    	}
    
    	public Integer getCode() {
    		return code;
    	}
    
    	public String getMsg(){
    		return msg;
    	}
    }

## 3.2.创建返回结果类 ##

package com.niu.demo.util.core;
    
    import com.niu.demo.util.ResultCode;
    import java.io.Serializable;
    
    /**
     * @description: 响应类
     * @author: nxq email: niuxiangqian163@163.com
     * @createDate: 2020/12/21 7:37 下午
     * @updateUser: nxq email: niuxiangqian163@163.com
     * @updateDate: 2020/12/21 7:37 下午
     * @updateRemark:
     * @version: 1.0
     **/
    public class R<T> implements Serializable {
    
        private static final long serialVersionUID = 1L;
        private int code;  //状态码
        private boolean success; //是否成功
        private String msg; //提示信息
        private T data; //数据
    
        public static <T> R<T> ok() {
            return restResult(null, ResultCode.SUCCESS.getCode(),  ResultCode.SUCCESS.getMsg());
        }
    
        public static <T> R<T> ok(T data) {
            return restResult(data, ResultCode.SUCCESS.getCode(), ResultCode.SUCCESS.getMsg());
        }
    
        public static <T> R<T> ok(T data, String msg) {
            return restResult(data, ResultCode.SUCCESS.getCode(), msg);
        }
    
        public static <T> R<T> failed() {
            return restResult(null, ResultCode.FAILED.getCode(), ResultCode.FAILED.getMsg());
        }
        public static <T> R<T> failed(String msg) {
            return restResult(null, ResultCode.FAILED.getCode(), msg);
        }
    
        public static <T> R<T> failed(ResultCode resultCode) {
            return restResult(null, resultCode.getCode(), resultCode.getMsg());
        }
        public static <T> R<T> failed(Integer code,String msg) {
            return restResult(null, code, msg);
        }
    
        public static <T> R<T> failed(T data) {
            return restResult(data, ResultCode.FAILED.getCode(), ResultCode.SUCCESS.getMsg());
        }
    
        public static <T> R<T> failed(T data, String msg) {
            return restResult(data, ResultCode.FAILED.getCode(), msg);
        }
    
        public int getCode() {
            return code;
        }
    
        public void setCode(int code) {
            this.code = code;
        }
    
        public boolean isSuccess() {
            return success;
        }
    
        public void setSuccess(boolean success) {
            this.success = success;
        }
    
        public String getMsg() {
            return msg;
        }
    
        public void setMsg(String msg) {
            this.msg = msg;
        }
    
        public T getData() {
            return data;
        }
    
        public void setData(T data) {
            this.data = data;
        }
    
        private static <T> R<T> restResult(T data, int code, String msg) {
            R<T> apiResult = new R<>();
            apiResult.setCode(code);
            apiResult.setSuccess(code == 1);
            apiResult.setData(data);
            apiResult.setMsg(msg);
            return apiResult;
        }
    
    
    }

## 3.3.在控制器中使用 ##

@RequestMapping
    @RestController
    public class DemoController {
    
        @GetMapping("/test1")
        public R<Object> test1(){
            return R.ok();
        }
    
        @GetMapping("/test2")
        public R<String> test2(){
            return R.ok("uuid");
        }
    
        @GetMapping("/test3")
        public R<List<String>> test3(){
            List<String> list = new ArrayList<>();
            return R.ok(list);
        }
    
        @GetMapping("/test4")
        public R<Object> test4(){
            return R.failed();
        }
    
        @GetMapping("/test5")
        public R<Object> test5(){
            return R.failed("暂时不能进行修改");
        }
    
        @GetMapping("/test6")
        public R<Object> test6(){
            return R.failed(ResultCode.USER_LOGIN_ERROR);
        }
        
        @GetMapping("/test7")
        public R<Object> test7(){
            return R.failed(500,"内部错误，请联系管理员");
        }
    }

# 4.补充 #

这个方案还有没有别的优化空间，当然是有的。例如：每个接口都要返回下R这个类，其实最主要的数据还是R的data数据对象，可以优化一下只返回数据对象，在拦截器里再包装一下数据对象。

如果大家有更好的方式可以在评论区交流一下