framework-common - 通用工具模块

1. 模块概述

framework-common 是 epoch-framework 的核心基础模块，提供了一系列通用工具类和功能组件，供其他模块和应用使用。该模块是整个框架的基础，包含了各种常用的工具类、常量定义、异常处理、数据模型等。

2. 模块结构

framework-common/
├── async/           # 异步任务相关
├── consts/          # 常量定义
├── core/            # 核心工具类
├── domain/          # 领域模型
├── enums/           # 枚举类
├── exception/       # 异常处理
├── pojo/            # 数据传输对象
├── resp/            # 响应码系统
└── util/            # 工具类集合
    ├── json/        # JSON 处理工具
    ├── monitor/     # 监控相关工具
    ├── servlet/     # Servlet 相关工具
    └── spirng/      # Spring 相关工具

3. 核心功能

3.1 async - 异步任务

提供异步任务执行的配置和服务。

主要类：

• CommonTaskExecutorConfig：异步任务执行器配置类，配置线程池参数
• CommonTaskExecutorService：异步任务执行服务，提供异步任务提交和执行功能

使用示例：

@Autowired
private CommonTaskExecutorService executorService;

executorService.execute(() -> {
    // 异步执行的任务逻辑
});

3.2 consts - 常量定义

定义框架通用的常量。

主要类：

• Constants：框架通用常量定义，包含各种业务常量和系统常量

核心常量：

• 分页默认参数（页码、每页条数等）
• 通用状态码（成功、失败等）
• 日期格式
• 缓存键前缀

3.3 core - 核心工具类

提供框架核心的工具类。

主要类：

• Assert：断言工具类，提供各种断言方法，用于参数校验和业务逻辑验证
• UserUtils：用户信息获取工具类，用于获取当前登录用户信息

使用示例：

// 断言参数非空
Assert.notNull(param, "参数不能为空");

// 获取当前登录用户ID
Long userId = UserUtils.getCurrentUserId();

3.4 domain - 领域模型

定义框架通用的领域模型。

主要类：

• LoginUserInfo：登录用户信息模型，包含用户基本信息和权限信息
• TreeShowVo：树形结构展示模型，用于构建和展示树形数据

核心字段：

// LoginUserInfo
private Long userId;
private String username;
private String realName;
private List<String> roles;
private List<String> permissions;

// TreeShowVo
private Long id;
private Long parentId;
private String name;
private List<TreeShowVo> children;

3.5 enums - 枚举类

定义框架通用的枚举类。

主要类：

• WebFilterOrderEnum：Web 过滤器顺序枚举，定义各种过滤器的执行顺序

核心枚举值：

• CORS_FILTER：跨域过滤器
• AUTH_FILTER：认证过滤器
• LOG_FILTER：日志过滤器
• XSS_FILTER：XSS防护过滤器

3.6 exception - 异常处理

定义框架的异常处理体系。

主要类：

• BusinessException：业务异常基类，所有业务异常都应继承此类

核心特性：

• 支持自定义错误码和错误信息
• 支持携带额外参数
• 与全局异常处理器集成

使用示例：

if (user == null) {
    throw new BusinessException(GlobalErrorCode.USER_NOT_FOUND);
}

3.7 pojo - 数据传输对象

定义框架通用的数据传输对象。

主要类：

• PageParam：分页参数模型，用于接收分页查询参数
• ResponseResult：统一响应结果模型，用于包装API响应数据

使用示例：

// 分页参数
@PostMapping("/page")
public ResponseResult<IPage<UserVO>> page(@RequestBody PageParam<UserQueryDTO> pageParam) {
    // 处理分页查询
}

// 响应结果
return ResponseResult.success(data);
return ResponseResult.error(GlobalErrorCode.SYSTEM_ERROR);

3.8 resp - 响应码系统

定义框架的响应码体系。

主要类：

• BaseErrorCode：基础错误码接口，定义错误码的基本属性
• ErrorCode：错误码扩展接口，定义错误码的扩展属性
• GlobalErrorCode：全局错误码定义，包含系统级错误码

核心错误码：

• SUCCESS：操作成功
• SYSTEM_ERROR：系统错误
• PARAM_ERROR：参数错误
• USER_NOT_FOUND：用户不存在
• PERMISSION_DENIED：权限不足

3.9 util - 工具类集合

提供各种常用的工具类。

3.9.1 json - JSON 处理工具

• JsonUtils：JSON 序列化/反序列化工具，基于 Jackson 实现

主要方法：

// 对象转JSON字符串
String json = JsonUtils.toJson(obj);

// JSON字符串转对象
User user = JsonUtils.parse(json, User.class);

// JSON字符串转集合
List<User> userList = JsonUtils.parseList(json, User.class);

3.9.2 monitor - 监控相关工具

• TracerUtils：分布式追踪工具，集成 SkyWalking 实现分布式追踪

主要方法：

// 获取当前追踪ID
String traceId = TracerUtils.getTraceId();

// 向追踪链路添加标签
TracerUtils.addTag("key", "value");

3.9.3 servlet - Servlet 相关工具

• ServletUtils：Servlet 相关工具，用于处理 HTTP 请求和响应

主要方法：

// 获取请求IP
String ip = ServletUtils.getClientIP(request);

// 获取请求参数
String param = ServletUtils.getParameter(request, "key");

// 获取请求头
String header = ServletUtils.getHeader(request, "User-Agent");

3.9.4 spirng - Spring 相关工具

• SpringExpressionUtils：Spring 表达式工具，用于解析和执行 Spring EL 表达式
• SpringUtils：Spring 上下文工具，用于获取 Spring 容器中的 Bean

主要方法：

// 获取Spring Bean
UserService userService = SpringUtils.getBean(UserService.class);

// 执行Spring EL表达式
Object result = SpringExpressionUtils.evaluateExpression(expression, context);

3.9.5 其他工具类

• StreamUtils：Stream 流操作工具，提供各种 Stream 流的便捷操作
• StringUtils：字符串操作工具，提供各种字符串处理方法
• ValidatorUtils：参数校验工具，基于 JSR-380 实现参数校验

使用示例：

// 字符串判空
if (StringUtils.isEmpty(str)) {
    // 处理空字符串
}

// Stream 操作
List<Long> ids = StreamUtils.map(list, User::getId);

// 参数校验
ValidationResult result = ValidatorUtils.validate(obj);
if (!result.isValid()) {
    // 处理校验失败
}

4. 设计理念

4.1 高内聚低耦合

将相关功能组织在一起，提高模块内聚性；同时与其他模块保持低耦合，通过接口和抽象进行交互。

4.2 易用性

提供简洁易用的 API，减少使用成本；同时提供丰富的文档和示例。

4.3 可扩展性

预留扩展接口，支持自定义实现；同时提供默认实现，满足大多数需求。

4.4 性能优化

对性能敏感的功能进行优化，如异步任务的线程池配置、JSON 序列化的性能优化等。

5. 使用指南

5.1 引入依赖

<dependency>
    <groupId>com.epoch</groupId>
    <artifactId>framework-common</artifactId>
    <version>${epoch.version}</version>
</dependency>

5.2 配置说明

大部分功能不需要额外配置，直接使用即可。对于异步任务等需要配置的功能，可以在 application.yml 中进行配置：

epoch:
  common:
    async:
      core-pool-size: 10
      max-pool-size: 50
      queue-capacity: 100
      keep-alive-seconds: 60

5.3 最佳实践

1. 优先使用框架提供的工具类：避免重复造轮子，提高代码一致性
2. 遵循框架规范：使用框架提供的异常处理、响应格式等规范
3. 合理使用异步任务：对于耗时操作，使用异步任务提高系统性能
4. 注意线程安全：在多线程环境下使用工具类时，注意线程安全问题

6. 版本变更

6.1 主要变更

• 3.4.0：

  • 新增 StreamUtils 工具类
  • 优化 JSON 序列化性能
  • 完善分布式追踪功能

• 3.3.0：

  • 重构异常处理体系
  • 新增 ValidationUtils 工具类
  • 优化响应码系统

• 3.2.0：

  • 新增异步任务功能
  • 完善 Spring 工具类
  • 优化字符串工具类

7. 常见问题

7.1 如何获取当前登录用户信息？

使用 UserUtils 工具类：

LoginUserInfo userInfo = UserUtils.getCurrentUserInfo();
Long userId = UserUtils.getCurrentUserId();

7.2 如何处理业务异常？

抛出自定义业务异常或使用全局错误码：

// 使用自定义错误码
throw new BusinessException("CUSTOM_ERROR", "自定义错误信息");

// 使用全局错误码
throw new BusinessException(GlobalErrorCode.PARAM_ERROR);

7.3 如何使用异步任务？

注入 CommonTaskExecutorService 并使用：

@Autowired
private CommonTaskExecutorService executorService;

executorService.execute(() -> {
    // 异步执行的任务逻辑
});

CompletableFuture<String> future = executorService.submit(() -> {
    // 异步执行并返回结果
    return "result";
});

7.4 如何进行参数校验？

使用 ValidatorUtils 工具类：

// 校验对象
ValidationResult result = ValidatorUtils.validate(user);
if (!result.isValid()) {
    throw new BusinessException(GlobalErrorCode.PARAM_ERROR, result.getErrorMessages());
}

// 使用注解进行校验
@Valid
@RequestBody User user