spring-boot-extension-doc

提供spring boot扩展包,包含自动装配、starter、一些工具类等。

1. 关于

1.1. 简介

spring-boot-extension是一个拓展Spring Boot的库，内置一些SpringBoot未包含的Starter包
同时也补充的各种工具类，用于简化开发、提升开发效率

2. 安装

2.1. 依赖相关

Maven

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.github.livk-cloud</groupId>
            <artifactId>spring-extension-dependencies</artifactId>
            <version>${version}</version>
            <scope>import</scope>
            <type>pom</type>
        </dependency>
    </dependencies>
</dependencyManagement>

Gradle

dependencies {
    implementation platform("io.github.livk-cloud:spring-extension-dependencies:$version")
}

嵌入Spring Boot、Spring Boot Admin、Springdoc OpenApi

2.2. 支持的Java版本

仅支持JDK17及其以上版本

3. 使用指导

3.1. spring boot装配文件自动生成

根据代码定义生成spring boot的自动装配文件和spring.factories、aot.factories

Maven

<dependency>
    <groupId>io.github.livk-cloud</groupId>
    <artifactId>spring-auto-service</artifactId>
    <version>${version}</version>
    <scope>provided</scope>
</dependency>

Gradle-Groovy

dependencies {
    //自定义插件，等同于如下两个依赖引用
    compileProcessor project(":spring-auto-service")

    compileOnly project(":spring-auto-service")
    annotationProcessor project(":spring-auto-service")
}

Gradle-Kotlin

dependencies {
    //自定义插件，等同于如下两个依赖引用
    compileProcessor(project(":spring-auto-service"))

    compileOnly(project(":spring-auto-service"))
    annotationProcessor(project(":spring-auto-service"))
}

3.1.1. @SpringAutoService使用示例

@Component
@SpringAutoService
public class SpringContextHolder implements BeanFactoryAware, ApplicationContextAware, DisposableBean {

}

生成文件 META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports

com.livk.commons.spring.context.SpringContextHolder

@AutoConfiguration
@ConditionalOnClass(WebClient.class)
@SpringAutoService(com.livk.commons.http.annotation.EnableWebClient.class)
public class WebClientConfiguration {

}

生成文件 META-INF/spring/com.livk.commons.http.annotation.EnableWebClient.imports

com.livk.commons.http.WebClientConfiguration

3.1.2. @SpringFactories 使用示例

@SpringFactories支持生成aot.factories原理基本同下，只需指定属性aot=true

指定接口为spring.factories的Key

@SpringFactories(org.springframework.boot.env.EnvironmentPostProcessor)
public class TraceEnvironmentPostProcessor implements EnvironmentPostProcessor {

}

生成文件 META-INF/spring.factories

org.springframework.boot.env.EnvironmentPostProcessor=\
    com.livk.commons.spring.TraceEnvironmentPostProcessor

当前类如果仅仅只有一个接口，可以不指定，自动生成

@SpringFactories
public class TraceEnvironmentPostProcessor implements EnvironmentPostProcessor {

}

生成文件 META-INF/spring.factories

org.springframework.boot.env.EnvironmentPostProcessor=\
    com.livk.commons.spring.TraceEnvironmentPostProcessor

3.2. spring extension commons

提供一些通用、工具类方便开发

3.2.1. aop

AnnotationAbstractPointcutAdvisor

使用注解处理AOP的通用切点及表达式

使用示例

public class LockInterceptor extends AnnotationAbstractPointcutAdvisor<OnLock>{
    @Override
    protected Object invoke(MethodInvocation invocation, OnLock onLock){
        //AOP处理等同于org.aspectj.lang.annotation.Around
    }

    @Override
    public Pointcut getPointcut(){
        //实现切入点
    }
}

将注解作为泛型，自动获取到注解信息

AnnotationAbstractPointcutTypeAdvisor

定制化拓展

使用示例

public class LockInterceptor extends AnnotationAbstractPointcutTypeAdvisor<OnLock>{
    @Override
    protected Object invoke(MethodInvocation invocation, OnLock onLock){
        //
    }

    @Override
    protected AnnotationPointcutType pointcutType() {
        //默认实现
        return AnnotationPointcutType.AUTO;
    }
}

AnnotationPointcutType

提供四种可选方案

TYPE基于类级别的拦截等价于(@Around(@within(Annotation)))
METHOD基于方法级别的拦截等价于(@Around(@annotation(Annotation)))
TYPE_OR_METHOD基于类或方法级别的拦截等价于(@Around(@annotation(Annotation)||@within(Annotation)))
AUTO根据Annotation Target推断(如果仅有TYPE、则为TYPE级别。如果仅有METHOD、则为METHOD级别。如果同时都有则为TYPE_OR_METHOD级别。以上情况都无法出现则抛出异常)

3.2.2. bean

BeanLambdaFunc

根据lambda解析Field和Method

使用示例:

import java.lang.reflect.Field;
import java.lang.reflect.Method;

public class Main{
    public static void main(String[] args){
      String methodName = BeanLambdaFunc.methodName(Maker::getNo);
      Method method = BeanLambdaFunc.method(Maker::getNo);
      String fieldName = BeanLambdaFunc.fieldName(Maker::getNo);
      Field field = BeanLambdaFunc.field(Maker::getNo);
    }
}

pair

一个便捷的KV键值对

jackson序列化({K:V},反序列化同理，类似于Map)
可直接转Map、Map.Entity
同时设置map和flatMap进行转换

3.2.3. expression

AbstractExpressionResolver

ExpressionResolver抽象实现
将Map或者Method等信息转成Context

使用示例:

public class MyExpressionResolver extends AbstractExpressionResolver {
    @Override
    public <T> T evaluate(String value, Context context, Class<T> returnType) {
        //TODO:解析表达式
    }

    //重写此方法用于调整Context的解析
    @Override
    protected ContextFactory getContextFactory() {
        return super.getContextFactory();
    }
}

CacheExpressionResolver

用于对表达式解析进行缓存构建
同时添加spring-environment的支持

使用示例:

public class MyExpressionResolver extends CacheExpressionResolver<Expression> {
  //将表达式转成不同组件的表达式类
    @Override
    protected Expression compile(String value) throws Throwable {
        return null;
    }

  //根据组件的表达式进行计算
    @Override
    protected <T> T calculate(Expression expression, Context context, Class<T> returnType) throws Throwable {
        return null;
    }
}

ConverterExpressionResolver

用于适配不同的解析工具
将Context转成相对于的上下文环境

public class MyExpressionResolver extends ConverterExpressionResolver<EvaluationContext, Expression> {
  //将上下文转成组件的上下文
    @Override
    protected EvaluationContext transform(Context context) {
        return null;
    }
}

内置ExpressionResolver

SpringExpressionResolver → 根据SpringEL表达式进行解析
AviatorExpressionResolver → 根据Aviator表达式进行解析(需要重新引入jar)
FreeMarkerExpressionResolver → 根据FreeMarker表达式进行解析(需要重新引入jar)
JexlExpressionResolver → 根据Apache Commons Jexl3表达式进行解析(需要重新引入jar)
MvelExpressionResolver → 根据Mvel 2表达式进行解析(需要重新引入jar)

3.2.4. http

3.2.5. spring

3.3. SpringBoot自动装配拓展

使用spring boot的自动装配特性,自定义配置文件来覆盖官方的配置

3.3.1. 动态数据源

使用方式
示例

主启动类添加 @EnableDynamicDatasource

@EnableDynamicDatasource
@SpringBootApplication
public class DynamicExample {
    public static void main(String[] args) {
        LivkSpring.run(DynamicExample.class, args);
    }
}

yml配置

spring:
  dynamic:
    datasource:
      mysql:
        url: jdbc:mysql://livk.com:3306/mybatis
        username: root
        password: 123456
        driver-class-name: com.mysql.cj.jdbc.Driver
#        是否主数据源
        primary: true
      pgsql:
        url: jdbc:postgresql://livk.com:5432/mybatis
        username: postgres
        password: 123456
        driver-class-name: org.postgresql.Driver

使用示例，在类获取方法上添加注解 @DynamicSource 并填入数据源名称，数据源名称为yml配置的名称
方法级注解优先级高于类级别

@RestController
@RequestMapping("user")
@RequiredArgsConstructor
public class UserController {

    private final UserMapper userMapper;

    @DynamicSource("mysql")
    @PostMapping("mysql")
    public HttpEntity<Boolean> mysqlSave() {
        User user = new User();
        user.setUsername("root");
        user.setPassword("123456");
        return ResponseEntity.ok(userMapper.insert(user, "user") != 0);
    }

    @DynamicSource("mysql")
    @GetMapping("mysql")
    public HttpEntity<List<User>> mysqlUser() {
        return ResponseEntity.ok(userMapper.selectList("user"));
    }

    @DynamicSource("pgsql")
    @PostMapping("pgsql")
    public HttpEntity<Boolean> pgsqlSave() {
        User user = new User();
        user.setUsername("postgres");
        user.setPassword("123456");
        return ResponseEntity.ok(userMapper.insert(user, "\"user\"") != 0);
    }

    @DynamicSource("pgsql")
    @GetMapping("pgsql")
    public HttpEntity<List<User>> pgsqlUser() {
        return ResponseEntity.ok(userMapper.selectList("\"user\""));
    }

}

3.3.2. 注解导入或生成Excel

使用方式:
SpringMvc示例
 SpringWebflux示例

Excel导入

使用注解 @ExcelImport 解析Excel(支持Spring Webflux)
fileName指定文件名称
parse使用自定义封装阿里EasyExcel的解析器 com.livk.excel.mvc.listener.InfoExcelListener
paramName指定需要传递至那个参数

@RestController
public class InfoController {

    @ExcelImport(parse = InfoExcelListener.class, paramName = "dataExcels")
    @PostMapping("uploadList")
    public HttpEntity<List<Info>> uploadList(List<Info> dataExcels) {
        return ResponseEntity.ok(dataExcels);
    }

    @ExcelImport(parse = InfoExcelListener.class, paramName = "dataExcels")
    @PostMapping("upload")
    public HttpEntity<List<Info>> upload(List<Info> dataExcels) {
        return ResponseEntity.ok(dataExcels);
    }

    @ExcelImport(parse = InfoExcelListener.class, paramName = "dataExcels")
    @PostMapping("uploadMono")
    public Mono<HttpEntity<List<Info>>> uploadMono(Mono<List<Info>> dataExcels) {
        return dataExcels.map(ResponseEntity::ok);
    }
}

Excel导出

使用注解 @ExcelReturn 或者 @ExcelController 解析Excel(支持Spring Webflux)
fileName指定下载文件名
suffix指定Excel后缀默认xlsm
使用ExcelController之后，fileName为out，suffix为xlsm

返回结果为 List<?> Mono<List<?>> Flux<?> 是sheet名称即为sheet
返回结果为 Map<String,?> Mono<Map<String,?>> 是sheet名称即为map key

@RestController
@RequiredArgsConstructor
public class InfoController {

    @ExcelReturn(fileName = "outFile")
    @ExcelImport(parse = InfoExcelListener.class, paramName = "dataExcels")
    @PostMapping("uploadDownLoad")
    public List<Info> uploadDownLoadMono(List<Info> dataExcels) {
        return dataExcels;
    }

    @ExcelReturn(fileName = "outFile")
    @ExcelImport(parse = InfoExcelListener.class, paramName = "dataExcels")
    @PostMapping("uploadDownLoadMono")
    public Mono<List<Info>> uploadDownLoadMono(Mono<List<Info>> dataExcels) {
        return dataExcels;
    }

    @ExcelReturn(fileName = "outFile")
    @ExcelImport(parse = InfoExcelListener.class, paramName = "dataExcels")
    @PostMapping("uploadDownLoadFlux")
    public Flux<Info> uploadDownLoadFlux(Mono<List<Info>> dataExcels) {
        return dataExcels.flatMapMany(Flux::fromIterable);
    }
}

@ExcelController
public class Info2Controller {

    @PostMapping("download")
    public Map<String, List<Info>> download(@RequestBody List<Info> dataExcels) {
        return dataExcels.stream()
                .collect(Collectors.groupingBy(info -> String.valueOf(Long.parseLong(info.getPhone()) % 10)));
    }
}

3.3.3. 接口声明式http客户端

使用方式:
http interface示例

使用示例，在接口上添加 @Provider 或者 @HttpExchange
兼容reactor Mono Flux
使用方式类似于Feign, 被注解标准的接口需要在Spring包扫描下

@Provider(url = "https://spring.io")
public interface RemoteService {

    @GetExchange()
    String get();

}

@Provider(url = "https://spring.io")
@Slf4j
@RestController
@RequiredArgsConstructor
public class HttpController {

    private final RemoteService service;

    @PostConstruct
    public void init() {
        log.info("get length:{}", service.get().trim().length());
    }

    @GetMapping("get")
    public HttpEntity<String> get() {
        return ResponseEntity.ok(service.get());
    }

}

3.3.4. 本地锁与分布式锁

使用方式:
lock示例

使用示例
key支持SpEL表达式，同时支持公平锁、读锁、写锁，并支持异步
本地锁：在方法上添加 @OnLock(scope = LockScope.STANDALONE_LOCK)
分布式：在方法上添加 @OnLock(scope = LockScope.DISTRIBUTED_LOCK) (当前分布式锁仅支持Redis)+

@RestController
@RequestMapping("shop")
public class ShopController {
    private Integer num = 500;
    private int buyCount = 0;
    private int buySucCount = 0;

    @PostMapping("/buy/local")
    @OnLock(key = "shop", scope = LockScope.STANDALONE_LOCK)
    public HttpEntity<Map<String, Object>> buyLocal(@RequestParam(defaultValue = "2") Integer count) {
        buyCount++;
        if (num >= count) {
            num -= count;
            buySucCount++;
            return ResponseEntity.ok(Map.of("code", "200", "msg", "购买成功，数量：" + count));
        } else {
            return ResponseEntity.ok(Map.of("code", "500", "msg", "数量超出库存！"));
        }
    }

    @PostMapping("/buy/distributed")
    @OnLock(key = "shop", scope = LockScope.DISTRIBUTED_LOCK)
    public HttpEntity<Map<String, Object>> buyDistributed(@RequestParam(defaultValue = "2") Integer count) {
        RedisScript<Long> redisScript = RedisScript.of(new ClassPathResource("script/buy.lua"), Long.class);
        Long result = redisTemplate.execute(redisScript, RedisSerializer.string(), new GenericToStringSerializer<>(Long.class), List.of("shop", "num", "buySucCount", "buyCount"), String.valueOf(count));
        if (result != null && result == 1) {
            return ResponseEntity.ok(Map.of("code", "200", "msg", "购买成功，数量：" + count));
        }
        return ResponseEntity.ok(Map.of("code", "500", "msg", "数量超出库存！"));
    }
}

3.3.5. Mapstruct

使用方式:
mapstruct示例

使用示例
自定义转换器
继承 com.livk.autoconfigure.mapstruct.converter.Converter
并添加注解 @Mapper(componentModel = MappingConstants.ComponentModel.SPRING)

@Mapper(componentModel = MappingConstants.ComponentModel.SPRING)
public interface UserConverter extends Converter<User, UserVO> {

    @Mapping(target = "password", ignore = true)
    @Mapping(target = "id", ignore = true)
    @Mapping(target = "createTime", source = "createTime", dateFormat = DateUtils.YMD_HMS)
    @Mapping(target = "type", source = "type", numberFormat = "#")
    @Override
    User getSource(UserVO userVO);

    @Mapping(target = "createTime", source = "createTime", dateFormat = DateUtils.YMD_HMS)
    @Mapping(target = "type", source = "type", numberFormat = "#")
    @Override
    UserVO getTarget(User user);

}

Spring转换器继承 org.springframework.core.convert.converter.Converter
并添加注解 @Mapper(componentModel = MappingConstants.ComponentModel.SPRING)

@Mapper(componentModel = MappingConstants.ComponentModel.SPRING)
public interface UserSpringConverter extends Converter<User, UserVO> {

    @Mapping(target = "createTime", source = "createTime", dateFormat = DateUtils.YMD_HMS)
    @Mapping(target = "type", source = "type", numberFormat = "#")
    @Override
    UserVO convert(@Nullable User user);

}

使用 `MapstructService`操作转换自定义转换器
使用 `ConversionService`操作转换Spring转换器

@RestController
@RequestMapping("user")
@RequiredArgsConstructor
public class UserController {

    public static final List<User> USERS = List.of(
            new User().setId(1).setUsername("livk").setPassword("123456").setType(1).setCreateTime(new Date()),
            new User().setId(2).setUsername("livk2").setPassword("123456").setType(2).setCreateTime(new Date()),
            new User().setId(3).setUsername("livk3").setPassword("123456").setType(3).setCreateTime(new Date()));

    // 自定义双向转换
    private final MapstructService service;

    // spring单向转换
    private final ConversionService conversionService;

    private final ConversionServiceAdapter conversionServiceAdapter;

    @PostConstruct
    public void init() {
        System.out.println(conversionService.convert(USERS.get(0), UserVO.class));
        service.convert(USERS, UserVO.class).forEach(System.out::println);
        SpringContextHolder.getBean(MapstructService.class).convert(USERS, UserVO.class).forEach(System.out::println);
    }

    @GetMapping
    public HttpEntity<Map<String, List<UserVO>>> list() {
        List<UserVO> userVOS = USERS.stream().map(user -> conversionService.convert(user, UserVO.class))
                .filter(Objects::nonNull).toList();
        return ResponseEntity
                .ok(Map.of("spring", userVOS,
                        "customize", service.convert(USERS, UserVO.class).toList()));
    }

    @GetMapping("/{id}")
    public HttpEntity<Map<String, UserVO>> getById(@PathVariable Integer id) {
        User u = USERS.stream().filter(user -> user.getId().equals(id)).findFirst().orElse(new User());
        UserVO userVOSpring = conversionService.convert(u, UserVO.class);
        return ResponseEntity.ok(Map.of("customize", service.convert(u, UserVO.class),
                "spring", userVOSpring,
                "adapter", conversionServiceAdapter.mapUserToUserVO(u)));
    }

}

spring-boot-extension-doc

1. 关于

1.1. 简介

2. 安装

2.1. 依赖相关

2.2. 支持的Java版本

3. 使用指导

3.1. spring boot装配文件自动生成

3.1.1. @SpringAutoService使用示例

3.1.2. @SpringFactories 使用示例

3.2. spring extension commons

3.2.1. aop

AnnotationAbstractPointcutAdvisor

AnnotationAbstractPointcutTypeAdvisor

AnnotationPointcutType

3.2.2. bean

BeanLambdaFunc

pair

3.2.3. expression

AbstractExpressionResolver

CacheExpressionResolver

ConverterExpressionResolver

内置ExpressionResolver

3.2.4. http

3.2.5. spring

3.3. SpringBoot自动装配拓展

3.3.1. 动态数据源

3.3.2. 注解导入或生成Excel

Excel导入

Excel导出

3.3.3. 接口声明式http客户端

3.3.4. 本地锁与分布式锁

3.3.5. Mapstruct

4. 问题