如何迁移JSF-2.2.12/PrimeFaces-13.0.10+Spring5应用至JSF3+SpringBoot3并适配Atlantis布局

一、快速搭建整合项目基础 #

按以下步骤构建可直接使用的项目骨架：

• 初始化Spring Boot 3项目：通过Spring Initializr选择Spring Web依赖，后续手动添加JoinFaces和PrimeFaces相关依赖。
• 配置Maven依赖（适配Spring Boot 3 + JSF 3）：

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>org.joinfaces</groupId>
        <artifactId>jsf-spring-boot-starter</artifactId>
        <version>4.1.1</version> <!-- 与Spring Boot 3.x兼容 -->
    </dependency>
    <dependency>
        <groupId>org.primefaces</groupId>
        <artifactId>primefaces</artifactId>
        <version>13.0.10</version> <!-- 与原项目版本一致，降低适配成本 -->
        <classifier>jakarta</classifier> <!-- JSF 3使用Jakarta命名空间 -->
    </dependency>
    <dependency>
        <groupId>org.primefaces.themes</groupId>
        <artifactId>atlantis</artifactId>
        <version>1.0.10</version> <!-- 匹配PrimeFaces 13的Atlantis版本 -->
    </dependency>
</dependencies>

• 配置application.properties：

# JSF基础配置
jsf.project-stage=Development
# PrimeFaces主题与功能配置
primefaces.THEME=atlantis
primefaces.CLIENT_SIDE_VALIDATION=true
primefaces.FONT_AWESOME=true

• 创建通用布局模板（src/main/resources/templates/layout.xhtml）：

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml"
      xmlns:h="jakarta.faces.html"
      xmlns:p="http://primefaces.org/ui"
      xmlns:ui="jakarta.faces.facelets">
<h:head>
    <title>Atlantis Layout</title>
    <h:outputStylesheet library="primefaces-atlantis" name="theme.css"/>
</h:head>
<h:body>
    <p:layout fullPage="true">
        <p:layoutUnit position="north" size="70">
            <ui:insert name="header">默认头部</ui:insert>
        </p:layoutUnit>
        <p:layoutUnit position="west" size="250" collapsible="true">
            <ui:insert name="sidebar">默认侧边栏</ui:insert>
        </p:layoutUnit>
        <p:layoutUnit position="center">
            <ui:insert name="content">默认内容</ui:insert>
        </p:layoutUnit>
        <p:layoutUnit position="south" size="50">
            <ui:insert name="footer">默认底部</ui:insert>
        </p:layoutUnit>
    </p:layout>
</h:body>
</html>

• 创建测试页面（src/main/resources/index.xhtml）：

<ui:composition template="/templates/layout.xhtml"
                xmlns="http://www.w3.org/1999/xhtml"
                xmlns:ui="jakarta.faces.facelets"
                xmlns:p="http://primefaces.org/ui">
    <ui:define name="header">
        <h1>Atlantis + Spring Boot 3 测试</h1>
    </ui:define>
    <ui:define name="sidebar">
        <p:menu>
            <p:menuitem value="首页" url="/index.xhtml"/>
        </p:menu>
    </ui:define>
    <ui:define name="content">
        <p:panel header="迁移验证">
            <p>项目启动成功，Atlantis布局正常加载</p>
        </p:panel>
    </ui:define>
</ui:composition>

• 启动项目后访问http://localhost:8080/index.xhtml，即可看到生效的Atlantis布局。

二、现有JoinFaces/PrimeFaces项目集成Atlantis布局的修复方案 #

针对你遇到的布局部署问题，按以下步骤逐一解决：

• 替换命名空间：将原Atlantis布局页面中所有javax.faces.*命名空间替换为jakarta.faces.*，例如xmlns:h="jakarta.faces.html"、xmlns:ui="jakarta.faces.facelets"。
• 引入Atlantis主题依赖：在项目依赖中添加匹配PrimeFaces版本的Atlantis主题包（参考上面的Maven依赖配置）。
• 配置主题参数：在application.properties中设置primefaces.THEME=atlantis，确保PrimeFaces加载Atlantis主题。
• 修复资源路径：将自定义Atlantis资源（如css、js、图片）放置在src/main/resources/META-INF/resources/primefaces-atlantis/目录下，确保JSF能通过library="primefaces-atlantis"正确引用。
• 排除冲突依赖：若引入JoinFaces后出现javax与jakarta依赖冲突，在jsf-spring-boot-starter依赖中排除旧javax.faces-api：

<dependency>
    <groupId>org.joinfaces</groupId>
    <artifactId>jsf-spring-boot-starter</artifactId>
    <exclusions>
        <exclusion>
            <groupId>javax.faces</groupId>
            <artifactId>javax.faces-api</artifactId>
        </exclusion>
    </exclusions>
</dependency>

• 适配布局组件：检查原布局中使用的PrimeFaces组件（如p:layout）在PrimeFaces 13中的用法变更，若有差异则调整为最新写法；必要时可替换为PrimeFaces提供的Flex布局组件。

内容的提问来源于stack exchange，提问作者Doukya