JavaFX Boot Scaffold

一个基于 JavaFX + Spring Boot 的桌面应用脚手架项目，集成常用功能模块，开箱即用

功能特性 • 快速开始 • 项目结构 • 配置说明 • 使用示例

---

📖 项目简介

JavaFX Boot Scaffold 是一个企业级 JavaFX 桌面应用脚手架项目，基于 Spring Boot 框架构建，集成了用户权限管理、Selenium 自动化测试、操作日志记录、全局异常处理等常用功能模块。项目采用标准的 MVC 架构，代码结构清晰，注释完善，适合作为桌面应用开发的基础框架。

✨ 核心特性

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

🛠️ 技术栈

技术	版本	说明
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. 用户权限管理

• ✅ 用户登录/登出
• ✅ 角色管理
• ✅ 权限管理
• ✅ 用户-角色关联
• ✅ 角色-权限关联
• ✅ 密码加密（BCrypt）
• ✅ Session 管理

2. Selenium 自动化

• ✅ Chrome/Firefox/Edge 浏览器支持
• ✅ 无头模式运行
• ✅ 元素定位与操作
• ✅ 页面等待机制
• ✅ 截图功能
• ✅ Cookie 管理
• ✅ JavaScript 执行
• ✅ 文件下载

3. 操作日志

• ✅ 基于 AOP 的日志拦截
• ✅ 异步日志保存
• ✅ 操作类型分类
• ✅ 请求参数记录
• ✅ 返回结果记录

4. 异常处理

• ✅ 全局异常捕获
• ✅ 业务异常处理
• ✅ 系统异常处理
• ✅ 统一响应格式

5. 工具类库

• ✅ DateUtil：日期时间处理
• ✅ StringUtil：字符串操作
• ✅ FileUtil：文件操作
• ✅ JsonUtil：JSON 处理
• ✅ HttpUtil：HTTP 请求
• ✅ ExcelUtil：Excel 读写
• ✅ ValidationUtil：数据验证
• ✅ CollectionUtil：集合操作
• ✅ RandomUtil：随机数生成
• ✅ ImageUtil：图片处理

🚀 快速开始

环境要求

• 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

或者手动执行 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. 编译运行

# 编译项目
mvn clean compile

# 运行项目
mvn javafx:run

或者使用 IDE（如 IntelliJ IDEA、Eclipse）直接运行 io.javafxboot.Application 类的 main 方法。

默认账号

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

• 用户名：admin
• 密码：admin123

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

📁 项目结构

javafx-boot-scaffold/
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── io/javafxboot/
│   │   │       ├── annotation/          # 自定义注解
│   │   │       ├── aspect/              # AOP 切面
│   │   │       ├── config/              # 配置类
│   │   │       ├── ctrl/                # 控制器
│   │   │       ├── entity/              # 实体类
│   │   │       ├── exception/           # 异常类
│   │   │       ├── mapper/               # MyBatis Mapper
│   │   │       ├── service/             # 服务层
│   │   │       ├── util/                # 工具类
│   │   │       │   └── selenium/        # Selenium 工具类
│   │   │       └── view/                # 视图类
│   │   └── resources/
│   │       ├── application.yml          # 应用配置
│   │       ├── db/                      # 数据库脚本
│   │       ├── fxml/                    # FXML 界面文件
│   │       ├── css/                     # 样式文件
│   │       └── icon/                    # 图标资源
│   └── test/                            # 测试代码
├── pom.xml                              # Maven 配置
└── README.md                            # 项目说明

⚙️ 配置说明

数据库配置

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

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. 使用 Selenium 自动化

@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");

2. 使用工具类

// 日期格式化
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");

3. 操作日志记录

在方法上添加 @Log 注解即可自动记录操作日志：

@Log(module = "用户管理", operateType = "INSERT")
public void createUser(User user) {
    // 业务逻辑
}

4. 异常处理

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

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

🔧 开发指南

添加新功能模块

1. 在 entity 包下创建实体类
2. 在 mapper 包下创建 Mapper 接口
3. 在 service 包下创建服务接口和实现
4. 在 ctrl 包下创建控制器
5. 在 view 包下创建视图类
6. 在 resources/fxml 下创建 FXML 文件

自定义样式

编辑 src/main/resources/css/bootstrap-style.css 文件，修改 Bootstrap 风格的样式。

打包部署

# 打包为 JAR
mvn clean package

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

🤝 贡献指南

欢迎贡献代码！请遵循以下步骤：

1. Fork 本仓库
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 开启 Pull Request

代码规范

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

📄 许可证

本项目采用 MIT 许可证。

👥 作者

• 项目维护者 - MrZhao

🙏 致谢

• Spring Boot - 核心框架
• JavaFX - UI 框架
• MyBatis Plus - ORM 框架
• Selenium - 浏览器自动化
• javafx-support - JavaFX 与 Spring Boot 集成

📞 联系方式

• Issues: Gitee Issues
• 邮箱: mrzhaopro@qq.com

---

如果这个项目对你有帮助，请给个 ⭐ Star 支持一下！

Made with ❤️ by JavaFX Boot Scaffold Team