JPwise-docs

Appearance

架构参考文档 ​

🏗️ 系统架构：JPwise项目的完整架构说明和技术栈详解

📋 目录 ​

项目总览 ​

项目基本信息 ​

  • 项目名称: JPwise (jpwise-java-boot)
  • 技术架构: 基于 Spring Boot 3.2.4 的企业级应用平台
  • 架构模式: 模块化单体架构
  • 主要功能: 工作流管理、文档协作、系统管理等企业功能

核心特性 ​

  • ✅ 模块化设计 - 各功能模块独立开发和部署
  • ✅ 工作流集成 - 内置完整的工作流引擎
  • ✅ 多数据源支持 - 支持多种数据库类型
  • ✅ 统一工具体系 - 丰富的封装工具类
  • ✅ 快速开发框架 - Basic继承体系减少重复代码

模块架构 ​

模块划分 ​

jpwise-java-boot/
├── jpwise-admin/          # 🚀 主应用模块和入口
├── jpwise-common/         # 🔧 共享工具、配置和基础类
├── jpwise-system/         # 💼 核心系统功能
├── jpwise-workflow/       # 📋 工作流引擎和流程管理
├── jpwise-visualdev/      # 🎨 可视化开发工具和表单构建器
├── jpwise-file/           # 📁 文件管理和存储服务
├── jpwise-extend/         # 📈 业务扩展和自定义模块
├── jpwise-hr/            # 👥 人力资源模块
├── jpwise-officeAuto/    # 📄 办公自动化模块
├── jpwise-design/        # 🎯 设计项目模块
└── jpwise-docSystem/     # 📚 档案系统模块

模块职责 ​

jpwise-admin (主应用模块) ​

  • 作用: 项目启动入口和配置中心
  • 主类: jpwise.JpWiseAdminApplication
  • 端口: 30000
  • 包含: 主配置、启动类、全局配置

jpwise-common (核心模块) ⭐ ​

  • 作用: 提供所有工具类、基础配置、公共组件
  • 核心内容:
    • 工具类 (jpwise.util.*)
    • 基础实体 (jpwise.model.base.*)
    • 常量定义 (jpwise.constant.*)
    • 异常定义 (jpwise.exception.*)

jpwise-system (系统模块) ​

  • 作用: 核心系统功能
  • 包含: 用户管理、权限控制、菜单管理、组织架构

jpwise-workflow (工作流模块) ​

  • 作用: 工作流引擎和流程管理
  • 重要: 不要在业务模块中重复实现工作流接口

jpwise-extend (主要开发模块) ⭐ ​

  • 作用: 业务扩展和自定义开发
  • 数据源: DbNameConst.JPWISE_DEMO
  • 用途: 大部分新功能在此模块开发

技术栈详解 ​

核心框架 ​

xml
<!-- Spring Boot 3.2.4 -->
<spring-boot.version>3.2.4</spring-boot.version>

<!-- Java 17+ -->
<java.version>17</java.version>

<!-- MyBatis-Flex 1.10.8 (ORM框架) -->
<mybatis-flex.version>1.10.8</mybatis-flex.version>

<!-- Sa-Token 1.39.0 (权限认证) -->
<sa-token.version>1.39.0</sa-token.version>

<!-- Jackson 2.18.3 (JSON处理) -->
<jackson.version>2.18.3</jackson.version>

数据库支持 ​

  • MySQL: 5.7.x+ / 8.0.x (主要支持)
  • SQL Server: 2012+
  • Oracle: 11g+
  • PostgreSQL: 12+
  • 达梦 DM8: 企业版支持
  • 人大金仓 KingbaseES: V8 R6

缓存和存储 ​

  • Redis: 5.0+ (Windows) / 6.0.x+ (Linux/Mac)
  • Redisson: 3.x (Redis客户端)
  • 本地存储: 支持本地文件存储
  • MinIO: 对象存储支持

构建工具 ​

  • Maven: 3.6.3+ (构建工具)
  • JDK: OpenJDK 17 (推荐)

三层架构 ​

架构模式 ​

┌─────────────────┐
│   Controller    │ ← REST API层，处理HTTP请求
│   (接口层)      │
└─────────────────┘
         ↓
┌─────────────────┐
│    Service      │ ← 业务逻辑层，处理业务规则
│   (业务层)      │
└─────────────────┘
         ↓
┌─────────────────┐
│     Mapper      │ ← 数据访问层，操作数据库
│   (数据层)      │
└─────────────────┘

Controller层职责 ​

java
@RestController
@RequestMapping("/api/extend/Business")
public class BusinessController {
    
    // 职责：
    // 1. 接收HTTP请求
    // 2. 参数验证和转换
    // 3. 调用Service层方法
    // 4. 返回统一格式的响应
    
    @BuildQuery
    @GetMapping
    public ActionResult<PageListVO<BusinessEntity>> getList(QueryBuilder pagination) {
        List<BusinessEntity> data = businessService.getList(pagination);
        PaginationVO paginationVO = JsonUtil.getJsonToBean(pagination, PaginationVO.class);
        return ActionResult.page(data, paginationVO);
    }
}

Service层职责 ​

java
@Service
@UseDataSource(DbNameConst.JPWISE_DEMO)
public class BusinessServiceImpl extends ServiceImpl<BusinessMapper, BusinessEntity> 
                                implements BusinessService {
    
    // 职责：
    // 1. 业务逻辑处理
    // 2. 事务管理
    // 3. 数据验证
    // 4. 调用Mapper层操作数据
    // 5. 缓存管理
    // 6. 消息通知
    
    @Override
    @Transactional(rollbackFor = Exception.class)
    public void create(BusinessEntity entity) {
        // 业务逻辑处理
        validateBusiness(entity);
        setDefaultValues(entity);
        this.save(entity);
        sendNotification(entity);
    }
}

Mapper层职责 ​

java
@Mapper
public interface BusinessMapper extends BaseMapper<BusinessEntity> {
    
    // 职责：
    // 1. 数据库CRUD操作
    // 2. 复杂SQL查询
    // 3. 数据映射
    
    // MyBatis-Flex通过Service实现类提供的基础操作：
    // - this.save() 保存
    // - this.updateById() 更新
    // - this.getById() 查询
    // - this.list() 列表查询
    // - this.page() 分页查询
}

统一返回格式 ​

ActionResult结构 ​

java
public class ActionResult<T> {
    private int code;           // 状态码
    private String msg;         // 消息
    private T data;            // 数据
    private long time;         // 时间戳
    // 分页字段
    private PaginationVO pagination;
    
    // 静态方法
    public static <T> ActionResult<T> success(T data);
    public static <T> ActionResult<T> fail(String message);
    public static <T> ActionResult<T> page(List<T> data, PaginationVO pagination);
}

使用方式 ​

java
// 成功返回数据
return ActionResult.success(entity);

// 成功返回消息
return ActionResult.success(MsgCode.SU001.get());

// 失败返回
return ActionResult.fail("操作失败");
return ActionResult.fail(MsgCode.FA001.get());

// 分页返回
return ActionResult.page(dataList, paginationVO);

响应格式 ​

json
{
    "code": 200,
    "msg": "操作成功",
    "data": {
        // 具体数据
    },
    "time": 1692000000000
}

异常体系 ​

异常类层次 ​

java
// 项目定义的异常类
jpwise.exception.BusinessException    // 业务异常
jpwise.exception.DataException       // 数据异常
jpwise.exception.WorkFlowException   // 工作流异常

// 使用方式
if (businessConditionFails) {
    throw new BusinessException("业务规则验证失败");
}

if (dataValidationFails) {
    throw new DataException("数据格式错误");
}

if (workflowError) {
    throw new WorkFlowException("工作流状态异常");
}

全局异常处理 ​

java
@ControllerAdvice
public class GlobalExceptionHandler {
    
    @ExceptionHandler(BusinessException.class)
    public ActionResult handleBusinessException(BusinessException e) {
        return ActionResult.fail(e.getMessage());
    }
    
    @ExceptionHandler(DataException.class)
    public ActionResult handleDataException(DataException e) {
        return ActionResult.fail("数据异常：" + e.getMessage());
    }
}

数据库架构 ​

多数据源配置 ​

java
// 数据源常量
public class DbNameConst {
    public static final String JPWISE_BASE = "jpwise_base";      // 基础数据库
    public static final String JPWISE_DEMO = "jpwise_demo";      // 测试项目
    public static final String JPWISE_HR = "jpwise_hr";          // 人力资源
    public static final String JPWISE_AFFAIR = "jpwise_affair";  // 事务数据库
    public static final String JPWISE_DESIGN = "jpwise_design";  // 设计项目
    public static final String JPWISE_DOCSYSTEM = "jpwise_docsystem"; // 档案系统
}

// 使用方式
@Service
@UseDataSource(DbNameConst.JPWISE_DEMO)
public class BusinessServiceImpl { }

MyBatis-Flex特性 ​

java
// 1. 实体映射
@Table("business_table")
public class BusinessEntity {
    @Id
    @Column("id")
    private String id;
    
    @Column("name")
    private String name;
}

// 2. 查询构建器
QueryWrapper queryWrapper = new QueryWrapper();
queryWrapper.eq(Entity::getName, "test")
           .like(Entity::getDescription, "keyword")
           .between(Entity::getCreateTime, startDate, endDate);

// 3. 分页查询 - 在Service实现类中使用
Page<Entity> page = new Page<>(1, 10);
Page<Entity> result = this.page(page, queryWrapper);

缓存架构 ​

Redis集成 ​

java
@Autowired
private RedisUtil redisUtil;

// 基础操作
redisUtil.insert(key, data, RedisUtil.CACHE_HOUR);  // 存储1小时
redisUtil.insert(key, data, RedisUtil.CACHE_DAY);   // 存储1天
Object value = redisUtil.getString(key);             // 获取
redisUtil.remove(key);                               // 删除

// 复杂对象
Map<String, Object> map = redisUtil.getMap(key);

缓存策略 ​

java
public BusinessEntity getWithCache(String id) {
    // 1. 先查缓存
    String cacheKey = "business:" + id;
    BusinessEntity cached = (BusinessEntity) redisUtil.getString(cacheKey);
    if (cached != null) {
        return cached;
    }
    
    // 2. 查数据库
    BusinessEntity entity = this.getById(id);
    if (entity != null) {
        // 3. 存入缓存
        redisUtil.insert(cacheKey, entity, RedisUtil.CACHE_HOUR);
    }
    
    return entity;
}

统一配置 ​

环境配置 ​

yaml
# application.yml
spring:
  profiles:
    active: dev  # dev, test, preview, pro

# 各环境配置文件
application-dev.yml      # 开发环境
application-test.yml     # 测试环境
application-preview.yml  # 预发布环境
application-pro.yml      # 生产环境

关键配置项 ​

yaml
# 服务端口
server:
  port: 30000

# 数据源配置
spring:
  datasource:
    # 多数据源配置...

# MyBatis-Flex配置
mybatis-flex:
  configuration:
    map-underscore-to-camel-case: false  # 不转换下划线
    
# Redis配置
spring:
  redis:
    host: localhost
    port: 6379

开发工作流 ​

标准开发流程 ​

mermaid
graph LR
    A[需求分析] --> B[选择开发方式]
    B --> C{Basic继承?}
    C -->|是| D[继承BasicController]
    C -->|否| E[手工实现]
    D --> F[使用工具类]
    E --> F
    F --> G[编写业务逻辑]
    G --> H[测试验证]
    H --> I[代码审查]

质量保证 ​

  • 代码规范: 统一的代码风格和命名规范
  • 单元测试: JUnit 5 测试框架
  • 集成测试: 完整的接口测试
  • 代码审查: 团队代码审查流程

监控和运维 ​

应用监控 ​

  • 健康检查: Spring Boot Actuator
  • 日志管理: Logback日志框架
  • 性能监控: 内置性能统计

部署架构 ​

  • 单体部署: 传统WAR包部署
  • 容器化: Docker容器支持
  • 配置管理: 外部配置文件管理

💡 架构优势：JPwise采用模块化单体架构，既保持了单体应用的简单性，又具备了模块化的灵活性。通过统一的工具体系和开发规范，确保了代码质量和开发效率。