# mole **Repository Path**: mole-platform/mole ## Basic Information - **Project Name**: mole - **Description**: Mole（鼹鼠）是一套聚焦 “高效复用、简化开发” 的公共基础组件库，通过封装日志、数据源、HTTP 工具等通用能力，减少重复开发工作，为业务系统提供稳定易用的底层支撑，助力开发效率提升与代码标准化。 - **Primary Language**: Java - **License**: Apache-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 1 - **Forks**: 0 - **Created**: 2025-11-18 - **Last Updated**: 2026-03-04 ## Categories & Tags **Categories**: Uncategorized **Tags**: Java, SpringCloud, SpringBoot, Java基础框架, OAuth2 ## README # 系统说明 Mole（鼹鼠）是一套聚焦 “高效复用、简化开发” 的公共基础组件库，通过封装日志、数据源、HTTP 工具等通用能力，减少重复开发工作，为业务系统提供稳定易用的底层支撑，助力开发效率提升与代码标准化。在架构实现上，系统框架层以 Spring Boot 为核心，融合 Spring Cloud 与 Spring Cloud Alibaba 相关组件进行微服务架构设计，可提供高效灵活的分布式服务支持。 ![技术架构图.png](技术架构图.png) | 名称 | 版本号 | |------------------------| ------------ | | Spring Cloud | Hoxton.SR12 | | Spring Cloud Alibaba | 2.2.9.RELEASE | | Spring Boot | 2.3.12.RELEASE| | Spring Security Oauth2 | 2.3.6.RELEASE| ## Spring Cloud 组件列表 | 名称 | 描述 | | ------------ | ------------ | | Spring Cloud Gateway | API网关组件，用于路由请求。 | | Spring Cloud OpenFeign | 声明式 HTTP 客户端，便于微服务之间的通信。 | | Spring Cloud Sleuth + Zipkin | 分布式系统的日志追踪工具，与 Zipkin 配合实现链路追踪。| | Spring Security + Spring-security-oauth2 | 安全框架，支持 OAuth2 身份认证与授权。| ## Spring Cloud Alibaba 组件列表 | 名称 | 描述 | | ------------ | ------------ | | Nacos | 服务注册与发现,配置管理。| | Sentinel | 流量控制和熔断限流。| ## 自定义组件 | 名称 | 说明 | 描述 | |-----------------------------|-----------------|--------------------------------------------| | mole-common-core | 核心模块 | 集成公共基础组件，涵盖 Http 连接池、swagger 文档、跨域配置及可重入锁等功能 | | mole-common-log | 日志模块 | 提供 SysLog 日志注解能力，关键接口可通过添加注解实现日志脱敏与持久化 | | mole-common-datasource | 动态数据源 | 支持多数据源动态切换，若需分库分表需额外引入 sharing-jdbc | | mole-common-file | 文件上传下载 | 适配 minio、腾讯云等存储服务，提供文件上传下载基础能力 | | mole-common-cache | 缓存模块 | 封装 Redis 的通用操作方法、分布式锁、提供便捷的缓存访问能力 | | mole-common-crypto | 加解密模块 | 封装请求数据的加解密逻辑，提供便捷的配置能力，保障数据传输安全 | | mole-common-security | 安全模块 | 封装安全认证默认实现 | | mole-common-security-oauth2 | 安全模块-Oauth2认证模块 | 封装Oauth2认证实现 | | mole-modules-base | 基础服务依赖 | 基础服务依赖 | ### mole-common-core #### 介绍 mole-common-core是mole组件的核心包，提供统一返回Result封装、Http 连接池、通用异常处理、swagger 接口文档、跨域配置及可重入锁等功能。 #### 基础组件 - Result 定义统一的接口返回格式，规范响应数据结构。 - HttpUtil 封装了 HTTP 请求工具类，支持 GET、POST 等请求方式，书写形式简洁易用；结合 HttpClient 连接池使用，经实际压力测试验证，可满足性能需求。 - ExceptionControllerAdvice 实现全局异常处理机制，统一捕获并处理系统运行中的各类异常。 - SwaggerConfig 配置接口文档相关参数，生成规范化的 API 文档，便于接口查阅与调试。 - CorsProperties 规范跨域配置相关参数，统一管理跨域请求的配置信息。 - ReentrantLockUtil 封装可重入锁实现方式，提供便捷的锁操作能力。 Http连接池配置 ```yaml spring: http-client: pool: readTimeout: 20000 # 超时时间20秒 retryTimes: 0 # 失败不重试 ``` HttpUtil使用 ```java String url = "http://www.baidu.com"; // URL参数 Map params = new HashMap<>(); params.put("param1", "value1"); // 请求体 Object jsonBody = "{\"key\":\"value\"}"; // 执行测试 HttpUtil.Builder builder = HttpUtil.builder() .addHeaders("Content-Type", "application/json") .addParams(params) .setJsonBody(jsonBody); builder.doPost(url); ``` CorsProperties 跨域配置参数 ```yaml cors: allowed-origins: - "https://www.baidu.com" allowed-methods: - GET - POST - PUT - DELETE - OPTIONS allowed-headers: - "*" allow-credentials: true max-age: 3600 ``` ReentrantLockUtil使用 ```java @Bean public ReentrantLockUtil reentrantLockUtil() { return new ReentrantLockUtil(); } reentrantLockUtil.execute(key, () -> { log.info("线程任务执行中..."); }); reentrantLockUtil.tryExecute(key, 3, TimeUnit.SECONDS, () -> { log.info("线程任务执行中..."); return ""; }); ``` ### mole-common-log #### 介绍 mole-common-log是mole组件的日志包，提供 SysLog 日志注解能力，关键接口可通过添加注解实现日志脱敏与持久化。 #### 基础组件 - @SysLog 在关键方法上添加此注解，可自动打印方法的入参信息与返回结果，实现日志的便捷记录。 - SysLogService接口 通过实现该接口，可自定义日志的保存逻辑，灵活适配不同的日志存储需求。 - 日志脱敏配置 SysLog注释使用 ```java @SysLog(value = "获取状态信息") public Result getStatus(String id) { // 业务代码... } ``` 日志脱敏配置 ```yaml sensitive: # 姓名 【中文姓名】姓名脱敏显示：**明。显示姓名的最后1-2个汉字； unames: - uname - name - userName # 证件号 【身份证号、银行卡号、社保卡号】 ***********4432。显示最后四位，其 他隐藏； ids: - idNo # 固定电话 【固定电话】如有，后六位以*代替，其余显示 fixPhones: - tel # 手机号 【手机号码】手机号码脱敏显示：133****4387。显示前3位和后4位，其他隐藏； mobiles: - mobile - phone # 地址 【地址】用户户籍地址、用户居住地址、用户工作单位和发卡地脱敏显示：北京市海淀区********。长度大于12时,只显示前6位，不足12位显示不超过50%，其他隐藏 address: - address # 电子邮箱【电子邮箱】用户邮箱脱敏显示：*********@163.com。显示“@”及之后部分，其他隐藏； emails: # 中国车牌【中国车牌】车牌中间用*代替 carLicenses: # 银行卡号 【银行卡号】 eg: 银行卡号显示后4位，其余以*代替 bankCards: # base64 【base64】 日志格式 [header]-prefix-***-suffix-[length] base64: - photo - baseStr - imgStr # 证件有效期脱 【证件有效期】 20200101-20400101 eg: ****0421。显示后4位，其他隐藏； ****-04-21 到 ****-04-20 cardValidity: # 生日 【生日】 长度小于8位：直接返回原值; 长度等于8位（如：19900101）：脱敏为 ****-01-01; 长度等于10位（如：1990-01-01）：脱敏为 ****-01-01; birth: - birthday ``` ### mole-common-file #### 介绍 mole-common-file 文件上传下载组件，适配 MinIO、腾讯云等主流存储服务，提供标准化的文件上传、下载基础能力，简化不同存储场景下的文件操作实现。 #### 基础组件 - IFileService 提供文件上传、下载、删除等方法实现。 文件类型配置 支持 minio、cos(腾讯对象存储)存储服务 ```yaml file: type: cos cos: secretId: * secretkey: * region: ap-beijing bucket: * threadsNum: 4 ``` 文件上传的校验规则中，文件类型校验可通过如下方法实现: ```java // 获取文件后缀后，根据需求校验 FileNameUtil.extName(file.getOriginalFilename()); // 获取文件真实类型后，根据需求校验 FileTypeUtil.getType(file.getInputStream()); // 实际解码验证，只限图片类型，如果image不是null则为图片 BufferedImage image = ImageIO.read(file.getInputStream()); if (image == null) { throw new BusinessException(FileUploadResultCode.FILE_TYPE_ERROR.getCode(), "上传文件无法解析为有效图片，请检查文件内容！"); } // 可选扫描可疑关键词 String content = new String(file.getBytes(), StandardCharsets.UTF_8); if (content.contains(" updateWrapper = new AutoincrementUpdateWrapper<>(); updateWrapper.eq("id", userId).incrField("points", 10); // Lambda 方式 AutoincrementLambdaUpdateWrapper lambdaUpdateWrapper = new AutoincrementLambdaUpdateWrapper<>(); lambdaUpdateWrapper.eq(User::getId, userId).incrField(User::getPoints, 10).descField(User::getBalance, 5); ``` #### 慢SQL监控配置 慢SQL监控功能可通过以下配置启用和自定义： ```yaml mole: datasource: slow-sql: enabled: true # 启用慢SQL监控（默认false） threshold: 500 # 慢SQL阈值，单位ms（默认500ms） record-stack-trace: true # 是否记录堆栈信息（默认true） stack-trace-depth: 5 # 堆栈信息深度（默认5） async: true # 是否启用异步处理（默认true） async-core-pool-size: 5 # 异步处理线程池大小（默认5） ``` #### 功能说明 - 自动拦截执行时间超过阈值的SQL语句 - 记录SQL执行时间、SQL类型、数据源名称、SQL语句、参数和堆栈信息 - 支持异步处理，避免影响主业务线程 - 可配置堆栈信息记录深度和线程池大小 - 慢SQL信息通过日志单独存储，避免数据库表维护负担 慢SQL日志格式示例： ``` 【慢SQL】执行时间: 600ms | SQL类型: SELECT | 数据源: master | SQL: SELECT * FROM users WHERE id = ? | 参数: '1' | 堆栈信息: com.example.UserService.getUserById(UserService.java:42) ``` ### mole-common-cache #### 介绍 mole-common-cache 封装 Redis 的通用操作方法、分布式锁、提供便捷的缓存访问能力。 #### 基础组件 - RedisManager 提供get、set、ttl等通用操作方法 - RedissonLockUtil 增加了redisson的依赖提供分布式锁能力 - @EnableCaching 开启@EnableCaching后可以启用Spring 框架中缓存机制。 RedisManager 常用方法。 ```java @Autowired private RedisManager redisManager; // 示例参数 String key ="user:id:1"; UserDetails user = User.builder() .username(key) .build(); // 判断用户是否存在 boolean hasKey = redisManager.hasKey(key); // 缓存用户信息 不设置有效期 redisManager.set(key, user); // 缓存用户信息 有效期300秒 redisManager.set(key, user, 300L); // 获取用户对象（Object） Object obj = redisManager.get(key); // 获取用户对象（字符串） String str = redisManager.getStr(key); // 获取用户Bean UserDetails userBean = redisManager.getBean(key, User.class); // 设置有效期 redisManager.expire(key, 60L); ``` RedissonLockUtil 分布式锁使用 ```java @Bean public RedissonLockUtil redissonLockUtil(RedissonClient redissonClient) { return new RedissonLockUtil(redissonClient); } redissonLockUtil.execute(key, 3, 5, TimeUnit.SECONDS, () -> { log.info("任务执行中..."); return "success"; }); ``` EnableCaching缓存注解的常用方法。 ```java // 开启Spring缓存机制后，可以使用如下常用注解 // @CacheConfig 配置缓存名称 // @Cacheable 首次调用会执行方法并缓存结果，后续相同参数直接从缓存读取 // @CacheEvict 删除缓存中的数据 @CacheConfig(cacheNames = {"user"}) public interface UserServiceImpl extends IService { @CacheEvict(cacheNames = {"user"}, key = "#id") void delete(Long id); @Cacheable(cacheNames = {"user"},key = "#id",unless="#result == null") User get(Long id) { return getBaseMapper().selectById(id); } @CacheEvict(cacheNames = {"user"}, key = "#user.id",condition = "#user.id != null", unless="#result == null") Boolean saveOrUpdate(User user); } ``` ### mole-common-crypto #### 介绍 mole-common-crypto 封装请求数据的加解密逻辑，提供便捷的配置能力，保障数据传输安全。提供数字信封加密解密工具类 #### 基础组件 - @EnableCrypto 启用该注解后，默认对所有请求进行解密处理，对所有响应数据进行加密处理 - DigitEnvelopeUtil 提供数字信封加密解密工具类 1、业务系统增加@EnableCrypto注解。 ```yaml # 可手动配置忽略地址 ignore: decryptUrls: - /** encryptUrls: - /** ``` 2、 实现 IRequestDecryptService 和 IResponseEncryptService 接口，并将其注册为 Spring Bean（如通过 @Service 注解），以自定义请求解密和响应加密的具体逻辑。 DigitEnvelopeUtil 使用 ```java String cPriKeyStr = "00f4556025a71dc9ad7e022706ea122b0caa56116539cb4f175b301bb98c044021"; String cPubKeyStr = "04018de0d1d063d85335b0b0c42b0aad2b2c02fd2d85f7cca53df9e6371e0de56e82df607669d081e49a696ce81439567da0ca6dcab15c605955de34610af3fd20"; byte[] cPriKey = HexUtil.decodeHex(cPriKeyStr); byte[] cPubKey = HexUtil.decodeHex(cPubKeyStr); String sPriKeyStr = "70b2b6bc4a5973206a1e6f3d5552efa5966f46081faa1697e64e0b4ea4865417"; String sPubKeyStr = "04c37c3cbcfe0bfee4cce74dc9110c5a0bb170b446ebd351e7065009d66ed39e523694358ae47fc673b22e895ca814654c28744035164cc1ff8dfb88dad6bd0918"; byte[] sPriKey = HexUtil.decodeHex(sPriKeyStr); byte[] sPubKey = HexUtil.decodeHex(sPubKeyStr); // 加密过程. String str = "123456"; System.out.println("加密字符串:" + str); byte[] encrypt = DigitEnvelopeUtil.encrypt(str.getBytes(), sPubKey, cPriKey); System.out.println("加密之后数据长度:" + encrypt.length); System.out.println("加密之后转Hex Str:" + HexUtil.encodeHexStr(encrypt)); // 解密过程 String decStr = HexUtil.encodeHexStr(encrypt); System.out.println("解密Hex字符串:" + decStr); byte[] bytes = HexUtil.decodeHex(decStr); byte[] decrypt = DigitEnvelopeUtil.decrypt(bytes, cPubKey, sPriKey); System.out.println("解密成功:" + new String(decrypt)); ``` ### mole-common-security #### 介绍 mole-common-security 基于spring-boot-starter-security，提供spring security默认的handler配置和安全防护组件。 #### 基础组件 - SecurityHeadersFilter 用于添加安全响应头，增强浏览器端的防护 - XssFilter 用于防止 XSS 攻击，使用 OWASP Java HTML Sanitizer 进行输入过滤 - SqlInjectionFilter 用于防止 SQL 注入攻击，使用正则表达式检测常见的 SQL 注入模式 #### 使用示例 **SecurityHeadersFilter 配置** ```yaml security: headers: enabled: true content-security-policy: "default-src 'self'" xss-protection: "1; mode=block" content-type-options: "nosniff" frame-options: "DENY" strict-transport-security: "max-age=31536000; includeSubDomains" ``` **XssFilter 配置** ```yaml security: xss: enabled: true allowed-tags: "p,br,strong,em,i,b,u" exclude-patterns: - "/*/api/v1/login" ``` **SqlInjectionFilter 配置** ```yaml security: sql-injection: enabled: true injection-pattern: "(?:')|(?:--)|(/\\*(?:.|[\\n\\r])*?\\*/)|(?:\\b(?:select|update|insert|delete|drop|union|create|alter|drop|exec|execute|backup|restore|shutdown)\\b.*?(?:\\b(?:from|where|set|values|into|union|join|group|order|having|limit|offset)\\b|$))" exclude-patterns: - "/*/api/v1/login" ``` #### SecurityConfig 推荐配置（在业务工程中配置） 如果需要自定义安全配置，可以在业务工程中创建 SecurityConfig 类： ```java @EnableWebSecurity @Configuration public class SecurityConfig extends WebSecurityConfigurerAdapter { @Resource private SecurityHeadersFilter securityHeadersFilter; @Resource private XssFilter xssFilter; @Resource private SqlInjectionFilter sqlInjectionFilter; @Override protected void configure(HttpSecurity http) throws Exception { http // 配置会话管理 .sessionManagement() .sessionCreationPolicy(SessionCreationPolicy.STATELESS) .and() // 配置跨站请求伪造防护（对于 OAuth2 资源服务器，通常禁用 CSRF 防护） .csrf().disable() .and() // 配置安全拦截过滤器 .addFilterBefore(securityHeadersFilter, UsernamePasswordAuthenticationFilter.class) .addFilterBefore(xssFilter, UsernamePasswordAuthenticationFilter.class) .addFilterBefore(sqlInjectionFilter, UsernamePasswordAuthenticationFilter.class); } } ``` ### mole-common-security-oauth2 #### 介绍 mole-common-security 基于spring-security-oauth2 2.3.6.RELEASE版本，提供Spring OAuth2的默认基础配置。 ### mole-modules-base #### 介绍 mole-modules-base 后端服务基础包，在mole-common-security、mole-common-security-oauth2基础提供WebMvcConfigurer、ResourceServerConfig的基础配置。 1、PreSecretKeyConfig 预置密钥配置 可以用于StringEncryptHandler、RemoteTokenServices的加密、解密。 ```yaml # 预制密钥 secret: preSecretKey: 01cc84fa3a7d7b413488011a3a934c98 ``` 2、BaseEntity 所有实体继承此类，提供active标志删除字段。 3、UserUtil 用户Util类，提供获取当前用户、权限等通用方法。 4、ZipkinKafkaProperties zipkin的kafka模式的配置项。 5、BaseEntityFieldFillHandler，提供 fill = FieldFill.INSERT（新增）、FieldFill.INSERT_UPDATE（新增或者更新）时填充。 ```java @ApiModelProperty("主键ID") @TableId(value = "id", type = IdType.ASSIGN_ID) private Long id; @ApiModelProperty("用户名") @TableField(value = "name", typeHandler = StringEncryptHandler.class) private String name; @ApiModelProperty("乐观锁") @TableField("revision") @Version private Integer revision = 1; @ApiModelProperty("创建人") @TableField(value = "created_by", fill = FieldFill.INSERT) private String createdBy; @ApiModelProperty("创建时间") @TableField(value = "created_time", fill = FieldFill.INSERT) private LocalDateTime createdTime; @ApiModelProperty("更新人") @TableField(value = "updated_by", fill = FieldFill.INSERT_UPDATE) private String updatedBy; @ApiModelProperty("更新时间") @TableField(value = "updated_time", fill = FieldFill.INSERT_UPDATE) private LocalDateTime updatedTime; @TableField(value = "active", fill = FieldFill.INSERT) private Boolean active; ``` ## 部署到私有库 可以在pom.xml中配置distributionManagement 填写Nexus地址信息。 ```xml releases User Project Release http://XXX:8081/repository/maven-releases/ snapshots User Project Snapshots http://XXX:8081/repository/maven-snapshots/ ```