Java 如何设计 API 接口，实现统一格式返回？

fang·up·ad

已于 2022-03-21 11:29:19 修改

阅读量1.3k

点赞数 1

分类专栏：自学框架文章标签：接口返回格式 restful

于 2021-08-20 16:00:03 首次发布

原文链接：https://blog.csdn.net/qq_42046105/article/details/102854741

版权

自学框架专栏收录该内容

24 篇文章 1 订阅

订阅专栏

前言

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

一般系统的大致整体架构图如下：

需要说明的是，有些小伙伴会回复说，这个架构太简单了吧，太low了，什么网关啊，缓存啊，消息中间件啊，都没有。

因为老顾这篇主要介绍的是API接口，所以我们聚焦点，其他的模块小伙伴们自行去补充。

接口交互

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

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

后端服务器如何实现把数据返回给前端？

返回格式

后端返回给前端我们一般用JSON体方式，定义如下：

{
  #返回状态码
  code:integer,
  #返回信息描述
  message:string,
  #返回值
  data:object
}

CODE状态码

code返回状态码，一般小伙伴们是在开发的时候需要什么，就添加什么。

如接口要返回用户权限异常，我们加一个状态码为101吧，下一次又要加一个数据参数异常，就加一个102的状态码。这样虽然能够照常满足业务，但状态码太凌乱了

我们应该可以参考HTTP请求返回的状态码，下面是常见的HTTP状态码：

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

640?wx_fmt=jpeg

我们可以参考这样的设计，这样的好处就把错误类型归类到某个区间内，如果区间不够，可以设计成4位数。

#1000～1999 区间表示参数错误
#2000～2999 区间表示用户错误
#3000～3999 区间表示接口异常

这样前端开发人员在得到返回值后，根据状态码就可以知道，大概什么错误，再根据message相关的信息描述，可以快速定位。

ResultCode 枚举类

这个字段相对理解比较简单，就是发生错误时，如何友好的进行提示。一般的设计是和code状态码一起设计。状态码和信息就会一一对应，比较好维护。

package cn.fri.eb.cityguardfaceengine.resultWrapper;

public enum ResultCode {
    //仿照http状态码设置返回码
    SUCCESS(200, "请求成功"),
    FAIL(500, "请求失败"),
    HTTP_ERROR(250,"http请求错误");
    private Integer code;
    private String message;

    ResultCode(Integer code, String message) {
        this.code = code;
        this.message = message;
    }

    public Integer getCode() {
        return this.code;
    }

    public String getMessage() {
        return this.message;
    }
}

Response 返回类

我们要设计一个返回体类Response。我们可以在Response类中，加入静态方法来表示成功失败。

package cn.fri.eb.cityguardfaceengine.resultWrapper;

import com.alibaba.fastjson.JSONObject;
import lombok.Data;

import java.io.Serializable;

/**
 * @author fang
 */
@Data
public class Response implements Serializable {
    private int code;
    private String message;
    private long timestamp;
    private Object result;

    public Response(ResultCode resultCode, Object data) {
        this.code = resultCode.getCode();
        this.message = resultCode.getMessage();
        this.timestamp = System.currentTimeMillis();
        this.result = data;
    }

    public static Response success(Object data) {
        return new Response(ResultCode.SUCCESS, data);
    }

    public static Response fail(Object data) {
        return new Response(ResultCode.FAIL, data);
    }

    public static Response faileHttpError(Object data) {
        return new Response(ResultCode.HTTP_ERROR, data);
    }
}

优雅优化

上面我们看到在Response类中增加了静态方法，使得业务处理代码简洁了。但小伙伴们有没有发现这样有几个问题：

每个方法的返回都是Response封装对象，没有业务含义

在业务代码中，成功的时候我们调用Response.success，异常错误调用Response.fail。是不是很多余

我们最好的方式直接返回真实业务对象，最好不要改变之前的业务方式，如下图：

    @RequestMapping(value = "/check", method = RequestMethod.POST)
    public @ResponseBody
    Object faceCheck(@RequestParam String content) {
        JSONObject mpp_json = new JSONObject();
        return content_json;
    }

这个和我们平时的代码是一样的，非常直观，直接返回order对象，这样是不是很完美。

那实现方案是什么呢？

实现方案

小伙伴们怎么去实现是不是有点思路，在这个过程中，我们需要做几个事情

定义一个注解@ResponseResult，表示这个接口返回的值需要包装一下

拦截请求，判断此请求是否需要被@ResponseResult注解

核心步骤就是实现接口ResponseBodyAdvice和@ControllerAdvice，判断是否需要包装返回值，如果需要，就把Controller接口的返回值进行重写。

拦截器相关知识可参考文章

注解类

用来标记方法的返回值，注解接口类表示接口响应是否需要包装

package cn.fri.eb.cityguardfaceengine.resultWrapper;

import java.lang.annotation.*;

@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.METHOD, ElementType.TYPE})
@Documented
public @interface ResponseResult {
}

拦截器

拦截所有http请求，解析@ResponseResult注解，有此注解的接口表明响应需要包装，设置一个属性标记来表明需要包装，后续根据响应是有有此属性来决定是否包装。

package cn.fri.eb.cityguardfaceengine.resultWrapper;

import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Component;
import org.springframework.web.method.HandlerMethod;
import org.springframework.web.servlet.HandlerInterceptor;

import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.lang.reflect.Method;

/**
 * @author fang
 */
@Slf4j
@Component
public class ResponseResultInterceptor implements HandlerInterceptor {
    public static final String RESPONSE_RESULT_ANN = "RESPONSE-RESULT-ANN";

    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {
        if (handler instanceof HandlerMethod) {
            final HandlerMethod handlerMethod = (HandlerMethod) handler;
            final Class<?> clazz = handlerMethod.getBeanType();
            final Method method = handlerMethod.getMethod();
            //判断是否再类对象上加了注解 else if 判断是否再方法上加了注解
            if (clazz.isAnnotationPresent(ResponseResult.class)) {
                request.setAttribute(RESPONSE_RESULT_ANN, clazz.getAnnotation(ResponseResult.class));
            } else if (method.isAnnotationPresent(ResponseResult.class)) {
                request.setAttribute(RESPONSE_RESULT_ANN, method.getAnnotation(ResponseResult.class));
            }
        }
        return true;
    }
}

重写响应

看响应是否有标记来决定是否进行响应包装重写。

package cn.fri.eb.cityguardfaceengine.resultWrapper;

import com.alibaba.fastjson.JSON;
import com.alibaba.fastjson.JSONObject;
import com.alibaba.fastjson.JSONPObject;
import lombok.extern.slf4j.Slf4j;
import org.springframework.core.MethodParameter;
import org.springframework.http.MediaType;
import org.springframework.http.converter.HttpMessageConverter;
import org.springframework.http.server.ServerHttpRequest;
import org.springframework.http.server.ServerHttpResponse;
import org.springframework.web.bind.annotation.ControllerAdvice;
import org.springframework.web.context.request.RequestContextHolder;
import org.springframework.web.context.request.ServletRequestAttributes;
import org.springframework.web.servlet.mvc.method.annotation.ResponseBodyAdvice;

import javax.servlet.http.HttpServletRequest;

@Slf4j
@ControllerAdvice
public class ResponseResultHandler implements ResponseBodyAdvice<Object> {
    public static final String RESPONSE_RESULT_ANN = "RESPONSE-RESULT-ANN";

    @Override
    public boolean supports(MethodParameter methodParameter, Class<? extends HttpMessageConverter<?>> aClass) {
        ServletRequestAttributes sra = (ServletRequestAttributes) RequestContextHolder.getRequestAttributes();
        HttpServletRequest request = sra.getRequest();
        //判断请求是否有RESPONSE_RESULT_ANN标记
        ResponseResult responseResult = (ResponseResult) request.getAttribute(RESPONSE_RESULT_ANN);
        log.info("===============");
        //返回true 才会执行下面的方法，否则跳过不执行
        return responseResult != null ? false : true;
    }

     @Override
    public Object beforeBodyWrite(Object o, MethodParameter methodParameter, MediaType mediaType, Class<? extends HttpMessageConverter<?>> aClass, ServerHttpRequest serverHttpRequest, ServerHttpResponse serverHttpResponse) {
        //根据controller返回的响应类型 进行返回结果包装。controller可返回各种类型的exception或各类型数据 然后此处控制返回不同的响应：code、msg都不同
        if (o instanceof Exception) {
            return Response.fail(o);
            //如果自身产生异常。LinkedHashMap为http异常
        } else if (o instanceof LinkedHashMap) {
            LinkedHashMap lk = (LinkedHashMap) o;
            return Response.faileHttpError(o);
            //如果没有报错
        } else {
            return Response.success(o);
        }
    }
}

上面代码就是判断是否需要返回值包装，如果需要就包装。这里处理了正常成功的包装，和异常包装。异常也比较简单，只要判断body是否为异常类。

怎么做全局的异常处理，篇幅原因，老顾这里就不做介绍了，只要思路理清楚了，自行改造就行。

指定消息转换器

如果接口返回string类型，会报错 StringHttpMessageConverter cannot be cast to java.lang.String；如果返回JSON类型数据，那么此处不需要改变。

原因是返回值是String，Spring会使用StringHttpMessageConverter来处理返回体，但是我们定义的统一返回处理类将返回值String变成了Result.success(（String）)，是一个对象。导致类型转换失败。

解决：直接使用fastjson来序列化，fastjson处理的时候不会报错。
<dependency>
    <groupId>com.alibaba</groupId>
    <artifactId>fastjson</artifactId>
    <version>1.2.48</version>
</dependency>
package com.fri.audioengine.response;

import com.alibaba.fastjson.serializer.SerializerFeature;
import com.alibaba.fastjson.support.config.FastJsonConfig;
import com.alibaba.fastjson.support.spring.FastJsonHttpMessageConverter;
import org.springframework.boot.autoconfigure.http.HttpMessageConverters;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.converter.HttpMessageConverter;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

import java.util.List;

@Configuration
public class MyWebmvcConfiguration implements WebMvcConfigurer {

    @Bean
    public HttpMessageConverters custHttpMessageConverter() {
        return new HttpMessageConverters(new FastJsonHttpMessageConverter());
    }
}
参考

SpringBoot统一返回处理遇到的问题cannot be cast to java.lang.String - 简书

springboot自定义消息转换器HttpMessageConverter - 请叫我西毒 - 博客园

重写Controller

package cn.fri.eb.cityguardfaceengine.controller;

import cn.fri.eb.cityguardfaceengine.config.ApplicationMapping;
import cn.fri.eb.cityguardfaceengine.resultWrapper.ResponseResult;
import cn.fri.eb.cityguardfaceengine.utils.MyHttpClient;
import com.alibaba.fastjson.JSON;
import com.alibaba.fastjson.JSONObject;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.HttpStatus;
import org.springframework.web.bind.annotation.*;

import java.util.Map;

@ResponseResult
@RestController
@RequestMapping("/face")
public class FaceCheckController {

    @RequestMapping(value = "/check", method = RequestMethod.POST)
    public @ResponseBody
    Object faceCheck(@RequestParam String content) {
        JSONObject mpp_json = new JSONObject();

        //如果报错 直接返回指定类型的错误
         return new Exception("");

        //如果正常 就直接返回结果        
        return mpp_json ;
    }
}

在控制器类上或者方法体上加上@ResponseResult注解，这样就ok了，简单吧。到此返回的设计思路完成，是不是又简洁，又优雅。注意：需要返回时json才行。

这个方案还有没有别的优化空间，当然是有的。如：每次请求都要反射一下，获取请求的方法是否需要包装，其实可以做个缓存，不需要每次都需要解析。当然整体思路了解，小伙伴们就可以在此基础上面自行扩展。

fang·up·ad

关注

1
点赞
踩
2

收藏

觉得还不错? 一键收藏
1
评论
Java 如何设计 API 接口，实现统一格式返回？

前言在移动互联网，分布式、微服务盛行的今天，现在项目绝大部分都采用的微服务框架，前后端分离方式，（题外话：前后端的工作职责越来越明确，现在的前端都称之为大前端，技术栈以及生态圈都已经非常成熟；以前后端人员瞧不起前端人员，那现在后端人员要重新认识一下前端，前端已经很成体系了）一般系统的大致整体架构图如下：需要说明的是，有些小伙伴会回复说，这个架构太简单了吧，太low了，什么网关啊，缓存啊，消息中间件啊，都没有。因为老顾这篇主要介绍的是API接口，所以我..
复制链接

扫一扫

专栏目录