# csc开发脚手架 **Repository Path**: xyy010/csc ## Basic Information - **Project Name**: csc开发脚手架 - **Description**: 基于spring cloud的开发脚手架： （1）使用nacos作为微服务注册中心及配置中心 （2）支持动态数据源、动态redis、动态kafka生产者及消费者 （3）提供了基于quartz 2.0的的自动任务框架 （4）引入了traceId用于全链路日志追踪 - **Primary Language**: Java - **License**: Apache-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 1 - **Forks**: 0 - **Created**: 2023-02-22 - **Last Updated**: 2024-06-19 ## Categories & Tags **Categories**: Uncategorized **Tags**: SpringCloud, SpringBoot ## README # 轻量级spring cloud开发脚手架 ### 介绍 基于spring cloud的开发脚手架： 1、使用nacos作为微服务注册中心及配置中心 2、支持动态数据源、动态redis、动态kafka生产者及消费者 3、提供了基于quartz 2.0的的自动任务框架 4、引入了traceId用于全链路日志追踪 ### 用途 - 整合日常碰到的优质代码及思想，方便日后使用 ### 需要具备的知识点 为了顺利的使用本脚手架，需要了解以下知识点： >1. 微服务概念 **必须** >2. spring boot/spring cloud **必须** >3. mysql及redis的使用 **必须** >4. kafka 使用kafka时 必须 >5. docker 使用镜像部署服务时必须。入门学习资料：https://www.runoob.com/docker/docker-tutorial.html。 >6. nacos 参看：https://nacos.io/zh-cn/docs/what-is-nacos.html >7. mybatis\mybatis plus **必须** >8. spring **必须** ### 基础软件依赖 基础软件版本如下： - jdk 1.8.342 - redis 3.0.503 - mysql 8.0.23 - kafka 2.12-2.3.0 - docker 19.03.12 - maven 3.3.9 - nacos 2.0.0 使用过程中可根据需要自行调整版本。其中： - maven、jdk、redis、mysql **必须使用** - kafka、docker 根据需要 **选用** - nacos 作为微服务的注册与配置中心使用，可**根据需要**自行替换。 ### 工程目录结构及简要说明 >正式使用之前请先对照源码及说明，对工程有大致了解 1. sql   mysql的建表脚本目录。数据库创建完毕之后需要执行次目录下的脚本，否则应用包无法正常启动。 2. docker   jdk基础镜像制作脚本目录。使用提供的脚本制作jdk基础镜像，或者使用您已有的jdk镜像作为基础镜像。 3. build.bat   windows环境全工程编译打包文件。可根据需要修改或者增加linux环境需要的脚本文件。 4. build_image.bat   windows环境全工程构建docker镜像文件。可根据需要修改或者增加linux环境需要的脚本文件。 5. clean.bat   windows环境全工程清理文件。可根据需要修改或者增加linux环境需要的脚本文件。 6. pom.xml   maven构建定义文件。 7. xy-boot-util   基础依赖包，本工程下所有其它模块均需要引入。提供了公共常量、枚举、异常、常用工具类及公共代码。 8. xy-boot-web   web开发依赖包，所有需要提供http服务的子模块均需要引入。提供了web开发中的过程中的常用内容的抽象与封装。 - 提供了http请求全局异常捕获 - 提供了spring mvc全局配置 - 提供了全局的请求拦截器，用于添加traceId，方便后期的日志追踪 - 提供了全局feign client的全局拦截器，用于添加traceId，方便后期的日志追踪 - 提供了分页对分页查询的封装 - 提供了对http response响应结果的封装 - 提供了常用的http请求工具类 - 引入了swagger的依赖，可以对controller接口编写swagger文档 - 提供了http请求日志记录用的公共注解 - 应用接入kafka时，请求日志可以通过kafka保存到数据库 - 应用不接入kafka时，请求日志仅输出到日志文件 - 提供了service层日志记录用的公共方法 - 应用接入kafka时，请求日志可以通过kafka保存到数据库 - 应用不接入kafka时，请求日志仅输出到日志文件 9. xy-boot-db   数据库依赖包，所有需要连接数据库的模块均需要引入。 - 提供了mybatis plus的基础依赖，应用可以使用mybatis/mybatis plus进行开发 - 提供了对JdbcTemplete的封装，应用可以使用封装的数据库操作工具类进行开发 - 提供了对多数据源的封装，应用可以根据配置指定需要初始化的数据源 - 使用mybatis/mybatis plus进行开发时可以通过注解的方式切换数据源 - 使用封装的工具类开发时可以通过指定数据源id的方式切换数据源 - 源码方式集成了百度开源的UidGenerator，用于分布式id的生成 10. xy-boot-redis   redis依赖包，所有需要连接redis的模块均需要引入。 - 封装了常用的redis操作方法，并提供了redis操作工具类 - 支持多redis同时使用，应用可以根据配置指定需要初始化的redis - 使用redis操作工具类开发时，可以通过指定redis id的方式切换redis 11. xy-boot-kafka   kafka依赖包，所有需要连接kafka的模块均需要引入。 - 提供了kafka生产者及消费者的初始化连接方法 - 提供了kafka生产者的操作工具类，可以通过指定kafka id的方式切换kafka - 提供了kafka消费者业务处理service需要实现的公共接口 12. dynamic-gateway   基于Spring Cloud Gateway的微服务网关。 - 增加了请求过滤器，用于记录请求基本信息 - 增加了响应过滤器，用于记录响应结果 - 增加了异常过滤器，用于基于请求异常信息 - 开启了微服务自动发现，用于在微服务增加过程中不需要修改网关配置 13. demo-service   系统开发样例模块，提供了系统的各组件的使用及编码样例。   当前模块的子模块包说明如下（其它业务模块与当前模块类似，除独有包，不再单独说明）： - ..\pom.xml：当前模块maven构建定义文件 - ..\demo-service-api：当前模块对外接口子模块，用于给其它模块或外部系统提供调用接口 - ..\start.spring.basic.demo.dto：存放当前模块的dto对象 - ..\start.spring.basic.demo.vo：存放当前模块的vo对象 - ..\start.spring.basic.demo.feignapi：当前模块通过feign提供给其它模块或外部系统调用的api接口 - ..\demo-service-web：当前模块的业务处理实现子模块，用于实际的业务实现 - ..\resources：存放系统的资源文件 - ..\start.spring.basic.demo.common：存放当前模块的公共内容。涉及多模块的公共内容，根据实际抽取到xy-boot对应的依赖包中。 - ..\start.spring.basic.demo.config：存放当前模块通过spring bean初始化的配置。涉及多模块的公共配置，根据实际抽取到xy-boot对应的依赖包中。 - ..\start.spring.basic.demo.controller：存放当前模块controller层的类 - ..\start.spring.basic.demo.dao.mapping：存放mybatis的xml映射文件 - ..\start.spring.basic.demo.dao：存放mybatis的mapper接口类 - ..\start.spring.basic.demo.entity：存放数据库表的java映射实体类 - ..\start.spring.basic.demo.enums：存放当前模块的枚举类。涉及多模块的枚举类，根据实际抽取到xy-boot对应的依赖包中。 - ..\start.spring.basic.demo.feignclient：存放当前模块通过feignclient调用外部系统的feign客户端 - ..\start.spring.basic.demo.filter：存放当前模块的过滤器。 - ..\start.spring.basic.demo.service：存放当前模块service层的类 - ..\start.spring.basic.demo.service.singletable：存放mybatis plus封装的单表操作接口方法，如批量insert - ..\start.spring.basic.demo.utils：存放当前模块的专有工具类。涉及多模块的工具类，根据实际抽取到xy-boot-util依赖包中。 14. exinterface-service   对外接口模块，用于系统统一提供给第三方系统调用接口的业务编码实现。 15. job-service   自动任务模块，基于quartz封装了自动任务服务。 - 基于数据库配置自动加载自动任务 - 支持单线程自动任务，并提供了编码样例 - 支持多线程自动任务，并提供了编码样例 - 可以通过日志表查询自动任务执行状态 - 自动任务实现了traceId，可以通过traceId进行日志追踪 - 当前模块独有包目录如下： - ..\start.spring.basic.job.quartz：存放quartz初始化相关的类 - ..\start.spring.basic.job.job：存放quartz的job入口类 16. logs-kfkconsumer   基于kafka的日志记录模块，用于把应用投递到kafka的日志信息记录到数据库。 - 支持通过@ServiceLog注解投递的controller层的日志消费 - 支持通过ServiceDetails类投递的service层的日志消费 ### 关键代码及配置说明 **本部分为纯干货，比较枯燥，请保留一些耐心** #### xy-boot包 1. ..\xy-boot-db\..\start.spring.basic.dynamic.DynamicDSRegister   此类用于在应用包启动时初始化gg_pz_db表中配置的数据源。应用包需要初始化的数据源在application.properties文件中通过配置指定，如下：   spring.datasource.dynamic.druid.customnames=dbid1,dbid2 其中的dbid为gg_pz_db表主键，配置多个时使用“,”分隔，不需要时配置值留空即可。 >**注意：**应用包启动时需要的数据源通过nacos配置中心或者bootstrap.properties文件配置，不在GG_PZ_DB表配置。 2. ..\xy-boot-db\..\start.spring.basic.dynamic.DynamicJdbc   此类提供了对JdbcTemplete的封装，用于跨库操作。可通过指定dbid切换数据源，不支持事务，开发样例参看：demo-service。   start.spring.basic.dynamic.SpringJdbc也提供了对JdbcTemplete的封装，用于单库的操作。可以通过@DS注解切换数据源，通过@Transactional注解控制事务，开发样例参看：demo-service。 3. ..\xy-boot-db\..\start.spring.basic.init.InitSystem   此类用于在应用包启动时加载gg_pz_sys表的配置到jvm内存，应用使用系统配置参数据无需查询数据库。应用包中通过：start.spring.basic.constant.ProConstant.PRAMS获取。 - ProConstant.PRAMS为JSON对象，key为gg_pz_sys.pzdm字段，值为gg_pz_sys.pzz字段 - 可根据实际需要修改扩展 4. ..\xy-boot-web\..\start.spring.basic.exception.GloabExceptionHandler   此类用于http请求的全局异常捕获，可根据需要修改扩展。 5. ..\xy-boot-web\..\start.spring.basic.interceptor.GlobalMvcConfigurer   此类为全局spring mvc配置，可根据需要修改扩展。 6. ..\xy-boot-web\..\start.spring.basic.interceptor.TraceIdInterceptor   此类为http请求全局拦截器，用于给请求头添加traceId，方便根据traceId进行全链路的日志追踪。 7. ..\xy-boot-web\..\start.spring.basic.interceptor.FeignRequestInterceptor   此类为feign client公共拦截类，用于给feign客户端请求头添加traceId。开发样例参看：..\job-service\..\start.spring.basic.job.feignclient.InterfaceVersionFeignClient 8. ..\xy-boot-web\..\start.spring.basic.response.ResponseData   此类为http请求通用响应结果对象。无特别要求时，所有http请求均应返回此对象或者ResponsePage对象。 9. ..\xy-boot-web\..\start.spring.basic.response.ResponsePage   此类为分页查询请求通用响应结果对象。无特别要求时，所有http请求均应返回此对象或者ResponseData对象。 10. ..\xy-boot-web\..\start.spring.basic.log.ServiceLog - 此注解用于controller接口，用于自动记录请求日志 - 对于配置了日志kafaka的应用日志信息会投递到kafka，并由logs-kfkconsumer把日志信息记录到gg_sys_log表 - @ServiceLog的使用参看demo-service 11. ..\xy-boot-web\..\start.spring.basic.log.ServiceDetails - 此类解用于service层记录日志，可根据需要在service中任意位置记录日志 - 对于配置了日志kafaka的应用日志信息会投递到kafka，并由logs-kfkconsumer把日志信息记录到gg_sys_log表 - ServiceDetails的使用参看demo-service 12. ..\xy-boot-redis\..\start.spring.basic.dynamic.DynamicRedisRegister   此类用于在应用包启动时初始化gg_pz_redis表中配置的redis。应用包需要初始化的redis在application.properties文件中通过配置指定，如下：   spring.redis.customnames=redis_id1,redis_id2 其中的redis_id为gg_pz_redis表主键，配置多个时使用“,”分隔，不需要时配置值留空即可。 13. ..\xy-boot-redis\..\start.spring.basic.dynamic.DynamicRedisDAO   此类封装了常用的redis操作方法。通过redis_id切换需要操作的redis，redis_id必须指定，不允许设置为null。 14. ..\xy-boot-kafka\..\start.spring.basic.dynamic.DynamicKafkaRegister   此类用于在应用包启动时初始化gg_pz_kafka表中配置的kafka生产者。应用包需要初始化的kafka生产者在application.properties文件中通过配置指定，如下：   spring.kafka.customnames=kafka_id1,kafka_id2 其中的kafka_id为gg_pz_kafka表主键，配置多个时使用“,”分隔，不需要时配置值留空即可。 15. ..\xy-boot-kafka\..\start.spring.basic.dynamic.DynamicKafkaDAO   此类封装了常用的kafka生产者操作方法。通过kafka_id切换kafka，kafka_id必须指定，不允许设置为null。 16. ..\xy-boot-kafka\..\start.spring.basic.dynamic.DynamicKafkaConsumer   此类用于在应用包启动时初始化gg_pz_kfkconsumer表配置的kafka消费者。应用包需要初始化的kafka消费者在application.properties文件中通过配置指定，如：   spring.kafka.dyconsumer=kafkaid1-队列1-消费者组1,kafkaid2-队列2-消费者组2 >- 多个消费者时“,”分隔，不需要时配置值留空即可。 >- gg_pz_kfkconsumer表主键kafka_id（kafka唯一标志），topic（队列名），group_id（消费者组） >- gg_pz_kfkconsumer表与gg_pz_kafka表通过kafka_id关联。 >- kafka的连接信息通过kafka_id在gg_pz_kafka表获取。原因同一个kafka存在多个队列， 同一个队列存在多个消费者组，统一配置连接信息可以减少运维的工作量及出错概率。 17. ..\xy-boot-kafka\..\start.spring.basic.service.IKfkConsumerHandleService   此接口为所有kafka消费者业务处理service需要实现的接口。使用方式参看：   ..\logs-kfkconsumer\..\start.spring.basic.logs.service.logsrecord.LogsConsumerServiceImpl >注意： >- 所有实现此接口的的service类，需要通过@Service注解指定service名称。 >- service名称需要配置到gg_pz_kfkconsumer表的consumer_service_name字段，应用启动时通过gg_pz_kfkconsumer配置绑定service到kafka的消费者组。 #### demo-service模块 1. ..\Dockfile   打包Docker镜像的声明文件，根据需要修改 2. ..\logback-spring.xml   logback配置，根据需要修改 3. ..\application.properties   spring boot包的静态配置文件，此文件中的配置不随环境变化的改变 >注意： > 无kafka环境时需要把文件中的配置：spring.kafka.customnames=logskfk 的配置值置空，即修改为：spring.kafka.customnames= > 否则应用包启动报错。 4. ..\bootstrap.properties   spring boot包的动态配置文件，此文件中的配置随环境变化的改变，如：启动数据库连接信息、swagger访问控制信息等。此文件中的配置可以通过nacos配置中心覆盖（nacos连接信息需要通过spring boot启动命令或者环境变量覆盖）。 5. ..\start.spring.basic.demo.config.SwaggerConfig   swagger初始化配置。swagger访问地址：   （1）直接访问：http://localhost:8081/demo/doc.html   （2）通过dynamic-gateway网关访问：http://localhost:7080/demo/doc.html   两种方式仅端口不同，建议通过dynamic-gateway网关访问。 6. ..\start.spring.basic.demo.controller.BaseController   controller层公共基类，所有的controller均需要继承，提供了controller层的公共操作方法。 7. ..\start.spring.basic.demo.controller.demo.DemoController   系统编码样例controller入口 8. ..\start.spring.basic.exinterface.controller.ResourceController   系统资源检测入口，当前仅提供了应用包版本号查询接口。后续可以根据需求添加资源监控接口。 9. ..\start.spring.basic.demo.service.BaseServiceImpl及start.spring.basic.demo.service.IBaseService   service层公共基类，提供了service层操作的公共方法。 10. ..\start.spring.basic.demo.controller.demo.H2DemoController   嵌入式数据库h2编码样例，对应h2数据库文件:..\demo-service-web\app\test.mv.db。   h2数据源初始化配置参看bootstrap.properties。此数据源配置未放到gg_pz_db表。 #### exinterface-service模块 >与demo-service模块相同的内容，不再单独说明，参看demo-service模块说明。 1. ..\start.spring.basic.exinterface.feignapi.InterfaceVersionApi   此接口为被调用方通过FeignClient发布对外接口样例，其它模块可以通过引用当前模块的-api子模块调用接口。调用此接口样例参看方法：   ..\job-service\\..\start.spring.basic.job.service.demo.impl.DemoServiceImpl.queryInterfaceVersionFromApi() >注意：为了通过traceId进行日志跟踪，对外提供api时可通过**请求参数**强制调用方增加traceId请求头。 #### job-service模块 >与demo-service模块相同的内容，不再单独说明，参看demo-service模块说明。 1. ..\start.spring.basic.job.feignclient.InterfaceVersionFeignClient   此为调用方通过FeignClient调用其它模块接口样例。通过start.spring.basic.interceptor.FeignRequestInterceptor给请求添加traceId请求头。调用此接口样例参看方法：   ..\start.spring.basic.job.service.demo.impl.DemoServiceImpl.queryInterfaceVersionFromFeignClient() 2. ..\start.spring.basic.job.quartz.TaskLoad   自动任务启动加载类。用于把gg_pz_job表配置的自动任务初始化，并根据配置运行自动任务。 >注意：所有的job自动任务均需要在gg_pz_job表配置，通过gg_pz_job.yxbz控制任务是否要加载执行（yxbz = 'Y'时加载）。 3. ..\start.spring.basic.job.job.BaseJob   所有job类的基类，提供了job类需要的公共操作方法，公共方法中设置了traceId用于日志跟踪。 4. ..\start.spring.basic.job.job.DemoJob   多线程自动任务编码样例。多线程任务日志表：gg_job_log（任务执行日志），gg_thread_exec（线程执行日志） 5. ..\start.spring.basic.job.job.DemoJob2   单线程自动任务编码样例。任务日志表：gg_job_log（任务执行日志） 6. ..\bootstrap.properties - 其中的配置：job.cluster.num=1 表示当前启动了几个job-service受管，需要根据实际修改。 此配置用于在有多个自动任务需要执行时，均匀分配自动任务到各job-service受管。 代码实现参看方法：start.spring.basic.job.quartz.TaskService.getTaskFromDb() - job.cluster.restart.mintime=1 表示所有受管启动后，释放redis锁的时间。保证下次重启job-service受管可以分配到自动任务。 如果出现启动时redis连接异常导致redis死锁（通常不会出现），则需要手动解锁，或者提供管理员页面解锁的功能。 需要解锁的redis key的前缀：joblock，手工解锁后需要重启所有的job-service受管。 #### logs-kfkconsumer模块 >与demo-service模块相同的内容，不再单独说明，参看demo-service模块说明。   此模块通过从kafka logs队列读取日志，并记录日志信息到数据库gg_sys_log表，展示了动态kafka消费者使用。 - application.properties配置信息：spring.kafka.dyconsumer=logskfk-logs-recordlogs - 其中logskfk为日志kafka唯一标识，logs为topic名称（需要提前创建此队列），recordlogs为消费者组名称。 - 数据库配置参看：gg_pz_kafka及gg_pz_kfkconsumer表中where kafka_id = 'logskfk'的配置记录。 - gg_pz_kfkconsumer表中where kafka_id = 'logskfk'的配置记录的consumer_service_name字段值为： ..\start.spring.basic.logs.service.logsrecord.LogsConsumerServiceImpl 的service名称 ### 安装教程 1. 启动redis 2. 启动kafka并创建logs队列 3. 启动mysql创建csc、xtgl用户，分别执行对应的建表脚本。根据实际环境修改表配置： gg_pz_db、gg_pz_kafka、gg_pz_redis 4. 启动nacos，nacos使用mysql保存配置信息，参看官网说明 5. 在nacos default命名空间下，创建各微服务应用包的配置并配置数据库连接信息： - demo-service demo - exinterface-service exinterface - logs-kfkconsumer logsconsumer - job-service job  数据库连接信息参看bootstrap.properties文件中：master数据源、sysconfig数据源配置。 6. 按顺序启动：demo-service--》exinterface-service--》logs-kfkconsumer--》job-service--》dynamic-gateway 7. 访问各工程swagger，测试应用是否启动正常，如demo-service：http://localhost:7080/demo/doc.html ### 其它说明 1. 基于此脚手架开发的系统可以使用jar包的方式部署，也可以通过docker镜像的方式部署 2. 工程内提供的Dockerfile均经过验证，可根据需要自行调整 3. docker部署环境的安装及docker镜像构建环境的安装，需要根据实际情况自行解决，不同的项目、不同的组织要求不同，无法统一 ### 参与贡献 1. Fork 本仓库 develop 分支 2. 基于 develop 分支新建 develop_xxx 分支 3. 提交代码到 develop_xxx 分支 4. 新建 develop_xxx 分支到 develop 分支的 Pull Request