JavaFX + Spring Boot 桌面应用脚手架：开箱即用的企业级开发框架

📖 前言

在 Java 桌面应用开发领域，JavaFX 作为 Oracle 官方推荐的 GUI 框架，相比 Swing 具有更现代化的界面和更丰富的功能。然而，从零开始搭建一个完整的 JavaFX 应用框架往往需要大量的基础工作，包括用户权限管理、数据库集成、异常处理、日志记录等模块的开发。

为了帮助开发者快速搭建 JavaFX 桌面应用，我开源了一个基于 JavaFX + Spring Boot 的脚手架项目，集成了企业级应用开发中常用的功能模块，真正做到开箱即用。

✨ 项目亮点

🎯 核心特性

• ✅ 完整的权限管理系统：用户、角色、权限三级管理，支持细粒度权限控制
• ✅ Selenium 自动化集成：内置 WebDriver，支持浏览器自动化操作
• ✅ 操作日志记录：基于 AOP 的日志拦截，异步保存，性能优异
• ✅ 全局异常处理：统一的异常处理机制，优雅的错误提示
• ✅ 丰富的工具类库：日期、字符串、文件、JSON、HTTP、Excel 等 10+ 工具类
• ✅ 现代化 UI 设计：Bootstrap 风格样式，界面美观大方
• ✅ 开箱即用：完善的配置文件和数据库脚本，5 分钟快速启动

🛠️ 技术栈

技术	版本	说明
Java	1.8+	JDK 8 内置 JavaFX
Spring Boot	2.1.4	核心框架
MyBatis Plus	3.x	ORM 框架
MySQL	5.7+	数据库
Selenium	4.x	浏览器自动化
Lombok	-	简化代码
Druid	-	数据库连接池

📦 功能模块详解

1. 用户权限管理模块

完整的 RBAC（基于角色的访问控制）权限系统，包括：

• 用户管理：登录、登出、用户信息管理
• 角色管理：角色创建、编辑、删除
• 权限管理：权限编码、权限描述
• 关联关系：用户-角色关联、角色-权限关联
• 安全特性：BCrypt 密码加密、Session 管理、Token 机制

使用示例：

@Autowired
private UserService userService;

// 用户登录
User user = userService.login("admin", "admin123");

// 检查权限
boolean hasPermission = userService.hasPermission(user.getId(), "user:add");

2. Selenium 自动化模块

内置完整的 Selenium WebDriver 支持，封装了常用的浏览器操作：

• 支持 Chrome、Firefox、Edge 浏览器
• 无头模式运行（后台执行）
• 元素定位与操作（ID、Class、XPath、CSS 选择器）
• 页面等待机制（显式等待、隐式等待）
• 截图功能、Cookie 管理、JavaScript 执行

使用示例：

@Autowired
private SeleniumService seleniumService;

// 打开网页
seleniumService.navigateTo("https://www.example.com");

// 查找元素并点击
seleniumService.click(By.id("submit-btn"));

// 输入文本
seleniumService.sendKeys(By.name("username"), "testuser");

// 截图保存
seleniumService.takeScreenshot("screenshot.png");

3. 操作日志模块

基于 Spring AOP 实现的操作日志记录，支持：

• 自动拦截标注了 @Log 注解的方法
• 异步保存日志，不影响业务性能
• 记录操作模块、操作类型、请求参数、返回结果
• 支持自定义日志内容

使用示例：

@Log(module = "用户管理", operateType = "INSERT", saveRequestParam = true)
public void createUser(User user) {
    // 业务逻辑
    // 操作日志会自动记录
}

4. 全局异常处理模块

统一的异常处理机制，包括：

• 业务异常（BusinessException）：用户操作错误、数据验证失败等
• 系统异常（SystemException）：系统内部错误、数据库连接失败等
• 统一响应格式：所有异常统一封装为 Result 对象
• 优雅的错误提示：用户友好的错误信息展示

使用示例：

// 抛出业务异常
throw new BusinessException("用户名或密码错误");

// 抛出系统异常
throw new SystemException("数据库连接失败");

5. 工具类库

项目内置了 10+ 个常用工具类，覆盖日常开发需求：

• DateUtil：日期时间格式化、计算、转换
• StringUtil：字符串操作、验证、格式化
• FileUtil：文件读写、复制、删除
• JsonUtil：JSON 序列化、反序列化
• HttpUtil：HTTP GET/POST 请求
• ExcelUtil：Excel 文件读写（基于 Apache POI）
• ValidationUtil：数据验证（邮箱、手机号、身份证等）
• CollectionUtil：集合操作、转换
• RandomUtil：随机数生成
• ImageUtil：图片处理、压缩、格式转换

使用示例：

// 日期格式化
String dateStr = DateUtil.format(LocalDateTime.now(), "yyyy-MM-dd HH:mm:ss");

// JSON 处理
String json = JsonUtil.toJson(user);
User user = JsonUtil.parseObject(json, User.class);

// Excel 读取
List<Map<String, Object>> data = ExcelUtil.readExcel("data.xlsx");

// HTTP 请求
String response = HttpUtil.get("https://api.example.com/data");

🚀 快速开始

环境要求

• JDK 1.8 或更高版本
• Maven 3.6+
• MySQL 5.7+ 或 MySQL 8.0+
• Chrome/Firefox/Edge 浏览器（用于 Selenium）

安装步骤

步骤 1：克隆项目

git clone https://gitee.com/zhbdream/javafx-boot-scaffold.git
cd javafx-boot-scaffold

步骤 2：创建数据库

执行数据库初始化脚本：

mysql -u root -p < src/main/resources/db/schema.sql

或者使用 MySQL 客户端工具（如 Navicat、DBeaver）执行 src/main/resources/db/schema.sql 文件。

步骤 3：配置数据库连接

编辑 src/main/resources/application.yml 文件，修改数据库连接信息：

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/javafx_boot?useUnicode=true&characterEncoding=utf8&useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true
    username: root
    password: your_password  # 修改为你的数据库密码

步骤 4：配置应用参数（可选）

app:
  # 是否启用登录验证（true-需要登录，false-跳过登录直接进入主界面）
  enable-auth: true
  
  # JWT Token 密钥（建议修改为随机字符串）
  jwt-secret: your-secret-key
  
  # Token 过期时间（小时）
  jwt-expiration: 24

步骤 5：编译运行

方式一：使用 Maven 命令

# 编译项目
mvn clean compile

# 运行项目
mvn javafx:run

方式二：使用 IDE

1. 使用 IntelliJ IDEA 或 Eclipse 导入项目
2. 等待 Maven 依赖下载完成
3. 运行 io.javafxboot.Application 类的 main 方法

默认账号

数据库初始化后，默认管理员账号：

• 用户名 ：admin
• 密码 ：admin123

⚠️ 安全提示：生产环境请务必修改默认密码！

📁 项目结构

javafx-boot-scaffold/
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── io/javafxboot/
│   │   │       ├── annotation/          # 自定义注解（@Log）
│   │   │       ├── aspect/              # AOP 切面（日志拦截）
│   │   │       ├── config/              # 配置类（数据库、Selenium等）
│   │   │       ├── ctrl/                # 控制器（LoginCtrl、MainCtrl）
│   │   │       ├── entity/              # 实体类（User、Role、Permission等）
│   │   │       ├── exception/           # 异常类（BusinessException等）
│   │   │       ├── mapper/               # MyBatis Mapper
│   │   │       ├── service/             # 服务层（业务逻辑）
│   │   │       ├── util/                # 工具类
│   │   │       │   └── selenium/        # Selenium 工具类
│   │   │       └── view/                # 视图类（LoginView、MainView）
│   │   └── resources/
│   │       ├── application.yml          # 应用配置文件
│   │       ├── db/                      # 数据库初始化脚本
│   │       ├── fxml/                    # FXML 界面文件
│   │       ├── css/                     # CSS 样式文件
│   │       └── icon/                    # 应用图标
│   └── test/                            # 测试代码
├── pom.xml                              # Maven 配置文件
└── README.md                            # 项目说明文档

💡 使用示例

示例 1：使用 Selenium 自动化操作

@Autowired
private SeleniumService seleniumService;

public void testSelenium() {
    // 打开网页
    seleniumService.navigateTo("https://www.baidu.com");
    
    // 查找搜索框并输入关键词
    seleniumService.sendKeys(By.id("kw"), "JavaFX");
    
    // 点击搜索按钮
    seleniumService.click(By.id("su"));
    
    // 等待页面加载
    seleniumService.waitForElementVisible(By.className("result"), 10);
    
    // 截图保存
    seleniumService.takeScreenshot("baidu_search.png");
}

示例 2：使用工具类处理数据

// 日期时间处理
LocalDateTime now = LocalDateTime.now();
String formatted = DateUtil.format(now, "yyyy年MM月dd日 HH:mm:ss");
LocalDateTime tomorrow = DateUtil.addDays(now, 1);

// JSON 序列化
User user = new User();
user.setUsername("test");
user.setPassword("123456");
String json = JsonUtil.toJson(user);

// Excel 读取
List<Map<String, Object>> data = ExcelUtil.readExcel("用户数据.xlsx");
for (Map<String, Object> row : data) {
    System.out.println("姓名：" + row.get("name"));
    System.out.println("年龄：" + row.get("age"));
}

// HTTP 请求
String response = HttpUtil.get("https://api.example.com/users");
Map<String, Object> result = JsonUtil.parseObject(response, Map.class);

示例 3：添加操作日志

@Service
public class UserService {
    
    @Log(module = "用户管理", operateType = "INSERT", saveRequestParam = true)
    public void createUser(User user) {
        // 创建用户的业务逻辑
        // 操作日志会自动记录：操作模块、操作类型、请求参数等
    }
    
    @Log(module = "用户管理", operateType = "UPDATE", saveRequestParam = true)
    public void updateUser(User user) {
        // 更新用户的业务逻辑
    }
    
    @Log(module = "用户管理", operateType = "DELETE", saveRequestParam = false)
    public void deleteUser(Long userId) {
        // 删除用户的业务逻辑
    }
}

示例 4：异常处理

@Service
public class LoginService {
    
    public User login(String username, String password) {
        // 参数验证
        if (StringUtil.isBlank(username) || StringUtil.isBlank(password)) {
            throw new BusinessException("用户名或密码不能为空");
        }
        
        // 查询用户
        User user = userMapper.selectByUsername(username);
        if (user == null) {
            throw new BusinessException("用户名或密码错误");
        }
        
        // 验证密码
        if (!SecurityUtil.matches(password, user.getPassword())) {
            throw new BusinessException("用户名或密码错误");
        }
        
        // 检查用户状态
        if (user.getStatus() != 1) {
            throw new BusinessException("用户已被禁用");
        }
        
        return user;
    }
}

⚙️ 配置说明

数据库配置

spring:
  datasource:
    type: com.alibaba.druid.pool.DruidDataSource
    driver-class-name: com.mysql.cj.jdbc.Driver
    url: jdbc:mysql://localhost:3306/javafx_boot
    username: root
    password: root
    druid:
      initial-size: 5        # 初始连接数
      min-idle: 5            # 最小空闲连接数
      max-active: 20         # 最大活跃连接数

Selenium 配置

selenium:
  browser-type: chrome          # 浏览器类型: chrome, firefox, edge
  headless: false               # 是否无头模式（后台运行）
  implicit-wait: 10             # 隐式等待时间（秒）
  page-load-timeout: 30         # 页面加载超时时间（秒）
  driver-path:                  # 驱动路径（留空则自动下载）
  window-size: 1920,1080        # 窗口大小

登录验证配置

app:
  enable-auth: true             # 是否启用登录验证
  jwt-secret: your-secret-key   # JWT 密钥（建议修改）
  jwt-expiration: 24            # Token 过期时间（小时）

🔧 开发指南

添加新功能模块

1. 创建实体类 ：在 entity 包下创建实体类，使用 MyBatis Plus 注解
2. 创建 Mapper ：在 mapper 包下创建 Mapper 接口
3. 创建 Service ：在 service 包下创建服务接口和实现类
4. 创建 Controller ：在 ctrl 包下创建控制器
5. 创建 View ：在 view 包下创建视图类
6. 创建 FXML ：在 resources/fxml 下创建 FXML 界面文件

自定义样式

编辑 src/main/resources/css/bootstrap-style.css 文件，可以修改 Bootstrap 风格的样式，或者添加自定义样式。

打包部署

# 打包为 JAR 文件
mvn clean package

# 打包为可执行文件（Windows）
mvn javafx:jfxnative

打包后的可执行文件位于 target/jfx/native/ 目录下。

🎯 适用场景

这个脚手架项目适用于以下场景：

• ✅ 企业内部管理系统开发
• ✅ 数据采集和处理工具
• ✅ 自动化测试工具
• ✅ 桌面客户端应用
• ✅ 学习和研究 JavaFX 开发

🤝 贡献指南

欢迎贡献代码！如果你有任何建议或发现问题，可以通过以下方式参与：

1. 提交 Issue ：在 Gitee Issues 提交问题或建议
2. 提交 Pull Request：Fork 项目后提交代码改进
3. Star 支持：如果项目对你有帮助，欢迎 Star 支持

代码规范

• 遵循 Java 编码规范
• 使用 4 个空格缩进
• 类和方法必须添加 JavaDoc 注释
• 提交前运行 mvn clean compile 确保编译通过

📊 项目优势

相比从零开始开发，使用这个脚手架项目可以：

1. 节省开发时间：无需重复开发基础功能模块
2. 代码质量保证：经过实际项目验证，代码结构清晰
3. 易于扩展：采用标准 MVC 架构，便于添加新功能
4. 文档完善：详细的代码注释和使用文档
5. 持续更新：项目持续维护和更新

📝 总结

JavaFX Boot Scaffold 是一个功能完善、代码规范的 JavaFX 桌面应用脚手架项目。它集成了企业级应用开发中常用的功能模块，包括用户权限管理、Selenium 自动化、操作日志、异常处理等，可以帮助开发者快速搭建 JavaFX 桌面应用。

项目采用 Spring Boot 框架，代码结构清晰，注释完善，适合作为桌面应用开发的基础框架。无论是用于企业内部系统开发，还是作为学习 JavaFX 开发的参考项目，都是一个不错的选择。

---

🔗 相关链接

• 项目地址 ：https://gitee.com/zhbdream/javafx-boot-scaffold
• Issues ：https://gitee.com/zhbdream/javafx-boot-scaffold/issues

---

如果这个项目对你有帮助，欢迎 Star ⭐ 支持！

你的支持是我持续更新和维护项目的动力！

---

📌 标签

JavaFX Spring Boot 桌面应用 脚手架 权限管理 Selenium MyBatis Plus 开源项目