企业官网建设流程全解析

简介：这份源码实例面向希望将 Spring Boot 与 JavaFX 结合开发桌面应用的 Java 开发者，重点解决两个框架协同启动、依赖注入与生命周期管理的集成难题。资源包共 86 个文件，约 98KB，以 41 个 java 源码、12 个 fxml 界面布局、10 个 xml 与 9 个 yaml 配置为主，另含 properties、css、mvnw 构建脚本及 README 说明，覆盖多模块示例工程结构。目前已有 1412 人学习下载。通过阅读源码，可掌握用 @SpringBootApplication 协调 SpringApplication 与 Application.launch 的启动顺序、借助 spring-javafx-support 将控制器纳入 Spring 容器、以 @Autowired 注入 Bean，以及用 FXMLLoader 加载 FXML 并绑定控制器的完整链路，同时理解 application.yml 中窗口属性配置与依赖版本兼容处理。适合具备一定 Spring 基础、想快速跑通桌面端集成 Demo 并对照调试的中级开发者参考。

1. 把 Spring Boot 塞进 JavaFX：一份能跑起来的桌面端集成源码

很多做 Java 后端的兄弟都动过这个念头：手里一套 Spring Boot 的服务层、数据层代码，能不能直接搬到桌面端复用，而不是重写一遍？答案是可以的，但第一次动手大概率会翻车——Spring 容器和 JavaFX 的生命周期根本不在一个频道上，一个管 Bean 的创建和依赖注入，一个管 Stage 和 Scene 的渲染线程，硬拼在一起就是各种空指针和线程异常。这份 Spring Boot + JavaFX 集成实例源码，解决的正是这个衔接问题：它把 Spring 的 ApplicationContext 和 JavaFX 的 Application 启动流程串成一条线，让 Controller、Service、Repository 这套后端分层在桌面程序里照常工作。适合已经会写 Spring Boot、但没怎么碰过 JavaFX 的后端开发者，也适合想给内部工具套个图形界面、又不想学新框架的运维和测试同学。下面我按自己拆包复现的顺序，把关键节点和踩过的坑讲清楚。

2. 环境准备与工程骨架：从 pom 到启动类怎么搭

2.1 依赖选型：为什么 JavaFX 要单独引，Spring Boot 版本怎么卡

这份源码用的是 Maven 多模块结构，核心就一个模块，但依赖关系值得说清楚。JavaFX 从 JDK 11 开始就不再随 JDK 附带了，所以不管你用哪个版本的 JDK，都得显式引入javafx-controls和javafx-fxml。源码里用的是 OpenJFX 17，和 Spring Boot 3.x 搭配，如果你本地是 JDK 8 或者 JDK 11，Spring Boot 版本要相应降到 2.7.x，否则jakarta和javax的包名差异会让你在编译期就卡住。

常见做法是在pom.xml里把 JavaFX 依赖的 scope 设成compile，不要用provided，因为打包成可执行 jar 的时候需要把 JavaFX 的类一起带上。另外spring-boot-maven-plugin的mainClass要指向 JavaFX 的启动类，而不是 Spring Boot 的SpringApplication入口，这一点后面会细说。

<!-- pom.xml 关键依赖片段 --> <properties> <java.version>17</java.version> <javafx.version>17.0.2</javafx.version> </properties> <dependencies> <!-- Spring Boot 基础 --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter</artifactId> </dependency> <!-- JavaFX 控件与 FXML 支持 --> <dependency> <groupId>org.openjfx</groupId> <artifactId>javafx-controls</artifactId> <version>${javafx.version}</version> </dependency> <dependency> <groupId>org.openjfx</groupId> <artifactId>javafx-fxml</artifactId> <version>${javafx.version}</version> </dependency> </dependencies>

参数说明：javafx.version建议和本地 JDK 大版本对齐，JDK 17 配 OpenJFX 17 最稳；如果要用 JDK 21，OpenJFX 21 也可以，但源码里的 FXML 加载方式在 21 上有细微差异，后面避坑章节会提。spring-boot-starter不带 web 容器，桌面端不需要内嵌 Tomcat，引了反而拖慢启动。

2.2 启动类设计：ApplicationContext 和 Application 谁先谁后

这是整个集成最核心的一步。JavaFX 的Application子类负责start(Stage)方法，Spring Boot 的SpringApplication.run()负责初始化容器。如果直接在main方法里先跑 Spring Boot 再launch()，JavaFX 的线程模型和 Spring 的 Bean 初始化会打架，典型现象是@Autowired的字段在 Controller 里是 null。

源码里的做法是：让 JavaFX 的启动类持有ApplicationContext，在init()方法里启动 Spring 容器，然后在start()方法里从容器中取出主界面 Bean 并显示。init()是 JavaFX 生命周期里在start()之前调用的方法，且运行在 JavaFX-Launcher 线程，这个时机刚好够 Spring 完成 Bean 的扫描和注入。

public class MainApp extends Application { private ApplicationContext context; @Override public void init() { // 在 JavaFX 启动线程中初始化 Spring 容器 context = SpringApplication.run(SpringConfig.class); } @Override public void start(Stage primaryStage) { // 从容器中获取主界面控制器，而不是 new 出来 MainController mainController = context.getBean(MainController.class); Scene scene = new Scene(mainController.getRoot(), 800, 600); primaryStage.setTitle("集成示例"); primaryStage.setScene(scene); primaryStage.show(); } public static void main(String[] args) { launch(args); // 注意：这里不要调 SpringApplication.run } }

逻辑说明：launch(args)会触发 JavaFX 的完整生命周期，init()先跑，Spring 容器在这里起来；start()后跑，此时容器已经就绪，getBean能拿到完整注入的 Controller。参数上，SpringConfig是一个带@Configuration和@ComponentScan的配置类，扫描范围要覆盖你的 Controller 和 Service 包。如果getBean抛NoSuchBeanDefinitionException，八成是扫描路径没配对。

3. Controller 与 FXML 绑定：让 @Autowired 在桌面端生效

3.1 FXML 加载器改造：为什么 fx:controller 不能直接写类名

JavaFX 原生的FXMLLoader在解析 FXML 时，如果遇到fx:controller属性，会直接通过反射new一个 Controller 实例。这个实例不归 Spring 管，里面的@Autowired字段全是 null。源码里对这一步做了改造：设置FXMLLoader的controllerFactory，让它从 Spring 容器里取 Bean。

// 在 MainController 或专门的 ViewLoader 中 FXMLLoader loader = new FXMLLoader(getClass().getResource("/fxml/main.fxml")); loader.setControllerFactory(context::getBean); // 关键：Controller 由 Spring 创建 Parent root = loader.load();

逻辑说明：setControllerFactory接收一个Callback<Class<?>, Object>，这里直接用context::getBean方法引用，意思是「给我一个 Class，我还你一个容器里的 Bean」。这样 FXML 里写的fx:controller="com.example.demo.controller.MainController"就会走 Spring 的 Bean 创建流程，依赖注入正常生效。参数上要注意，Controller 类必须加@Component或@Controller注解，否则容器里没有这个 Bean，getBean会直接抛异常。

3.2 Service 层复用：后端代码原样搬过来的边界在哪

这份源码的一个卖点是 Service 和 Repository 层几乎不用改。我实测把原来 Spring Boot Web 项目里的@Service和@Repository类直接复制过来，只要不依赖HttpServletRequest、SecurityContext这类 Web 专属对象，都能正常注入和使用。数据库访问用 Spring Data JPA 或者 MyBatis 都行，源码里给的是 JPA 版本，application.yml里配好数据源就能跑。

但有一个边界要注意：事务管理。桌面端没有 Web 请求线程，@Transactional默认的传播行为在 JavaFX 的应用线程里依然有效，但如果你在Platform.runLater()里调用事务方法，事务边界会跟着 runLater 的 Runnable 走，和你在后台线程里调用的行为不一致。常见做法是把事务方法放在 Service 层，由 Controller 在 JavaFX 线程里直接调用，不要跨线程传递事务上下文。

@Service public class UserService { @Autowired private UserRepository userRepository; @Transactional public void saveUser(String name) { User user = new User(); user.setName(name); userRepository.save(user); } }

参数说明：@Transactional加在 public 方法上，Spring 的代理才能生效；如果 Service 类实现了接口，JDK 动态代理默认走接口方法，没实现接口则走 CGLIB。桌面端一般不需要配多数据源，单数据源直接自动配置即可。

4. 避坑与排查：集成时最容易翻车的五个点

4.1 现象：启动后界面空白，控制台无报错

原因：start()方法里primaryStage.show()之前，Scene 的 root 为 null，或者 FXML 加载失败但异常被吞了。JavaFX 的FXMLLoader.load()抛的是IOException，如果没 try-catch 打印，容易被忽略。

解决：在load()外面包一层 try-catch，把e.printStackTrace()打出来；同时检查 FXML 文件路径是否以/开头，getResource对相对路径和绝对路径的处理不一样。

4.2 现象：@Autowired 字段为 null，但 Controller 明明加了 @Component

原因：FXML 的fx:controller触发了 JavaFX 默认的反射创建，没走setControllerFactory。或者setControllerFactory设置在了load()之后。

解决：确认setControllerFactory在loader.load()之前调用；确认 Controller 类在 Spring 的扫描包路径下；如果用了@Scope("prototype")，每次getBean会创建新实例，FXML 加载和后续事件处理可能拿到不同对象，桌面端建议用默认单例。

4.3 现象：在 Controller 里直接 new 一个 Service，编译通过但运行报错

原因：手动 new 出来的 Service 不受 Spring 管理，里面的 Repository 注入不进去，调用时抛NullPointerException。

解决：所有需要依赖注入的类都从容器拿，Controller 里不要出现new XxxService()。如果确实需要动态创建，用context.getBean(XxxService.class)。

4.4 现象：打包成 jar 后双击运行，提示「JavaFX runtime components are missing」

原因：JavaFX 11 之后模块化机制变了，直接用java -jar启动时，JavaFX 的模块路径没配好。

解决：源码里给了一个launcher类，这个类不继承Application，它的main方法里调用MainApp.main(args)。这样打包时spring-boot-maven-plugin的mainClass指向 launcher，JavaFX 的模块检查就能绕过。这是社区里比较通用的做法，不是源码作者独创，但很有效。

public class Launcher { public static void main(String[] args) { MainApp.main(args); // 间接调用，绕过 JavaFX 模块检查 } }

4.5 现象：界面卡死，按钮点不动

原因：在 JavaFX 应用线程（FX Application Thread）里执行了耗时操作，比如数据库查询、文件读写。JavaFX 的 UI 渲染和事件处理都在这个线程，阻塞它就等于卡死界面。

解决：耗时操作放到Task或Service（JavaFX 自带的javafx.concurrent.Service）里，用Platform.runLater()回传结果更新 UI。注意不要和 Spring 的@Service搞混，两者同名但完全不是一个东西。源码里给了一个BackgroundTask的封装示例，把 Spring 的 Service 调用包在 JavaFX 的 Task 里，算是一个折中方案。

5. 进阶技巧：把这份源码改成你自己的内部工具

5.1 用 Spring Boot 的配置文件管理桌面端参数

桌面端经常需要连不同的数据库或者切环境，源码里把application.yml放在resources下，Spring Boot 会自动加载。你可以通过--spring.profiles.active=dev这样的启动参数来切换配置，和 Web 项目一模一样。如果想让用户自己选配置文件，可以在 JavaFX 启动前弹一个文件选择框，把路径塞进System.setProperty("spring.config.location", path)，再调SpringApplication.run。

5.2 把 FXML 和 CSS 做成可替换的资源包

源码里的界面布局全在 FXML 里，样式在 CSS 里。如果你想给不同客户换皮肤，不需要改 Java 代码，只要替换resources/fxml和resources/css下的文件即可。我一般会在application.yml里加一个app.theme配置项，启动时根据这个值加载不同的 CSS 文件，这样打包一次就能出多个版本。

5.3 验证集成是否成功的三个检查点

第一，启动后看控制台有没有 Spring Boot 的 Banner 和 Tomcat 相关日志（不应该有 Tomcat，有的话说明引了 web starter）。第二，在 Controller 的initialize()方法里打一行日志，确认@Autowired的 Service 不为 null。第三，点一个触发数据库查询的按钮，看数据能不能正常返回并渲染到 TableView 上。这三个点过了，集成基本就没问题。

从那以后我每次把 Spring Boot 往桌面端搬，都会先把setControllerFactory和Launcher这两个点确认一遍，再动手写业务代码，省得回头排查那些玄学空指针。希望帮到你。

本文还有配套的精品资源，点击获取