# common-framework

**Repository Path**: zpache/common-framework

## Basic Information

- **Project Name**: common-framework
- **Description**: 基础框架及公共组件。
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-04
- **Last Updated**: 2026-02-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 基础组件

## operate-log-spring-boot-starter 日志切面组件
### 介绍
> 将日志记录功能封装为SpringBoot Starter 自定义组件，是实现跨项目复用的最佳方案，完全遵循 Spring 生态的自动装配规范，其他项目只需引入 Maven/Gradle 依赖，无需手动配置 Bean、AOP 等，即可通过注解快速使用日志功能，真正做到开箱即用、零侵入复用。

### 核心功能
- **极致解耦：** 组件仅负责「日志采集封装」，用户负责「日志落地处理」，两者通过标准接口解耦，无任何代码耦合；
- **自动切换：** 基于@ConditionalOnMissingBean实现「默认实现 + 用户自定义覆盖」，用户无需手动配置开关，Spring 自动完成切换；
- **高度灵活：** 用户可实现任意日志操作（存库、发 MQ、写 ES、存文件、多端同步），只需实现统一接口，组件完全不限制；
- **轻量通用：** 默认实现仅做日志打印，无任何存储依赖，适配所有 SpringBoot 项目，开箱即用；
- **向后兼容：** 原有所有功能（注解配置、异步处理、脱敏、上下文封装）完全保留，用户无需修改原有业务代码；
- **易于扩展：** 后续组件升级仅需维护标准接口，无需关心用户的具体实现；用户扩展日志功能仅需实现接口，无需修改组件代码；
- **符合Spring生态：** 完全遵循 Spring 的自动装配、依赖注入、条件注解等规范，无任何自定义语法，用户学习成本为 0。


### 快速使用
```xml
<!-- 引入操作日志 Starter 组件（自动装配，开箱即用） -->
<dependency>
    <groupId>io.gitee.zpache</groupId>
    <artifactId>operate-log-spring-boot-starter</artifactId>
    <version>1.0.0</version>
</dependency>
```

### 默认配置
```yaml
# 操作日志 Starter 自定义配置（可选，无配置则用默认值）
operate:
  log:
    enabled: true # 是否开启日志功能
    desensitize: true # 是否开启敏感信息脱敏
    core-pool-size: 8 # 异步线程池核心线程数
    max-pool-size: 30 # 异步线程池最大线程数
    queue-capacity: 200 # 队列容量
    thread-name-prefix: my-project-log- # 自定义线程名前缀
    ignore-null-param: false # 不忽略空参数
```

### 适配扩展
业务项目只需继承 **Starter** 的 **WebContextUtil**，重写**操作用户信息、敏感信息脱敏**的扩展方法，适配自身项目的登录框架和业务规则，无需修改其他代码。
```java
/**
 * 业务项目重写Starter的上下文工具类，适配自身用户信息和脱敏规则
 * 注解@Component：将此类注入Spring容器，覆盖Starter的默认WebContextUtil Bean
 */
@Component
public class ProjectWebContextUtil extends WebContextUtil {

    // ========== 重写：适配SpringSecurity操作用户信息 ==========
    @Override
    public Long getOperateUserId() {
        Authentication authentication = SecurityContextHolder.getContext().getAuthentication();
        if (authentication == null || !authentication.isAuthenticated()) {
            return 0L;
        }
        Object principal = authentication.getPrincipal();
        if (principal instanceof SysUser) {
            return ((SysUser) principal).getId();
        }
        return 0L;
    }

    @Override
    public String getOperateUserName() {
        Authentication authentication = SecurityContextHolder.getContext().getAuthentication();
        if (authentication == null || !authentication.isAuthenticated()) {
            return "匿名用户";
        }
        Object principal = authentication.getPrincipal();
        if (principal instanceof SysUser) {
            return ((SysUser) principal).getUserName();
        }
        return authentication.getName();
    }

    // ========== 重写：自定义敏感信息脱敏规则 ==========
    @Override
    public Object desensitize(Object obj) {
        if (obj == null) {
            return null;
        }
        // 1. 手机号脱敏：138****1234
        if (obj instanceof String str) {
            if (str.matches("^1[3-9]\\d{9}$")) {
                return str.replaceAll("(\\d{3})\\d{4}(\\d{4})", "$1****$2");
            }
            // 2. 身份证脱敏：110**********1234
            if (str.matches("^\\d{18}$")) {
                return str.replaceAll("(\\d{3})\\d{10}(\\d{4})", "$1**********$2");
            }
            // 3. 密码脱敏：******
            if (str.contains("password") || str.contains("pwd")) {
                return "******";
            }
        }
        // 4. 自定义实体类脱敏（如UserVO的password字段）
        if (obj instanceof SysUser user) {
            user.setPassword("******");
            user.setPhone(desensitize(user.getPhone()).toString());
            return user;
        }
        return obj;
    }
}
```
> 关键：业务项目的 ProjectWebContextUtil 加 @Component 注解后，会自动覆盖 Starter 中的默认 WebContextUtil Bean，Spring 会优先注入业务项目的实现类。