# base-components

**Repository Path**: drakelee1221/base-components

## Basic Information

- **Project Name**: base-components
- **Description**: base components
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 4
- **Forks**: 2
- **Created**: 2018-12-11
- **Last Updated**: 2025-01-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 配置说明
#### pom.xml 添加以下配置
```xml
  <parent>
    <groupId>com.drakelee.base</groupId>
    <artifactId>base-components</artifactId>
    <version>v2023-SNAPSHOT</version>
  </parent>
```
```xml
  <repositories>
    <repository>
      <id>devops-central</id>
      <name>central</name>
      <url>https://cqwk-maven.pkg.coding.net/repository/devops/central/</url>
      <releases>
        <enabled>true</enabled>
      </releases>
      <snapshots>
        <enabled>true</enabled>
        <updatePolicy>always</updatePolicy>
      </snapshots>
    </repository>
  </repositories>
```
##### 程序启动的必要配置文件：application.yml ，需放置在classpath中（Spring 已默认不推荐加载bootstrap.yml了）
>参考 application_demo.yml 该文件中为启动时的必要配置。
>一些常用的配置项，参考demo_base_config.yml
##### 配置加密（如无特殊需要，无需配置）
>先使用 SecretHelper.encrypt 静态方法来加密需要的配置信息，加密后的值需要使用 {cipher} 开头，如： 
>aaa.key={cipher}加密后的值
```yaml
#SecretHelper.encrypt加密时key和salt可以为空（有默认值），如果使用了自定义的key和salt，则需要配置以下内容到配置文件中
encrypt:
  # salt 的每个字符必须是 16进制的 hex character
  salt: ABC
  key: 1234567
```

##### 启动类方式 SpringBootApplicationRunner，当前项目的扫描包请至少包含三级，例
```java
@SpringBootApplication(scanBasePackages = "com.demo.app.**")
public class TestBootApplication {
  public static void main(String[] args) {
    SpringBootApplicationRunner.run(TestBootApplication.class, ServerPort.random(), BannerPrinter.create(), args);
  }
}
```
--- 
# 各模块说明
### [support](support) ：基础支持模块，包含常量、接口定义、通用配置、工具类、启动事件等
- ClassInfo 高性能反射工具，SnowflakeIdGenerator 雪花ID实现，接口参数自动效验实现，ConvertUtil 高性能类型转换工具等

---
### [common](common) ：加载各种基础配置，申明基础服务等
- 通过 BaseEnvironment 和 EnvBootChecker 设置一些低优先级的默认配置
- BasePriorityAutoConfiguration 配置各种启动事件、统一线程池管理等
- BaseIdGeneratorAutoConfiguration 配置全局唯一ID生成器
- ApplicationCustomConfiguration 配置跨域、全局异常处理等
- SystemLogConfiguration 配置系统日志AOP
- SystemEventNotifierConfiguration 配置系统事件通知
- ServletActuatorSecurityConfiguration 配置Actuator和Security

---
### [transaction](transaction)：事务配置管理，声明式事务，事务生命周期事件管理（支持分布式全局事务）

---
### [transaction-global](transaction-global)：分布式事务配置管理（暂支持 seata ）

---
### [log4jdbc](log4jdbc)：jdbc代理日志打印，支持sql打印、参数打印、耗时打印等
- 配置参考 base_config_demo.yml 中的 spring.datasource

### [database-jpa](database-jpa)：Spring JPA 增强
```java
//创建以下配置类，例：
@Configuration(proxyBeanMethods = false)
@EnableTransactionManagement
@EntityScan("com.xxx.yyy.domain")
@EnableJpaRepositories(
  value = "com.xxx.yyy.database.dao",
  repositoryBaseClass = GenericJpaDaoImpl.class
)
public class CustomJpaConfiguration extends AbstractJpaConfiguration{
}
```
```java
//实体类参考：
import com.base.components.common.constants.db.Domain;
import com.base.components.common.doc.annotation.Param;
import com.base.components.common.id.jpa.JpaId;
import jakarta.persistence.*;
import org.hibernate.annotations.DynamicUpdate;
import java.io.Serial;
@Entity
@Table(name = "t_tags")
@DynamicUpdate
public class Tags implements Domain<String> {
  @Serial
  private static final long serialVersionUID = 1L;
  @Id
  @JpaId
  @GeneratedValue(generator = JPA_ID_GENERATOR_NAME)
  @Column(name = "id", nullable = false)
  @Param(value = "id", required = true)
  private String id;

  @Column(name = "create_time", nullable = false)
  @Param(value = "创建时间", required = true)
  private java.util.Date createTime;

  @Column(name = "status", nullable = false)
  @Param(value = "状态; 0=禁用，1=启用", required = true)
  private Integer status = 0;

  @Column(name = "tag_name", nullable = false)
  @Param(value = "标签名", required = true)
  private String tagName = "";
}

```
- AsyncJpaRepositoryConfiguration 异步加载JPA Repository配置
- GenericJpaDao 抽象JPA Dao，支持分页、排序、条件查询、条件更新、条件删除、条件统计等
- JpaService 抽象JPA Service，将GenericJpaDao方法封装至Service中
- DynamicSqlBuilder 动态SQL生成器，可根据JOIN表依赖关系对SQL进行优化，支持SQL动态参数化

---
### [database-mybatis](database-mybatis)：MyBatis 增强，提供Mybatis-plus和tk-mybatis组件支持

---
### [cache](cache)：统一封装缓存管理，支持Redis（分布式）、Caffeine（本地单机）
- CacheManager 缓存管理实现
- TokenManager 令牌管理实现
- CacheLock 分布式锁实现
- 订阅发布模型，ChannelMessageSender 发布消息， BaseAsyncChannelMessageListener 订阅消息
- DictionaryCacheService 字典缓存服务

---
### [rpc](rpc)：RPC远程调用配置（feign实现）
```java
//添加自定义配置类如下实例：
@Configuration(proxyBeanMethods = false)
//扫描feign接口目录
@EnableFeignClients(basePackages = {"com.xxx.app.rpc.client"})
@AutoConfigureBefore(BaseRpcConfiguration.class)
public class CustomRpcConfiguration {}
```
- AbstractErrorDecoderHandler 统一异常处理
- TokenProcessHeaderInvocation token上下游传递
- XForwardedHeaderInvocation 通过x-forwarded-for将客户端IP上下游传递
- BaseRpcConfiguration 配置调用链路追踪、日志打印、异常处理等

---
### [gateway](gateway)：微服务网关配置（SpringCloud Gateway实现）
- OpenApiGatewayConfiguration 配置OpenApi文档网关配置

---
### [oss](oss)：OSS对象存储配置（支持阿里云、七牛云、本地）
- OssService 统一OSS接口，包含鉴权、上传下载等方法
- OssUploadTokenController 统一获取上传凭证接口

---
### [oss-vod](oss-vod)：视频点播配置（支持阿里云）
- AliVodController 视频点播接口
- OssVodPlayAuthValidation 自定义鉴权接口

---
### [task](task)：基于Quartz的任务调度，支持Groovy动态脚本、支持分布式部署
```
作业调用类需继承 com.base.components.common.service.task.BaseTaskHandler 。
需添加数据库表：
  CREATE TABLE `sys_task`  (
    `id` char(36) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci NOT NULL,
    `name` varchar(256) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci NOT NULL DEFAULT '' COMMENT '作业名称',
    `description` varchar(1000) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci NOT NULL DEFAULT '' COMMENT '描述',
    `target_class` varchar(500) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci NOT NULL DEFAULT '' COMMENT '执行完整类名',
    `target_class_script` varchar(5000) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci NOT NULL DEFAULT '' COMMENT '执行类代码',
    `cron_expression` varchar(50) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci NOT NULL DEFAULT '' COMMENT '格式; [秒] [分] [小时] [日] [月] [周] [年]，如：2016年1月10日13点24分0秒 为 0 24 13 10 1 ? 2016',
    `arguments_map` varchar(2000) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci NOT NULL DEFAULT '' COMMENT '传递到执行方法的参数, 如：{\"a\":1}',
    `last_server` varchar(50) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci NOT NULL DEFAULT '' COMMENT '最后执行的作业服务器端',
    `last_time` datetime(0) NULL DEFAULT NULL COMMENT '最后执行时间',
    `disabled` bit(1) NOT NULL DEFAULT b'0' COMMENT '已禁用; 0=否，1=是',
    `locking` bit(1) NOT NULL DEFAULT b'0' COMMENT '是否锁定中; 0=否，1=是，一般为一个作业服务端调用时锁定并排它',
    `create_time` datetime(0) NOT NULL COMMENT '创建时间',
    PRIMARY KEY (`id`) USING BTREE,
    INDEX `disabled`(`disabled`) USING BTREE,
    INDEX `locking`(`locking`) USING BTREE
  ) ENGINE = InnoDB CHARACTER SET = utf8mb4 COLLATE = utf8mb4_general_ci COMMENT = '系统调度作业' ROW_FORMAT = Dynamic;

  CREATE TABLE `sys_task_log`  (
    `id` char(36) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci NOT NULL,
    `task_id` char(36) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci NOT NULL DEFAULT '',
    `task_name` varchar(500) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci NOT NULL DEFAULT '' COMMENT '作业名称',
    `execute_over_time` datetime(0) NOT NULL COMMENT '执行完成时间',
    `task_fire_time` datetime(0) NOT NULL COMMENT '作业触发时间',
    `execute_success` bit(1) NOT NULL DEFAULT b'1' COMMENT '是否完整执行并未抛异常',
    `execute_exceptions` varchar(4000) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci NOT NULL DEFAULT '' COMMENT '异常信息',
    `execute_server_host` varchar(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci NOT NULL DEFAULT '' COMMENT '执行作业服务端',
    `result_message` varchar(4000) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci NOT NULL DEFAULT '' COMMENT '完成返回信息',
    PRIMARY KEY (`id`) USING BTREE,
    INDEX `task_id`(`task_id`) USING BTREE
  ) ENGINE = InnoDB CHARACTER SET = utf8mb4 COLLATE = utf8mb4_general_ci COMMENT = '系统调度作业日志' ROW_FORMAT = Dynamic;
```
- SysTaskClient 调度管理接口

---
### [elasticsearch](elasticsearch)：Elasticsearch配置
```java
//继承配置类 BaseElasticSearchConfig ，并指定 repository 包路径
@Configuration(proxyBeanMethods = false)
@EnableElasticsearchRepositories(
  basePackages = "com.xxx.xxx.elasticsearch.repository",
  repositoryBaseClass = GenericElasticsearchRepositoryImpl.class
)
public class ElasticsearchConfiguration extends BaseElasticSearchConfig {}
```
```java
//实体类参考：
@Entity
@Table(name = "t_xxx_domain")
@Document(indexName = EsIndex.INDEX_PREFIX + "xxx_domain")
public class XxxDomain implements Domain<String> {
  @Serial
  private static final long serialVersionUID = 1L;
  @Id
  @JpaId
  @GeneratedValue(generator = JPA_ID_GENERATOR_NAME)
  @Column(name = "id", nullable = false)
  @Param(value = "id", required = true)
  private String id;
  
  @Column(name = "tag_name", nullable = false)
  @Param(value = "名称", required = true)
  private String name = "";
}
```
- 对Query API进行封装，参考 com.base.components.elasticsearch.constants.Search
- GenericElasticsearchRepository 通用Repository封装，可根据@Table、@Column同步数据库
- TrackTotalHits 使用此注解的索引实体，分页时不限制行数，但性能有所下降

---
### [monitor-server](monitor-server)：监控服务配置（spring boot admin）
- 如需作为spring boot admin client，还需要依赖：
```xml
  <dependency>
    <groupId>de.codecentric</groupId>
    <artifactId>spring-boot-admin-starter-client</artifactId>
  </dependency>
```
- AdminServerHttpSecurityProcessor 配置Spring Security
- DingTalkMonitorNotifier 钉钉监控通知

---
### [doc](doc)：OpenApi文档配置
- 配置文件：BaseOpenApiProperties，配置前缀：base.open-api，默认UI地址：/doc.html
- 使用 com.base.components.common.doc.annotation.Param 对实体字段或参数进行描述
- 接口文档参考：
```java
import com.base.components.common.doc.*;
import com.base.components.common.doc.annotation.*;
import com.base.components.common.doc.type.*;
import com.base.components.common.dto.page.DataPage;
import com.base.components.common.dto.sys.PageParamMap;
import com.base.components.common.dto.sys.ParamMap;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

@Tag(name = "测试示例")
@RestController
public class DocController {
  @Operation(summary = "Post接口，Payload参数")
  @ApiExtension(author = "作者", update = "2019-06-09 13:32:22", token = @Token)
  @RequestBodyModel(baseModel = UserInfo.class, value ={
    @Param(name = "f1",value = "动态字符f1", example = "xxx", required = true),
    @Param(name = "f2",value = "动态数字f2", example = "1", dataType = Integer.class),
    @Param(name = "obj",value = "动态对象obj", dataType = ObjectType.class),
    @Param(name = "obj.id",value = "动态对象obj字段id", required = true),
    @Param(name = "list[]",value = "动态列表list", dataType = ArrayType.class),
    @Param(name = "list[].name",value = "动态列表list字段name"),
    @Param(name = "tagList[]" ,value = "标签列表", dataType = ArrayType.class, genericType = Tags.class),
    @Param(name = "tag" ,value = "标签对象", dataType = Tags.class),
    @Param(name = "password" ,value = "UserInfo隐藏字段password", hidden = true),
  })
  @ReturnModel(baseModel = UserInfo.class)
  @PostMapping(value = "/demo", produces = MediaType.APPLICATION_JSON_VALUE)
  public ResponseEntity<?> postDemo(@RequestBody ParamMap paramMap){
    return ResponseEntity.ok().build();
  }
  
  @Operation(summary = "Get接口")
  @ApiExtension(author = "作者", update = "2019-06-09 13:32:22",token = @Token)
  @RequestModel({
    @Param(name = "id",value = "id", requestScope = Scope.PATH, required = true),
    @Param(name = "name" ,value = "name"),
    @Param(name = "pageNum", value = "当前页数; 默认1", dataType = Integer.class),
    @Param(name = "pageSize", value = "每页行数; 默认30", dataType = Integer.class)
  })
  @ReturnModel(baseModel = DataPage.class, value = {
    @Param(name = "list[]", value = "数据列表", dataType = ArrayType.class, genericType = UserInfo.class)
  })
  @GetMapping(value = "/demo/{id}", produces = MediaType.APPLICATION_JSON_VALUE)
  public ResponseEntity<?> demo(@PathVariable("id") String id, @RequestParam PageParamMap paramMap){
    return ResponseEntity.ok().build();
  }
}
```

---
### [code-tool](code-tool)：代码生成工具
- 参考application.yml配置：
```yaml
server.port: 9999
spring:
  application:
    name: "code-tool"
  datasource:
    driver-class-name: net.sf.log4jdbc.DriverSpy
    name: 'demo_dev'
    username: 'root'
    password: '123456'
    url: jdbc:log4jdbc:mysql://127.0.0.1:3306/${spring.datasource.name}?autoReconnect=true&useUnicode=true&characterEncoding=utf-8&allowMultiQueries=true&useSSL=false&serverTimezone=GMT%2B8
  freemarker:
    suffix: ".ftl"
#如需修改模板，在对应位置覆盖模板文件即可；如：classpath: templates/common/DomainMybatisAndJPA.tmpl
```