项目集成swagger，并暴露指定端点给swagger

项目集成swagger

一：思考:

1.swagger解决了我们什么问题？

传统开发中，我们在开发完成一个接口后，为了测试我们的接口，我们通常会编写单元测试，以测试我们的接口的可用性，或者用postman等第三方接口测试工具进行测试，但是这也有一些弊端，我们需要为接口准备测试数据，但有时，数据量较大时，前期准备工作可能相当耗时
​
​

2.除了用于接口测试，我们还能利用它做些什么有意义的事呢？

在项目的开发过程中，我们通常会用到大量的定时任务；
a.分布式环境：quartz
b.单机环境：有spring提供的schedule 或者用线程（局限性较大）
因为公司没有引入调度中心，没有一个统一的地方对项目中的定时任务进行统一的管理，所以需要每个项目集成自己的调度框架
​

例如：我现在有一个需求，是每天早上7点的时候，对昨日告警发送一个统计日报，最简单的做法是引入@schedule（cron="0 0 7 * * ?"）

我们经过本地的辛苦开发测试，一切正常，可是当我们将项目发布到QA环境，发现自己无法对这个定时任务的代码进行有效测试，如果需要观察我们甚至需要等到明天早上7点

问题的根源在于 Schedule 方法基于时间触发，如果使其暴露出来，能够手工触发，将大大增加灵活性。

我通过对其定制，可以暴露使用到了schedule的地方，并提供手动触发，

二：集成swagger

1.引入依赖

<dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.7.0</version>
    </dependency>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.7.0</version>
    </dependency>

2.启用swagger

在配置类上加上注解@EnableSwagger2

三：为定时调度任务schedule暴露接口

#### 1.HandlerMapping 扩展

新建 ScheduleMethodHandlerMapping 继承自 RequestMappingInfoHandlerMapping ，实现 HandlerMapping 接口。

​

public class ScheduleMethodHandlerMapping
        extends RequestMappingInfoHandlerMapping
        implements HandlerMapping{
    /**
     * 包含@Scheduled注解方法的bean为handler
     * @param beanType
     * @return
     */
    @Override
    protected boolean isHandler(Class<?> beanType) {
        return Arrays.asList(MethodUtil.getMethods(beanType)).stream()
                    .anyMatch(method -> method.getAnnotation(Scheduled.class) != null);
    }
​
    /**
     * 处理@Scheduled标注方法，生成对于的RequestMappingInfo
     * @param method
     * @param handlerType
     * @return
     */
    @Override
    protected RequestMappingInfo getMappingForMethod(Method method, Class<?> handlerType) {
        if (method.getAnnotation(Scheduled.class) == null){
            return null;
        }
        return RequestMappingInfo.paths("/schedule/" + handlerType.getSimpleName() + "/" + method.getName())
                .methods(RequestMethod.GET)
                .build();
    }
​
    /**
     * 提高该HandlerMapping在HandlerMapping中的顺序，使其能优先处理
     * @return
     */
    @Override
    public int getOrder() {
        return 1;
    }
}

2.HandlerAdapter 扩展

andlerAdapter 扩展主要解决 Schedule 方法的执行问题。

带有 @Scheduled 注解的 Method 方法，需要单独的 HandlerAdapter 进行处理，并将处理结果通过 json 方式返回。

新建 ScheduleMethodHandlerAdapter

ScheduleMethodHandlerAdapter 继承自 AbstractHandlerMethodAdapter ，实现 HandlerAdapter 接口。

public class ScheduleMethodHandlerAdapter
        extends AbstractHandlerMethodAdapter
        implements HandlerAdapter {
​
    /**
     * 支持使用@Scheduled标准的handlerMethod对象
     * @param handlerMethod
     * @return
     */
    @Override
    protected boolean supportsInternal(HandlerMethod handlerMethod) {
        return handlerMethod.hasMethodAnnotation(Scheduled.class);
    }
​
    /**
     * 调用HandlerMethod方法，并返回json视图
     * @param request
     * @param response
     * @param handlerMethod
     * @return
     * @throws Exception
     */
    @Override
    protected ModelAndView handleInternal(HttpServletRequest request, HttpServletResponse response, HandlerMethod handlerMethod) throws Exception {
​
        Map<String, Object> data = Maps.newHashMap();
        data.put("service", handlerMethod.getBeanType().getSimpleName());
        data.put("method", handlerMethod.getMethod().getName());
        Stopwatch stopwatch = Stopwatch.createStarted();
        try {
            // 调用HandleMethod方法
            handlerMethod.getMethod().invoke(handlerMethod.getBean());
            stopwatch.stop();
            data.put("result", "success");
        }catch (Exception e){
            data.put("result", "error");
            data.put("exception", e.toString());
        }finally {
            data.put("cost", stopwatch.elapsed(TimeUnit.MILLISECONDS) + "ms");
​
        }
        // 返回Json视图
        return new ModelAndView(new MappingJackson2JsonView(), data);
    }
​
    @Override
    protected long getLastModifiedInternal(HttpServletRequest request, HandlerMethod handlerMethod) {
        return 0;
    }
​
    /**
     * 提高在HandlerAdapter列表中的顺序，以优先处理
     * @return
     */
    @Override
    public int getOrder() {
        return 0;
    }
}

3.与 Spring Boot 集成

ScheduleMethodHandlerMapping 和 ScheduleMethodHandlerAdapter 开发完成后，我们需要将其与 Spring Boot 进行集成，并通过参数控制是否启用。

新建 ScheduleEndpointConfiguration

新建 ScheduleEndpointConfiguration 配置类，对 ScheduleMethodHandlerMapping 和 ScheduleMethodHandlerAdapter 进行注册。

/**
 * 根据配置属性控制是否启用该配置。
 * <br />
 * spring.schedule.endpoint.enabled = true 启用配置 <br />
 * spring.schedule.endpoint.enabled = false 禁用配置 <br />
 */
@ConditionalOnProperty(prefix = "spring.schedule.endpoint", value = "enabled", havingValue = "true", matchIfMissing = false)
@Configuration
public class ScheduleEndpointConfiguration {
    /**
     * 注册 ScheduleMethodHandlerAdapter Bean
     * @return
     */
    @Bean
    public ScheduleMethodHandlerAdapter scheduleMethodHandlerAdapter(){
        return new ScheduleMethodHandlerAdapter();
    }
​
    /**
     * 注册ScheduleMethodHandlerMapping Bean
     * @return
     */
    @Bean
    public ScheduleMethodHandlerMapping scheduleMethodHandlerMapping(){
        return new ScheduleMethodHandlerMapping();
    }
}

在 resources 目录新建 META-INF 目录，并新建 spring.factories 文件，文件内声明 ScheduleEndpointConfiguration 为自动配置项。

org.springframework.boot.autoconfigure.EnableAutoConfiguration=com.fudax.sqcs.common.schedule.ScheduleEndpointConfiguration

 

四：集成效果

访问接口：/swagger-ui.html

 

这谁ChangeController下的所有接口

查看暴露的定时任务接口

在类MessageServer我有两个定时任务：pushAll()方法 clear()方法

 

点击 try it out即可立即触发

 五：安全

这种端点暴露只能在本地测试，开发环境使用，上到生产应该是严格禁止操作的

所以，我写环境校验，以保证生产的安全性

package com.fudax.sqcs.common.schedule.condition;

import com.fudax.sqcs.common.constants.Env;
import com.google.common.collect.Sets;
import org.springframework.context.annotation.Condition;
import org.springframework.context.annotation.ConditionContext;
import org.springframework.core.type.AnnotatedTypeMetadata;

import java.util.Map;

public class OnEnvironmentCondition implements Condition {
    @Override
    public boolean matches(ConditionContext context, AnnotatedTypeMetadata metadata) {
        Map<String, Object> attributes = metadata.getAnnotationAttributes(ConditionalOnEnvironment.class.getName());
        Env[] envs = (Env[]) attributes.get("values");
        Env currentEnv = Env.getCurrentEnv();
        return Sets.newHashSet(envs).contains(currentEnv);
    }
}

@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.TYPE, ElementType.METHOD})
@Documented
@Conditional(OnEnvironmentCondition.class)
public @interface ConditionalOnEnvironment {

    Env[] values() default {Env.LOCAL};
}