4.3.4.3. 构建 War

buildWarCubaWarBuilding 类型的任务,会构建一个 WAR 包,包含所有的应用程序代码和所有的依赖包。需要在 build.gradle 文件的根目录声明。生成的 WAR 包会在项目的 build/distributions 目录。

可以通过 Studio 里的 Deployment > WAR Settings 界面配置这个任务。

任何 CUBA 应用程序包含至少两个 block:中间件(Middleware)和 web 客户端(Web Client)。所以部署程序最自然的方法就是创建两个单独的 WAR 包:中间件一个,web 客户端一个。这样做的话也可以在用户数量增长的时候方便进行扩展。但是单独的包会重复包含一些两边都依赖的包,因此会增加整个程序的大小。还有就是扩展的部署选择也不常用,反而会使得部署流程更加复杂。CubaWarBuilding 任务可以创建这两种类型的 WAR 包:每个 block 一个包,或者包含两个 block 的包,后面这种情况下,应用程序的那些 block 会在一个 web 应用程序里面被不同的类加载器加载。

给中间件和 web 客户端创建不同的 WAR 包

可以采用这样的 task 配置:

task buildWar(type: CubaWarBuilding) {
    appProperties = ['cuba.automaticDatabaseUpdate': 'true']
    singleWar = false
}

任务参数:

  • appName - web 应用程序的名称,默认值是读取 Modules prefix,比如 app

  • appProperties - 定义应用程序属性键值对。这些属性会以 WAR 包里面的 /WEB-INF/local.app.properties 文件为基础增加。

    appProperties = ['cuba.automaticDatabaseUpdate': 'true'] 会在应用程序第一次启动的时候创建数据库,如果没有现成的数据库,需要设置这个参数。

  • singleWar - 如果要为 blocks 构建单独的 WAR,需要设置这个为 false

  • includeJdbcDriver - 是否包含项目里当前使用的 JDBC 驱动,默认是 false

  • includeContextXml - 是否包含项目里当前使用的 Tomcat 的 context.xml 文件,默认值是 false

  • coreContextXmlPath - 如果 includeContextXml 设置为 true,使用这个参数设置一个配置文件的相对目录用来替换项目 context.xml 文件。

  • hsqlInProcess - 如果设置成 truecontext.xml 里面的数据库 URL 会按照 HSQL in-process 模式修改。

  • coreProject - 用来作为 core 模块(Middleware)的 Gradle 项目。如果没定义,则会使用标准的 core 模块。

  • webProject - 用来作为 web 模块(Web Client)的 Gradle 项目。如果没定义,则会使用标准的 web 模块。

  • portalProject - 用来作为 portal 模块(Web Portal)的 Gradle 项目。如果项目包含了 portal 模块,需要设置这个参数,比如,portalProject = project(':app-portal')

  • coreWebXmlPath, webWebXmlPath, portalWebXmlPath - 用来作为相应模块 web.xml 的文件的相对目录。

    使用自定义 web.xml 文件的例子:

    task buildWar(type: CubaWarBuilding) {
        singleWar = false
        // ...
        coreWebXmlPath = 'modules/core/web/WEB-INF/production-web.xml'
        webWebXmlPath = 'modules/web/web/WEB-INF/production-web.xml'
    }
  • logbackConfigurationFile - 日志配置文件的相对目录。

    示例:

    task buildWar(type: CubaWarBuilding) {
        // ...
        logbackConfigurationFile = 'etc/war-logback.xml'
    }
  • useDefaultLogbackConfiguration - 当设置成 true (也是默认值)的时候,这个任务会拷贝标准的 logback.xml 配置文件。

  • frontBuildDir - Front UI 构建生成的目录名称。默认是 build。如需自定义,可以修改这个参数。

创建单一的 WAR 包

需要创建包含中间件和 web 客户端 block 的单一 WAR 包,可以用下面这个配置:

task buildWar(type: CubaWarBuilding) {
    webXmlPath = 'modules/web/web/WEB-INF/single-war-web.xml'
}

除了上面这些参数之外,以下这些参数也可以使用:

  • singleWar - 不设置或者设置成 true

  • webXmlPath - 用来作为单一 WAR 包 web.xml 的文件相对目录。这个文件定义了两个 servlet 上下文的监听器,用来加载程序 block:SingleAppCoreServletListenerSingleAppWebServletListener。通过上下文参数给这两个监听器传递所需要的所有参数。

    single-war-web.xml 示例:

    <?xml version="1.0" encoding="UTF-8"?>
    <web-app xmlns="http://java.sun.com/xml/ns/javaee"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
             version="3.0">
    
        <!--Application components-->
        <context-param>
            <param-name>appComponents</param-name>
            <param-value>com.haulmont.cuba</param-value>
        </context-param>
    
        <!-- Web Client parameters -->
    
        <context-param>
            <description>List of app properties files for Web Client</description>
            <param-name>appPropertiesConfigWeb</param-name>
            <param-value>
                classpath:com/company/sample/web-app.properties
                /WEB-INF/local.app.properties
                file:${app.home}/local.app.properties
            </param-value>
        </context-param>
    
        <context-param>
            <description>Web resources version for correct caching in browser</description>
            <param-name>webResourcesTs</param-name>
            <param-value>${webResourcesTs}</param-value>
        </context-param>
    
        <!-- Middleware parameters -->
    
        <context-param>
            <description>List of app properties files for Middleware</description>
            <param-name>appPropertiesConfigCore</param-name>
            <param-value>
                classpath:com/company/sample/app.properties
                /WEB-INF/local.app.properties
                file:${app.home}/local.app.properties
            </param-value>
        </context-param>
    
        <!-- Servlet context listeners that load the application blocks -->
    
        <listener>
            <listener-class>
                com.vaadin.server.communication.JSR356WebsocketInitializer
            </listener-class>
        </listener>
        <listener>
            <listener-class>
                com.haulmont.cuba.core.sys.singleapp.SingleAppCoreServletListener
            </listener-class>
        </listener>
        <listener>
            <listener-class>
                com.haulmont.cuba.web.sys.singleapp.SingleAppWebServletListener
            </listener-class>
        </listener>
    </web-app>

单个 WAR 包部署时所有的 sevlets 和 filters 需要通过编程的方式注册,参考Servlet 和过滤器的注册

单一 WAR 包只包含 coreweb 客户端 模块。如果需要部署 portal 模块,需要用另外的 WAR 包。

如果项目包含 front 模块,则可以通过 /<appName>/front 路径访问。为了让 frontend 界面在单一 WAR 也能正常工作,需要在构建时修改 PUBLIC_URL= /app/front/ 的值。(比如,在 .env.production.local 内修改 (see README))。

参考 部署 WAR 至 Jetty 章节详细介绍 WAR 部署的各种情况和步骤。