实战代码（八）：Springboot接口处理方法集合

最新推荐文章于 2024-02-24 20:07:21 发布

LY丶Smile

最新推荐文章于 2024-02-24 20:07:21 发布

阅读量475

点赞数 1

分类专栏：学习笔记文章标签： java spring spring boot

本文链接：https://blog.csdn.net/Tx_Smile/article/details/111054592

版权

学习笔记专栏收录该内容

20 篇文章 0 订阅

订阅专栏

一、理论基础

1.1 如何实现一个相对健壮的接口

接口设计应该假设所有的调用者都是不靠谱的，所以需要做全方位的防御措施并尽可能考虑到各种因素

正常访问

一个接口能正常访问是最基本的、最低的要求。不管调用者传递什么参数，接口应该都能给予良好的反馈，即使参数是错的。

当用户参数传递错误时，应该将错误信息反馈给用户，比如缺少参数或者参数格式不正确等

返回值统一化

标准化的返回格式，是绝对有利于同事间的感情发展的。
如果你一会返回个S,一会返回个B，你一定会被诅咒成这个返回值的拼接体的（人工狗头）

返回该返回的

尽可能的精简返回值，不要返回过多的冗余信息，比如调用方只需要两个字段，如果返回几十个字段，对于调用者来讲使用起来也不是很方便，而且还可能会暴露内部的业务逻辑。

报错信息全局处理

最常见的一个场景就是接口调用错误会将内部代码返给调用者，遇到过一个报名页面报错后，直接返回了几行代码，而且因为报错的很多都是关键逻辑，连代码注释的作者都能看到。

所以未知的错误最好统一处理下，比如“网络错误“等

及时更新的文档

写文档是最不受待见的一件事，那么一个自动化接口文档就很必要了，Swagger虽然繁琐，但是用起来很香。

而且可以设置默认的一些参数值，直接调试接口，真的香。

版本管理

不管会不会迭代，最好加个版本号。一来可以让接口看起来像”正规军”，二来可以有效应对随时到来的需求变更。

健壮的业务逻辑

这个就不多说了，相信每个人都有自己的一套方法论。

1.2 本实例集成的功能

接口异常全局处理
Knife4j接口文档
简单的token验证
Validator参数校验
返回值的统一化
解决跨域问题
AOP统计接口访问次数

1.3 示例源码地址

https://github.com/lysmile/spring-boot-demo/tree/master/spring-boot-api-handler-demo

二、接口异常全局处理

/**
 * 接口访问统一异常处理
 * - 当程序报错时，由此类进行统一处理
 * - 防止将程序内部错误暴露给用户
 * @author smile
 */
@RestControllerAdvice
@Slf4j
public class ControllerExceptionHandleAdvice {

    @ExceptionHandler(ValidatorRuntimeException.class)
    public CodeResult validationExceptionHandler(HttpServletRequest request, ValidatorRuntimeException e) {
        if (log.isDebugEnabled()) {
            log.error("接口[{}]请求发生[接口检验异常],错误信息:{}", request.getRequestURI(), e.getMessage());
        }
        return new CodeResult(ResponseEnum.REQUEST_PARAM_ERROR.getCode(), e.getMessage());
    }

    @ExceptionHandler(Exception.class)
    public CodeResult exceptionHandler(HttpServletRequest request, Exception e) {
        e.printStackTrace();
        log.error("接口[{}]请求发生异常,错误信息:{}", request.getRequestURI(), e.getMessage());
        return new CodeResult(ResponseEnum.SERVICE_ERROR);
    }

    @ExceptionHandler(TokenException.class)
    public CodeResult exceptionHandler(HttpServletRequest request, TokenException e) {
        if (log.isDebugEnabled()) {
            log.error("接口[{}]请求发生[token验证异常],错误信息:{}, token:{}", request.getRequestURI(), e.getMessage(), request.getHeader("token"));
        }
        return new CodeResult(ResponseEnum.TOKEN_ERROR.getCode(), e.getMessage());
    }
}

三、Knife4j接口文档

官网文档：https://xiaoym.gitee.io/knife4j/

3.1 依赖引入

<!-- knife4j api文档 -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>2.0.7</version>
</dependency>

3.2 配置文件

knife4j:
  # 开启增强配置
  enable: true
  # 开启Swagger的Basic认证功能,默认是false
  basic:
    enable: true
    username: smile
    password: 123456
  # 配置文档路径
  documents:
    -
      group: 0.1
      name: 说明文档
      # 某一个文件夹下所有的.md文件
      locations: classpath:markdown/*
    -
      group: 0.1
      name: 说明文档2
      # 某一个文件夹下所有的.md文件
      locations: classpath:markdown/*

3.3 配置文件

@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfig {

    private final OpenApiExtensionResolver openApiExtensionResolver;

    public Knife4jConfig(OpenApiExtensionResolver openApiExtensionResolver) {
        this.openApiExtensionResolver = openApiExtensionResolver;
    }

    @Bean(value = "defaultApi2")
    public Docket defaultApi2() {
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(new ApiInfoBuilder()
                        .title("Springboot API Handler")
                        .description("Springboot API 处理方法集成")
                        .version("0.1")
                        .build())
                //分组名称
                .groupName("0.1")
                .select()
                //这里指定Controller扫描包路径
                .apis(RequestHandlerSelectors.basePackage("com.smile.demo.apihandler.controller"))
                .paths(PathSelectors.any())
                .build()
                // 此处的0.1对应配置文件中的document-group
                .extensions(openApiExtensionResolver.buildExtensions("0.1"));
        return docket;
    }
}

3.4 简单应用

@Api(tags = "接口测试")
@RestController
@ApiSort(102)
@Slf4j
@RequestMapping("v0.1")
public class MainController {

    @ApiImplicitParam(name = "name", value = "姓名", required = true)
    @ApiOperation(value = "测试接口")
    @GetMapping("first-demo")
    public CodeResult firstDemo(@RequestParam(value = "name") String name) {
        log.info("!!成功进入接口, 参数是:[{}]", name);
        return new CodeResult(ResponseEnum.SUCCESS, name);
    }
}

完整代码可参考本实例源码

四、简单的token验证

本示例只实现了简单的token验证（验证用户和token是否过期）

优化方向

Springboot全家桶：集成Springboot Security
自实现功能：Jwt + Redis可实现较为完善的Token验证功能

4.1 依赖引入

<!-- java-jwt -->
<dependency>
    <groupId>com.auth0</groupId>
    <artifactId>java-jwt</artifactId>
    <version>3.10.3</version>
</dependency>

4.2 配置文件

my:
  security:
    username: api
    password: 123456

4.3 Jwt工具类

@Component
public class JwtUtils {

    @Value("${my.security.username}")
    private String defaultUsername;
    @Value("${my.security.password}")
    private String defaultPassword;

    /**
     * 过期时间，单位毫秒
     * - 10分钟
     */
    private static final long EXPIRE_TIME = 1000 * 60 * 10;

    public TokenInfo createToken(String username, String password) throws TokenException {
        if (!username.equals(defaultUsername) || !password.equals(defaultPassword)) {
            throw new TokenException("用户名或密码不正确");
        }
        //设置头信息
        HashMap<String, Object> header = new HashMap<>(2);
        header.put("typ", "JWT");
        header.put("alg", "HMAC256");
        long expireAt = System.currentTimeMillis() + EXPIRE_TIME;
        String token = JWT.create()
                .withHeader(header)
                // 存入需要保存在token的信息
                .withAudience(username)
                // 过期时间
                .withExpiresAt(new Date(expireAt))
                .sign(Algorithm.HMAC256(password));
        return new TokenInfo(token, expireAt);
    }

    public void verify(String token) throws TokenException {
        Algorithm algorithm = Algorithm.HMAC256(defaultPassword);
        JWTVerifier verifier = JWT.require(algorithm).build();
        try {
            DecodedJWT jwt = verifier.verify(token);
            if(!defaultUsername.equals(jwt.getAudience().get(0))) {
                throw new TokenException("用户不存在");
            }
        } catch(TokenExpiredException e) {
            throw new TokenException("token已过期");
        } catch(Exception e) {
            e.printStackTrace();
            throw new TokenException("token无效");
        }
    }
}

4.4 拦截器

4.4.1 拦截器功能实现

/**
 * 拦截器
 * - 验证token
 * @author yangjunqiang
 */
@Component
@Slf4j
public class UserTokenInterceptor implements HandlerInterceptor {

    private final JwtUtils jwtUtils;

    public UserTokenInterceptor(JwtUtils jwtUtils) {
        this.jwtUtils = jwtUtils;
    }

    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {
        log.info("！！进入拦截器方法");
        String token = request.getHeader("token");
        if (StringUtils.isBlank(token)) {
            throw new TokenException("请传入正确的token");
        }
        jwtUtils.verify(token);
        return true;
    }


    @Override
    public void postHandle(HttpServletRequest request, HttpServletResponse response, Object handler, ModelAndView modelAndView) throws Exception {

    }


    @Override
    public void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex) throws Exception {

    }
}

4.4.2注册拦截器

@Component
public class UserTokenAppConfig implements WebMvcConfigurer {


    private final UserTokenInterceptor userTokenInterceptor;

    public UserTokenAppConfig(UserTokenInterceptor userTokenInterceptor) {
        this.userTokenInterceptor = userTokenInterceptor;
    }


    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(userTokenInterceptor)
                // 配置需要被拦截的接口
                // 注意此处是controller中的路径，配置文件中的server.servlet.context-path不能在此处加上，否则拦截器不会生效
                .addPathPatterns("/v0.1/**")
                // 不被拦截的接口
                .excludePathPatterns("/token/get")
        ;
    }
}

五、Validator参数校验

5.1 依赖引入

<!-- 参数检验 -->
<dependency>
    <groupId>org.hibernate.validator</groupId>
    <artifactId>hibernate-validator</artifactId>
</dependency>

5.2 快速失败配置（可选）

/**
 * 参数校验快速失败配置
 * - 此模式下只要发现一个参数不匹配便会快速返回错误
 * @author smile
 */
@Configuration
public class ValidatorConfig {
    @Bean
    public Validator validator() {
        ValidatorFactory validatorFactory = Validation.byProvider( HibernateValidator.class )
                .configure()
                .failFast( true )
                .buildValidatorFactory();
        Validator validator = validatorFactory.getValidator();
        return validator;
    }
}

5.3 工具类

/**
 * 参数验证通用方法提取
 * @author smile
 */
public class ValidatorUtils {

    /**
     * controller bindingResult处理
     * @param bindingResult 参数验证结果集
     */
    public static void handleBindingResult(BindingResult bindingResult) {
        if (bindingResult.hasErrors()) {
            throw new ValidatorRuntimeException(bindingResult.getAllErrors().get(0).getDefaultMessage());
        }
    }
}

5.4 简单应用

关键词：@Validated、BindingResult

配合全局异常处理一块使用

@PostMapping("get")
@ApiOperationSupport(author = "smile")
@ApiOperation(value = "获取token")
public CodeResult getToken(@RequestBody @Validated User user, BindingResult bindingResult) throws TokenException {
    ValidatorUtils.handleBindingResult(bindingResult);
    return new CodeResult(ResponseEnum.SUCCESS, JSON.toJSON(jwtUtils.createToken(user.getUsername(), user.getPassword())));
}

六、接口返回值统一化

6.1 接口返回实体定义

@Data
public class CodeResult {

	private String errCode;
	private String errMsg;
	private Object data;
	
	public CodeResult() { }
	
	public CodeResult(String errCode, String errMsg) {
		this.errCode = errCode;
		this.errMsg = errMsg;
	}
	
	public CodeResult(ResponseEnum response) {
		this.errCode = response.getCode();
		this.errMsg = response.getMsg();
	}
	
	public CodeResult(ResponseEnum response, Object data) { 
		this.errCode = response.getCode();
		this.errMsg = response.getMsg();
		this.data = data;
	}
	
}

定义枚举

/**
 * 错误码
 * 0 ：成功
 * 1*：业务内自定义错误码
 * 2*：
 * 3*：
 * 4*：网络错误
 * 5*：系统内部错误，包含代码执行异常等
 * @author smile
 *
 */
public enum ResponseEnum {

	/**
	 * 请求成功
	 */
	SUCCESS("0", "success"),
	/**
	 * 请求参数错误
	 */
	REQUEST_PARAM_ERROR("1001", "参数错误"),
	/**
	 * token验证失败
	 */
	TOKEN_ERROR("1002", "token验证失败"),
	/**
	 * 服务内部异常，包括代码执行错误及一些不确定错误
	 */
	SERVICE_ERROR("5001", "服务异常，请稍后再试！")
	;
	
	private String code;
	private String msg;
	
	ResponseEnum(String code, String msg) {
		this.code = code;
		this.msg = msg;
	}
	
	public String getCode() {
		return code;
	}
	public void setCode(String code) {
		this.code = code;
	}
	public String getMsg() {
		return msg;
	}
	public void setMsg(String msg) {
		this.msg = msg;
	}
	
}

七、解决跨域问题

/**
 * 解决跨域问题
 * @author smile
 */
@Configuration
public class CorsConfig {
    @Bean
    public CorsFilter corsFilter() {
        final UrlBasedCorsConfigurationSource urlBasedCorsConfigurationSource = new UrlBasedCorsConfigurationSource();
        final CorsConfiguration corsConfiguration = new CorsConfiguration();
        /*是否允许请求带有验证信息*/
        corsConfiguration.setAllowCredentials(true);
        /*允许访问的客户端域名*/
        corsConfiguration.addAllowedOrigin("*");
        /*允许服务端访问的客户端请求头*/
        corsConfiguration.addAllowedHeader("*");
        /*允许访问的方法名,GET POST等*/
        corsConfiguration.addAllowedMethod("*");
        urlBasedCorsConfigurationSource.registerCorsConfiguration("/**", corsConfiguration);
        return new CorsFilter(urlBasedCorsConfigurationSource);
    }
}

八、AOP统计接口访问次数

详见实战代码（四）：Springboot AOP实现接口访问次数统计

LY丶Smile

关注

1
点赞
踩
2

收藏

觉得还不错? 一键收藏
0
评论
实战代码（八）：Springboot接口处理方法集合

一、理论基础1.1 如何实现一个相对健壮的接口接口设计应该假设所有的调用者都是不靠谱的，所以需要做全方位的防御措施并尽可能考虑到各种因素正常访问一个接口能正常访问是最基本的、最低的要求。不管调用者传递什么参数，接口应该都能给予良好的反馈，即使参数是错的。当用户参数传递错误时，应该将错误信息反馈给用户，比如缺少参数或者参数格式不正确等返回值统一化标准化的返回格式，是绝对有利于同事间的感情发展的。如果你一会返回个S,一会返回个B，你一定会被诅咒成这个返回值的拼接体的（人工狗头）返回该返回的尽
复制链接

扫一扫