1、一个单纯的springboot web工程

大家都知道springboot开箱即用的特性，一个springboot创建起来之后，不用做任何配置，只写一个启动类就可以，最多再加一个controller定义个接口，像这样：

@RestController
@RequestMapping("/api/any")
public class AnyController {

    @GetMapping("/list")
    public Map list() {
        Map ret = new HashMap();
        SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss.SSS");
        ret.put("time", sdf.format(new Date()));
        return ret;
    }
}

启动之后接口就可以访问了，但是，真有这么简单吗？前端同事对你这个单纯的接口能够满意吗？

前端同事跟我说，她比较关心以下几个问题：

1、接口有统一返回吗？返回的字段是code-data，还是status-resp，还是error-code-or-data？
2、除了正常情况的返回，异常情况但非500，是怎么返回的？http status code也会是除了200之外的值吗？
3、传参是时间的话，是传毫秒吗？
4、返回是时间的话，是返回毫秒吗？
5、一个参数传空或者不传，结果是一样的吗？
6、后端能给跨一下域吗？
7、双人联调时你能快速从日志里找到我传的什么参吗？难道还要人家自己F12吗？
8、要是有个long字段，是返回string还是怎么？考虑丢失精度问题了吗？
9、你接口文档怎么给我？是swagger吗？
10、分页的参数和返回是统一的吗？
11、如果返回错误信息，后端会直接返回国际化的文本吗？还是要前端自己控制国际化？

我说，不要着急，你说的问题，确实存在，是我冒失了，这周就加班着重解决这些问题，除了国际化的问题，这个以后再说。

2、统一返回规格

在commons-model里，我们定义了一个AnyResponse，现在就是要让所有接口都返回这个格式，就算方法的返回值不是AnyResponse也要强行封装成AnyResponse返回。

package org.danger.dy.common.web.response;

import java.lang.reflect.Method;
import java.util.concurrent.atomic.AtomicInteger;

import com.danger.dy.common.models.response.AnyResponse;
import lombok.extern.slf4j.Slf4j;
import org.springframework.core.MethodParameter;
import org.springframework.core.Ordered;
import org.springframework.core.annotation.Order;
import org.springframework.http.HttpStatus;
import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.http.converter.json.MappingJacksonValue;
import org.springframework.http.server.ServerHttpRequest;
import org.springframework.http.server.ServerHttpResponse;
import org.springframework.web.bind.annotation.RestControllerAdvice;
import org.springframework.web.servlet.mvc.method.annotation.AbstractMappingJacksonResponseBodyAdvice;


/**
 * 统一接口返回规格
 */
@Slf4j
@Order(value = Ordered.HIGHEST_PRECEDENCE)
@RestControllerAdvice
public class RestResponseWrapAdvice extends AbstractMappingJacksonResponseBodyAdvice {

    private AtomicInteger responseCount = new AtomicInteger(0);

    @Override
    protected void beforeBodyWriteInternal(MappingJacksonValue bodyContainer,
                                           MediaType contentType,
                                           MethodParameter returnType,
                                           ServerHttpRequest request,
                                           ServerHttpResponse response) {
        Method method = returnType.getMethod();
        if (method != null && MediaType.APPLICATION_JSON.equals(contentType)) {
            Object returnValue = bodyContainer.getValue();
            if (method.getReturnType() == ResponseEntity.class) {
                log.info("接口返回ResponseEntity，不进行任何修改");
                return;
            }
            if (returnValue instanceof AnyResponse) {
                response.setStatusCode(HttpStatus.valueOf(((AnyResponse) returnValue).getCode()));
            } else {
                bodyContainer.setValue(AnyResponse.ok(returnValue));
            }
            response.getHeaders().add("x-response-sequence", responseCount.incrementAndGet() + "");
        }
    }

}

逻辑是不是一目了然

如果是404,500，spring自己会返回ResponseEntity，就不用拦截了。
如果接口方法直接返回AnyResponse，那就将http status code设置为AnyResponse的code字段。
如果接口方法返回的是随意的对象，则包装为AnyResponse，保持http status code为默认200。
在响应中加一个header：x-response-sequence，没什么大用，暂时只是做个标记证明响应被拦截过。

3、统一异常处理

有了上面的统一响应之后，接口方法可以直接返回AnyErrorResponse，但接口调用各种service各种组件时，总不能期待所有方法都返回AnyResponse吧，肯定是要抛出异常的，我们在commons-model里定义了LogicException，但当真抛出LogicException时，我们还没有做任何处理，接口响应的只能是500，下面就要对异常拦截一下。

package org.danger.dy.common.web.error;

import java.io.IOException;
import java.nio.charset.StandardCharsets;

import javax.servlet.Filter;
import javax.servlet.FilterChain;
import javax.servlet.ServletException;
import javax.servlet.ServletRequest;
import javax.servlet.ServletResponse;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

import com.danger.dy.common.models.exceptions.LogicException;
import com.danger.dy.common.models.response.AnyErrorResponse;
import com.danger.dy.common.models.response.AnyResponse;
import com.fasterxml.jackson.databind.ObjectMapper;
import lombok.extern.slf4j.Slf4j;
import org.apache.commons.lang3.exception.ExceptionUtils;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.core.Ordered;
import org.springframework.core.PriorityOrdered;
import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpStatus;
import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;
import org.springframework.web.context.request.WebRequest;
import org.springframework.web.servlet.mvc.method.annotation.ResponseEntityExceptionHandler;


/**
 * 接口异常统一拦截
 */
@Slf4j
@RestControllerAdvice
public class ResponseExceptionHandler
        extends ResponseEntityExceptionHandler
        implements PriorityOrdered, Filter {

    private final ObjectMapper objectMapper;

    @Autowired
    public ResponseExceptionHandler(ObjectMapper objectMapper) {
        this.objectMapper = objectMapper;
    }


    @ExceptionHandler(LogicException.class)
    protected AnyResponse onBizException(LogicException bizException,
                                         HttpServletRequest request) {
        // 将异常包装为AnyResponse
        AnyErrorResponse ret = AnyResponse.error(bizException.getStatusCode(), bizException.getLabel());
        return ret;
    }

    @Override
    protected ResponseEntity<Object> handleExceptionInternal(Exception ex, Object body,
                                                             HttpHeaders headers,
                                                             HttpStatus status, WebRequest request) {
        AnyErrorResponse<?> ret = AnyResponse.error(status.value(), status.toString());
        return ResponseEntity.status(status.value()).body(ret);
    }

    /**
     * 非可预期的异常，也包装成AnyResponse
     */
    @ExceptionHandler(Exception.class)
    protected AnyResponse onException(Exception exception, HttpServletRequest request) {
        log.error("Unexpected exception: ", exception);
        AnyErrorResponse ret = AnyResponse.error(500, ExceptionUtils.getMessage(exception));
        return ret;
    }

    @Override
    public int getOrder() {
        return Ordered.HIGHEST_PRECEDENCE;
    }

    @Override
    public void doFilter(ServletRequest servletRequest, ServletResponse servletResponse, FilterChain filterChain)
            throws IOException, ServletException {
        try {
            filterChain.doFilter(servletRequest, servletResponse);
        } catch (LogicException bizException) {
            handleFilterBizException(bizException, servletRequest, servletResponse);
        }
    }

    /**
     * filter里抛出的异常处理
     */
    private void handleFilterBizException(LogicException bizException, ServletRequest servletRequest, ServletResponse servletResponse) {
        try {
            HttpServletRequest request = (HttpServletRequest) servletRequest;
            HttpServletResponse response = (HttpServletResponse) servletResponse;
            AnyResponse<?> errorResponse = onBizException(bizException, request);
            response.setStatus(errorResponse.getCode());
            response.setCharacterEncoding(StandardCharsets.UTF_8.name());
            response.setContentType(MediaType.APPLICATION_JSON_VALUE);
            response.getWriter().write(objectMapper.writeValueAsString(errorResponse));
        } catch (Exception e) {
            log.error("logic error: ", bizException);
            log.error("response error: ", e);
        }
    }
}

4、我们再来写一个接口试试


@RestController
@RequestMapping("/api/any")
public class AnyController {

    @GetMapping("/test")
    public AnyResponse<AnyObject> test(@RequestParam(name = "want") String want) {
        if (want.equals("500")) {
            throw new RuntimeException("who's your daddy");
        } else if (want.equals("406")) {
            throw new LogicException(406, "greed is good");
        } else if (want.equals("error_response")) {
            return AnyResponse.error(406, "the mountain is high");
        } else {
            SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss.SSS");
            return AnyResponse.ok(AnyObject.of(sdf.format(new Date())));
        }
    }
}

请求1：不带任何参数，返回

HTTP/1.1 400 

{
  "code": 400,
  "message": "400 BAD_REQUEST"
}

请求2：抛出RuntimeException，返回

HTTP/1.1 500 

{
  "code": 500,
  "message": "RuntimeException: who's your daddy"
}

请求3：抛出LogicException，返回

HTTP/1.1 406 

{
  "code": 406,
  "message": "greed is good"
}

请求4：抛出LogicException，返回

HTTP/1.1 406 

{
  "code": 406,
  "message": "the mountain is high"
}

请求5：正常

HTTP/1.1 200 

{
  "code": 200,
  "data": {
    "result": "2023-04-15 23:08:04.952"
  }
}

基本能够实现返回与异常的统一处理。

5、接口请求日志

记录日志的重要性应该不需要多说了，作为一个程序员，没日志不行，日志多了也不行，程序员与日志是相辅相成相爱相杀，日志怎么查，在这里不重要，首先要确定的事：你记录了日志。

在我这些年无数次的经过同事身后，有那么三两次，我看到同事在查：spring打印接口请求参数。

这一节就讲这个，打印请求参数当然主要是为了排查，但参数有时可能不在get和post参数里，而是在request body里，即需要去读http请求的输入流，而流默认情况下又只能读一次，那首先就是要解决让流可以重复读取的问题。

#保证请求的InputStream可以被重复读取

基本思路就是把原始body读出来，保存下来，再对外提供一个可以反复读取的InputStream，看代码：

package org.danger.dy.common.web.logging;

import java.io.BufferedReader;
import java.io.ByteArrayInputStream;
import java.io.IOException;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.nio.charset.Charset;

import javax.servlet.Filter;
import javax.servlet.FilterChain;
import javax.servlet.FilterConfig;
import javax.servlet.ReadListener;
import javax.servlet.ServletException;
import javax.servlet.ServletInputStream;
import javax.servlet.ServletRequest;
import javax.servlet.ServletResponse;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletRequestWrapper;

import lombok.extern.slf4j.Slf4j;
import org.apache.commons.lang3.StringUtils;
import org.apache.commons.lang3.exception.ExceptionUtils;
import org.springframework.http.MediaType;

@Slf4j
public class DyRepeatableFilter implements Filter {
    @Override
    public void init(FilterConfig filterConfig) throws ServletException {

    }

    @Override
    public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain)
            throws IOException, ServletException {
        ServletRequest requestWrapper = null;
        if ((request instanceof HttpServletRequest)
                && StringUtils.startsWithIgnoreCase(request.getContentType(), MediaType.APPLICATION_JSON_VALUE)) {
            requestWrapper = new RepeatedlyRequestWrapper((HttpServletRequest) request, response);
        }

        if (null == requestWrapper) {
            chain.doFilter(request, response);
        } else {
            chain.doFilter(requestWrapper, response);
        }
    }

    @Override
    public void destroy() {

    }


    /**
     * 可重复读取inputStream的request
     */
    public static class RepeatedlyRequestWrapper extends HttpServletRequestWrapper {
        private final byte[] body;

        public RepeatedlyRequestWrapper(HttpServletRequest request, ServletResponse response) throws IOException {
            super(request);
            request.setCharacterEncoding("UTF-8");
            response.setCharacterEncoding("UTF-8");

            body = getBodyString(request).getBytes("UTF-8");
        }

        @Override
        public BufferedReader getReader() throws IOException {
            return new BufferedReader(new InputStreamReader(getInputStream()));
        }

        @Override
        public ServletInputStream getInputStream() throws IOException {
            final ByteArrayInputStream bais = new ByteArrayInputStream(body);
            return new ServletInputStream() {
                @Override
                public int read() throws IOException {
                    return bais.read();
                }

                @Override
                public int available() throws IOException {
                    return body.length;
                }

                @Override
                public boolean isFinished() {
                    return false;
                }

                @Override
                public boolean isReady() {
                    return false;
                }

                @Override
                public void setReadListener(ReadListener readListener) {

                }
            };
        }


        public static String getBodyString(ServletRequest request) {
            StringBuilder sb = new StringBuilder();
            BufferedReader reader = null;
            try (InputStream inputStream = request.getInputStream()) {
                reader = new BufferedReader(new InputStreamReader(inputStream, Charset.forName("UTF-8")));
                String line = "";
                while ((line = reader.readLine()) != null) {
                    sb.append(line);
                }
            } catch (IOException e) {
                log.error("filter error", e);
                throw new RuntimeException(e);
            } finally {
                if (reader != null) {
                    try {
                        reader.close();
                    } catch (IOException e) {
                        log.error(ExceptionUtils.getMessage(e));
                    }
                }
            }
            return sb.toString();
        }
    }

}

#打印请求日志

也是通过filter解决。

package org.danger.dy.common.web.logging;

import java.io.BufferedReader;
import java.io.ByteArrayInputStream;
import java.io.IOException;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.nio.charset.Charset;

import javax.servlet.Filter;
import javax.servlet.FilterChain;
import javax.servlet.FilterConfig;
import javax.servlet.ReadListener;
import javax.servlet.ServletException;
import javax.servlet.ServletInputStream;
import javax.servlet.ServletRequest;
import javax.servlet.ServletResponse;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletRequestWrapper;

import lombok.extern.slf4j.Slf4j;
import org.apache.commons.lang3.StringUtils;
import org.apache.commons.lang3.exception.ExceptionUtils;
import org.springframework.http.MediaType;

@Slf4j
public class DyRepeatableFilter implements Filter {
    @Override
    public void init(FilterConfig filterConfig) throws ServletException {

    }

    @Override
    public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain)
            throws IOException, ServletException {
        ServletRequest requestWrapper = null;
        if ((request instanceof HttpServletRequest)
                && StringUtils.startsWithIgnoreCase(request.getContentType(), MediaType.APPLICATION_JSON_VALUE)) {
            requestWrapper = new RepeatedlyRequestWrapper((HttpServletRequest) request, response);
        }

        if (null == requestWrapper) {
            chain.doFilter(request, response);
        } else {
            chain.doFilter(requestWrapper, response);
        }
    }

    @Override
    public void destroy() {

    }


    /**
     * 可重复读取inputStream的request
     */
    public static class RepeatedlyRequestWrapper extends HttpServletRequestWrapper {
        private final byte[] body;

        public RepeatedlyRequestWrapper(HttpServletRequest request, ServletResponse response) throws IOException {
            super(request);
            request.setCharacterEncoding("UTF-8");
            response.setCharacterEncoding("UTF-8");

            body = getBodyString(request).getBytes("UTF-8");
        }

        @Override
        public BufferedReader getReader() throws IOException {
            return new BufferedReader(new InputStreamReader(getInputStream()));
        }

        @Override
        public ServletInputStream getInputStream() throws IOException {
            final ByteArrayInputStream bais = new ByteArrayInputStream(body);
            return new ServletInputStream() {
                @Override
                public int read() throws IOException {
                    return bais.read();
                }

                @Override
                public int available() throws IOException {
                    return body.length;
                }

                @Override
                public boolean isFinished() {
                    return false;
                }

                @Override
                public boolean isReady() {
                    return false;
                }

                @Override
                public void setReadListener(ReadListener readListener) {

                }
            };
        }


        public static String getBodyString(ServletRequest request) {
            StringBuilder sb = new StringBuilder();
            BufferedReader reader = null;
            try (InputStream inputStream = request.getInputStream()) {
                reader = new BufferedReader(new InputStreamReader(inputStream, Charset.forName("UTF-8")));
                String line = "";
                while ((line = reader.readLine()) != null) {
                    sb.append(line);
                }
            } catch (IOException e) {
                log.error("filter error", e);
                throw new RuntimeException(e);
            } finally {
                if (reader != null) {
                    try {
                        reader.close();
                    } catch (IOException e) {
                        log.error(ExceptionUtils.getMessage(e));
                    }
                }
            }
            return sb.toString();
        }
    }

}

加载filter

上面定义的两个filter并非可以被自动扫描并加载的Bean，需要配置：


@Configuration
@ComponentScan
@AutoConfigureBefore({WebMvcAutoConfiguration.class})
public class DyWebAutoConfiguration {

    @Bean(name = "loggingFilter")
    public FilterRegistrationBean<DyLoggingFilter> loggingFilterRegisterBean() {
        FilterRegistrationBean<DyLoggingFilter> filterRegistrationBean = new FilterRegistrationBean<>();
        filterRegistrationBean.setFilter(new DyLoggingFilter());
        filterRegistrationBean.addUrlPatterns("/*");
        filterRegistrationBean.setName("loggingFilter");
        filterRegistrationBean.setOrder(FilterRegistrationBean.HIGHEST_PRECEDENCE + 1); //order的数值越小 则优先级越高
        return filterRegistrationBean;
    }

    @Bean(name = "repeatableFilter")
    public FilterRegistrationBean<DyRepeatableFilter> repeatableFilter() {
        FilterRegistrationBean<DyRepeatableFilter> registration = new FilterRegistrationBean<>();
        registration.setFilter(new DyRepeatableFilter());
        registration.addUrlPatterns("/*");
        registration.setName("repeatableFilter");
        registration.setOrder(FilterRegistrationBean.HIGHEST_PRECEDENCE);
        return registration;
    }
}

看效果

再发起请求时，请求日志打印出来是这样:

>>>[request finished: /api/any/test, from 127.0.0.1](耗时5ms) params={"want":"406dd"}, body=null, response status=200

上面留了一点儿瑕疵，就是对日志行为进行控制，控制的方式就是在yml文件里进行配置，这部分内容我们打算放到最后对dy lib进行统一配置时再考虑，这里不做过多深究。

6、与前端沟通

谢谢同事的肯定，我一定会继续努力，争取获得与小姐姐一块加班的资格。

7、总结

今天就到这里了，对于前端提出的问题，我们并不打算一次性进行解决，编程讲究迭代、渐进、细水长流，只有这样，才能不断精进，并通过与同事的反复沟通，将细节打磨到极致。

4、springboot脚手架-常用web配置

1、一个单纯的springboot web工程

2、统一返回规格

3、统一异常处理

4、我们再来写一个接口试试

5、接口请求日志

#保证请求的InputStream可以被重复读取

#打印请求日志

加载filter

看效果

6、与前端沟通

7、总结

相关推荐

取消回复欢迎你发表评论:

Google 黑客常用搜索语句一览原力计划

npx简介（npxvip是哪国的）

在 Android 模拟器上运行 ARM 应用（android模拟器原理）

GB28181,B接口协议之SIPRTSPRTPRTMP协议从入门到精通

手机实时提取SIM卡打电话的信令和声音-辅助外设与商用通话方案

安装使用Hoppscotch构建API请求访问与测试

轻松转换!AppleNumbers到Excel的快捷教程

Python自动化办公——后台截图（python 自动截图）

电脑端腾讯文档如何导出excel

网络流媒体经典开源软件宝典webRTC, FFMpeg, SIP_流媒体开发教程

4、springboot脚手架-常用web配置

1、一个单纯的springboot web工程

2、统一返回规格

3、统一异常处理

4、我们再来写一个接口试试

5、接口请求日志

#保证请求的InputStream可以被重复读取

#打印请求日志

加载filter

看效果

6、与前端沟通

7、总结

相关推荐

取消回复欢迎 你 发表评论:

Google 黑客常用搜索语句一览 原力计划

npx简介（npxvip是哪国的）

在 Android 模拟器上运行 ARM 应用（android模拟器原理）

GB28181,B接口协议之SIPRTSPRTPRTMP协议从入门到精通

手机实时提取SIM卡打电话的信令和声音-辅助外设与商用通话方案

安装使用Hoppscotch构建API请求访问与测试

轻松转换!AppleNumbers到Excel的快捷教程

Python自动化办公——后台截图（python 自动截图）

电脑端腾讯文档如何导出excel

网络流媒体经典开源软件宝典webRTC, FFMpeg, SIP_流媒体开发教程

取消回复欢迎你发表评论:

Google 黑客常用搜索语句一览原力计划