Common-Base 模块架构设计文档

1. 模块定位与设计原则

1.1 模块定位

common-base 是 BeyondSoft Spring3 Framework 的基础核心模块，为整个框架提供跨项目复用的通用基础设施。它作为其他所有 Starter 模块（Web、异常、日志、安全等）的依赖基础，承担着以下核心职责：

统一模型定义：提供标准化的响应模型、异常模型和基础实体模型
异常体系构建：建立完整的业务异常体系，支持统一异常处理
工具类集合：提供常用工具类，减少重复代码
基础依赖管理：管理跨模块共享的第三方依赖

1.2 设计原则

无业务逻辑原则：模块不包含任何具体的业务逻辑，只提供通用基础设施
弱依赖原则：对第三方库的依赖尽量设置为可选（optional），避免强制依赖
高复用原则：所有组件都设计为可跨项目复用
开闭原则：提供扩展点，支持自定义实现
单一职责原则：每个类和方法都有明确的单一职责

2. 整体架构设计

2.1 模块分层架构

common-base
├── 模型层 (model)
│   ├── 响应模型 (CommonResult, ErrorResult)
│   ├── 分页模型 (Page)
│   ├── 基础实体 (FlexBaseEntity)
│   └── 数据传输对象 (ThreadShareDataDTO)
├── 异常层 (exceptions)
│   ├── 异常基类 (RequestException)
│   ├── 业务异常 (BusinessException, ParameterInvalidException)
│   └── 异常枚举 (ResponseCodeEnums)
├── 工具层 (utils)
│   ├── Spring工具 (SpringUtil)
│   ├── IP处理工具 (IpUtils)
│   ├── 数据处理工具 (ExcelUtil, RedisUtil)
│   └── 安全工具 (SqlInjectUtils)
├── 注解层 (annotation)
│   ├── 查询条件注解 (@Eq, @Gt, @Lt)
│   ├── 操作符注解 (@AndOperator, @OrOperator)
│   └── 条件注解 (@ConditionsAnnotation)
├── 常量层 (constant)
│   ├── 通用常量 (CommonConstants)
│   ├── 请求常量 (RequestConstants)
│   └── 缓存常量 (CaffeineTimeConstant)
├── 监听器层 (listener)
│   ├── 实体监听器 (BaseEntityListener)
│   └── Excel监听器 (ExcelListener)
├── 方言层 (dialect)
│   └── 动态排序方言 (DynamicOrderByDialect)
└── 包装器层 (wrapper)
    └── 请求包装器 (MultiReadHttpServletRequestWrapper)

2.2 依赖关系图

common-base
    ├── spring-boot-starter-web (optional)
    ├── spring-boot-starter-data-redis
    ├── spring-boot-starter-data-mongodb (optional)
    ├── mybatis-flex-spring-boot3-starter (optional)
    ├── sa-token-spring-boot3-starter (optional)
    ├── fastexcel
    ├── ip2region
    ├── caffeine (optional)
    └── commons-lang3

3. 核心组件详细设计

3.1 统一响应模型设计

3.1.1 CommonResult 设计

java

// 核心设计思想：统一成功响应格式
public class CommonResult {
    private Integer status;      // HTTP状态码
    private Integer code;        // 业务状态码
    private String msg;         // 响应消息
    private Object data;        // 响应数据
    private Long timestamp;     // 时间戳
    private String traceId;     // 链路追踪ID
    private String reason;      // 详细原因
    
    // 设计特点：
    // 1. 支持链式调用（@Builder注解）
    // 2. 支持序列化（Serializable接口）
    // 3. 内置工厂方法（success(), failure()）
    // 4. 集成MDC追踪（traceId自动获取）
}

3.1.2 ErrorResult 设计

java

// 核心设计思想：统一错误响应格式
public class ErrorResult {
    private Integer status;      // HTTP状态码
    private String error;        // 错误类型
    private String msg;         // 错误消息
    private Integer code;       // 业务错误码
    private String path;        // 请求路径
    private String exception;   // 异常类名
    private String reasons;     // 详细原因
    private LocalDateTime timestamp; // 时间戳
    private Object data;        // 错误数据
    
    // 设计特点：
    // 1. 自动获取请求上下文（RequestContextHolder）
    // 2. 支持多种错误构造方式
    // 3. 与Spring Boot错误处理机制兼容
}

3.2 异常体系设计

3.2.1 异常类继承体系

Throwable
└── Exception
    └── RuntimeException
        └── RequestException (基类)
            ├── BusinessException (业务异常)
            ├── ParameterInvalidException (参数异常)
            ├── NotFoundException (资源不存在)
            ├── DataConflictException (数据冲突)
            ├── InternalServerException (服务器异常)
            ├── RemoteAccessException (远程调用异常)
            ├── ExcelException (Excel异常)
            ├── FileNotExistException (文件不存在)
            ├── RequestEncryptException (加密异常)
            └── RequestSqlInjectException (SQL注入异常)

3.2.2 异常设计原则

类型化异常：每种业务场景都有对应的异常类型
响应码关联：异常与ResponseCodeEnums枚举关联
数据携带：异常可以携带额外的业务数据
链式传播：支持异常链，便于问题追踪

3.3 工具类设计模式

3.3.1 静态工具类模式

java

// 设计模式：静态工具类 + 私有构造方法
public class IpUtils {
    private IpUtils() {} // 防止实例化
    
    // 静态方法
    public static Optional<String> getIpAddress(HttpServletRequest request) {
        // 实现逻辑
    }
}

3.3.2 Spring工具类模式

java

// 设计模式：ApplicationContextAware接口实现
public class SpringUtil implements ApplicationContextAware {
    private static ApplicationContext applicationContext;
    
    @Override
    public void setApplicationContext(ApplicationContext context) {
        applicationContext = context;
    }
    
    // 静态方法访问Bean
    public static <T> T getBean(Class<T> clazz) {
        return applicationContext.getBean(clazz);
    }
}

3.4 注解体系设计

3.4.1 查询条件注解

java

// 设计思想：基于注解的查询条件构建
@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
public @interface Eq {
    String value() default ""; // 字段名
}

// 使用示例：
public class UserQuery {
    @Eq("username")
    private String name;
    
    @Gt("age")
    private Integer minAge;
}

3.4.2 操作符注解

java

// 设计思想：支持复杂查询条件组合
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
public @interface AndOperator {
    // 表示所有条件使用AND连接
}

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
public @interface OrOperator {
    // 表示所有条件使用OR连接
}

4. 关键技术实现

4.1 IP地址解析实现

4.1.1 IP获取策略

java

public static Optional<String> getIpAddress(HttpServletRequest request) {
    // 优先级：代理头 > 直接IP
    String[] IP_HEADERS = {
        "x-forwarded-for",
        "Proxy-Client-IP", 
        "WL-Proxy-Client-IP",
        "HTTP_CLIENT_IP",
        "HTTP_X_FORWARDED_FOR"
    };
    
    // 实现特点：
    // 1. 支持多种代理场景
    // 2. 自动处理本地IP（127.0.0.1）
    // 3. 返回Optional，避免空指针
}

4.1.2 IP地理位置解析

java

public static Optional<String> getLocationInfo(String ipAddress) {
    // 使用ip2region数据库
    // 特点：
    // 1. 基于xdb文件的本地查询
    // 2. 高性能（微秒级响应）
    // 3. 内存缓存优化
}

4.2 Excel处理实现

4.2.1 基于fastexcel的实现

java

public class ExcelUtil {
    // 设计特点：
    // 1. 使用fastexcel替代POI，性能更高
    // 2. 支持大文件流式处理
    // 3. 内置监听器模式
}

4.3 缓存工具实现

4.3.1 Redis工具类

java

public class RedisUtil {
    // 设计特点：
    // 1. 基于Spring Data Redis
    // 2. 支持对象序列化
    // 3. 提供常用操作的封装
}

5. 配置与扩展

5.1 可选依赖配置

xml

<!-- 示例：可选依赖声明 -->
<dependency>
    <groupId>com.mybatis-flex</groupId>
    <artifactId>mybatis-flex-spring-boot3-starter</artifactId>
    <scope>compile</scope>
    <optional>true</optional> <!-- 关键：设置为可选 -->
</dependency>

5.2 扩展点设计

5.2.1 自定义异常扩展

java

// 扩展方式：继承RequestException
public class CustomBusinessException extends RequestException {
    public CustomBusinessException(ResponseCodeEnums code) {
        super(code);
    }
}

5.2.2 工具类扩展

java

// 扩展方式：静态方法扩展
public class CustomExcelUtil {
    public static void exportWithTemplate(List<?> data, String template) {
        // 基于ExcelUtil的扩展
        ExcelUtil.exportExcel(data, ...);
        // 自定义逻辑
    }
}

6. 性能优化设计

6.1 缓存优化

IP数据库缓存：ip2region.xdb文件内存缓存
Spring Bean缓存：ApplicationContext单例缓存
工具类静态缓存：避免重复初始化

6.2 内存优化

Optional使用：避免空指针，减少内存占用
流式处理：Excel大文件流式读取
对象池：Redis连接池管理

6.3 并发安全

无状态设计：工具类均为无状态，线程安全
不可变对象：常量类使用final修饰
线程局部变量：ThreadLocal使用（如MDC）

7. 安全设计

7.1 SQL注入防护

java

public class SqlInjectUtils {
    // 防护策略：
    // 1. 关键字检测
    // 2. 特殊字符过滤
    // 3. 正则表达式匹配
}

7.2 请求安全

多次读取包装：MultiReadHttpServletRequestWrapper
参数校验：内置参数校验逻辑
异常安全：避免敏感信息泄露

8. 测试策略

8.1 单元测试覆盖

工具类测试：每个工具方法都需要单元测试
异常测试：测试异常抛出和捕获逻辑
模型测试：测试序列化和反序列化

8.2 集成测试

Spring上下文测试：测试SpringUtil等Spring相关工具
数据库测试：测试方言和实体监听器
文件操作测试：测试Excel和文件操作

9. 部署与维护

9.1 依赖管理

版本管理：通过父POM统一管理版本
可选依赖：非核心依赖设置为optional
冲突解决：排除有冲突的传递依赖

9.2 资源文件管理

IP数据库：ip2region.xdb放在resources/db目录
配置文件：支持外部化配置
模板文件：Excel模板等资源文件管理

10. 最佳实践

10.1 使用规范

异常使用：业务异常使用BusinessException及其子类
响应返回：Controller返回实体，由Web模块统一包装
工具调用：直接使用静态方法，无需实例化

10.2 开发规范

代码风格：遵循阿里巴巴Java开发规范
文档要求：所有公共API都需要JavaDoc注释
测试要求：核心功能必须有单元测试

10.3 性能规范

内存使用：大文件使用流式处理
缓存策略：合理使用缓存，避免内存泄漏
并发处理：注意线程安全问题

11. 常见问题与解决方案

11.1 IP解析失败

问题：无法获取客户端真实IP 解决方案：

检查代理配置是否正确
验证IP头优先级设置
使用getIpAddress()的Optional返回值

11.2 Excel内存溢出

问题：处理大Excel文件时内存溢出 解决方案：

使用ExcelUtil的流式读取方法
分批处理数据
增加JVM堆内存

11.3 Spring上下文获取失败

问题：SpringUtil.getBean()返回null 解决方案：

确保SpringUtil已正确初始化
检查Bean是否已正确注册
确认调用时机（不能在静态初始化块中使用）

12. 未来演进规划

12.1 短期规划

性能优化：进一步优化工具类性能
功能扩展：增加更多常用工具类
文档完善：补充更多使用示例和最佳实践

12.2 长期规划

模块拆分：根据功能将大模块拆分为更小的子模块
云原生支持：增强对云原生环境的支持
生态集成：与更多开源框架集成

文档信息

版本：1.0.0
更新日期：2025-12-30
维护团队：BeyondSoft 架构组
文档状态：正式发布

变更记录

版本	日期	描述	作者
1.0.0	2025-12-30	初始版本创建	架构组

Common-Base 模块架构设计文档 ​

1. 模块定位与设计原则 ​

1.1 模块定位 ​

1.2 设计原则 ​

2. 整体架构设计 ​

2.1 模块分层架构 ​

2.2 依赖关系图 ​

3. 核心组件详细设计 ​

3.1 统一响应模型设计 ​

3.1.1 CommonResult 设计 ​

3.1.2 ErrorResult 设计 ​

3.2 异常体系设计 ​

3.2.1 异常类继承体系 ​

3.2.2 异常设计原则 ​

3.3 工具类设计模式 ​

3.3.1 静态工具类模式 ​

3.3.2 Spring工具类模式 ​

3.4 注解体系设计 ​

3.4.1 查询条件注解 ​

3.4.2 操作符注解 ​

4. 关键技术实现 ​

4.1 IP地址解析实现 ​

4.1.1 IP获取策略 ​

4.1.2 IP地理位置解析 ​

4.2 Excel处理实现 ​

4.2.1 基于fastexcel的实现 ​

4.3 缓存工具实现 ​

4.3.1 Redis工具类 ​

5. 配置与扩展 ​

5.1 可选依赖配置 ​

5.2 扩展点设计 ​

5.2.1 自定义异常扩展 ​

5.2.2 工具类扩展 ​

6. 性能优化设计 ​

6.1 缓存优化 ​

6.2 内存优化 ​

6.3 并发安全 ​

7. 安全设计 ​

7.1 SQL注入防护 ​

7.2 请求安全 ​

8. 测试策略 ​

8.1 单元测试覆盖 ​

8.2 集成测试 ​

9. 部署与维护 ​

9.1 依赖管理 ​

9.2 资源文件管理 ​

10. 最佳实践 ​

10.1 使用规范 ​

10.2 开发规范 ​

10.3 性能规范 ​

11. 常见问题与解决方案 ​

11.1 IP解析失败 ​

11.2 Excel内存溢出 ​

11.3 Spring上下文获取失败 ​

12. 未来演进规划 ​

12.1 短期规划 ​

12.2 长期规划 ​

Common-Base 模块架构设计文档

1. 模块定位与设计原则

1.1 模块定位

1.2 设计原则

2. 整体架构设计

2.1 模块分层架构

2.2 依赖关系图

3. 核心组件详细设计

3.1 统一响应模型设计

3.1.1 CommonResult 设计

3.1.2 ErrorResult 设计

3.2 异常体系设计

3.2.1 异常类继承体系

3.2.2 异常设计原则

3.3 工具类设计模式

3.3.1 静态工具类模式

3.3.2 Spring工具类模式

3.4 注解体系设计

3.4.1 查询条件注解

3.4.2 操作符注解

4. 关键技术实现

4.1 IP地址解析实现

4.1.1 IP获取策略

4.1.2 IP地理位置解析

4.2 Excel处理实现

4.2.1 基于fastexcel的实现

4.3 缓存工具实现

4.3.1 Redis工具类

5. 配置与扩展

5.1 可选依赖配置

5.2 扩展点设计

5.2.1 自定义异常扩展

5.2.2 工具类扩展

6. 性能优化设计

6.1 缓存优化

6.2 内存优化

6.3 并发安全

7. 安全设计

7.1 SQL注入防护

7.2 请求安全

8. 测试策略

8.1 单元测试覆盖

8.2 集成测试

9. 部署与维护

9.1 依赖管理

9.2 资源文件管理

10. 最佳实践

10.1 使用规范

10.2 开发规范

10.3 性能规范

11. 常见问题与解决方案

11.1 IP解析失败

11.2 Excel内存溢出

11.3 Spring上下文获取失败

12. 未来演进规划

12.1 短期规划

12.2 长期规划