Skip to content

WAR ​

程式碼範例: jetty-war、 tomcat-war、 tomcat-war-ssl

你可以在 Servlet 容器(例如 Tomcat 或 Jetty)中執行 Ktor 應用程式。為此,你需要將應用程式封裝為 WAR 封存檔,並將其部署到支援 WAR 部署的伺服器或雲端服務上。

在本主題中,你將學習如何:

在 Servlet 應用程式中設定 Ktor ​

Ktor 允許你直接在應用程式中建立並啟動伺服器,使用特定的引擎(例如 Netty、Jetty 或 Tomcat)。在此配置下,你的應用程式控制著引擎設定、連線以及 SSL 設定。

當部署至 Servlet 容器時,容器會控制應用程式生命週期與連線設定。為此,Ktor 提供了 ServletApplicationEngine 引擎,將應用程式的控制權委託給 Servlet 容器。

在 Servlet 容器內執行時,組態檔中定義的 Ktor 連線與 SSL 設定將不會生效。

如需在 Tomcat 中設定 SSL,請參閱 tomcat-war-ssl 範例。

新增相依性 ​

若要在 Servlet 應用程式中使用 Ktor,請將 ktor-server-servlet-jakarta 構件新增至你的建置指令碼中:

kotlin
implementation(ktorLibs.server.servlet)
上述程式碼片段使用 Ktor 版本目錄 來指定 Ktor 相依性。
groovy
implementation ktorLibs.server.servlet
上述程式碼片段使用 Ktor 版本目錄 來指定 Ktor 相依性。
xml
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-server-servlet-jakarta-jvm</artifactId>
    <version>${ktor_version}</version>
</dependency>

當部署至 Servlet 容器時,無需個別新增 Jetty 或 Tomcat 引擎相依性。

設定 Servlet ​

若要在應用程式中註冊 Ktor Servlet,請開啟 WEB-INF/web.xml 檔案並將 servlet-class 屬性指定為 ServletApplicationEngine:

xml
<servlet>
    <display-name>KtorServlet</display-name>
    <servlet-name>KtorServlet</servlet-name>
    <servlet-class>io.ktor.server.servlet.jakarta.ServletApplicationEngine</servlet-class>
    <init-param>
        <param-name>io.ktor.ktor.config</param-name>
        <param-value>application.conf</param-value>
    </init-param>
    <async-supported>true</async-supported>
</servlet>
xml
<servlet>
    <display-name>KtorServlet</display-name>
    <servlet-name>KtorServlet</servlet-name>
    <servlet-class>io.ktor.server.servlet.ServletApplicationEngine</servlet-class>
    <init-param>
        <param-name>io.ktor.ktor.config</param-name>
        <param-value>application.conf</param-value>
    </init-param>
    <async-supported>true</async-supported>
</servlet>

接著,為此 Servlet 設定 URL 模式:

xml
<servlet-mapping>
    <servlet-name>KtorServlet</servlet-name>
    <url-pattern>/</url-pattern>
</servlet-mapping>

設定 Gretty 外掛程式 ​

Gretty 外掛程式允許你在 Jetty 和 Tomcat 上執行 Servlet 應用程式。

首先,開啟 gradle/libs.versions.toml 檔案並定義 Gretty 版本及其外掛程式別名:

toml
[versions]
gretty = "5.0.1"

[plugins]
gretty = { id = "org.gretty", version.ref = "gretty" }

在你的 build.gradle.kts 檔案中,將下列項目新增至 plugins {} 區塊:

groovy
plugins {
    alias(libs.plugins.gretty)
}

接著,你可以在 gretty {} 區塊中設定 Gretty:

groovy
gretty {
    servletContainer = "jetty12"
    contextPath = "/"
}
groovy
gretty {
    servletContainer = "tomcat10"
    contextPath = "/"
}

最後,設定 run 任務:

groovy
afterEvaluate {
    tasks.getByName("run") {
        dependsOn("appRun")
    }
}

設定 War 外掛程式 ​

War 外掛程式允許你產生用於部署至 Servlet 容器的 WAR 封存檔。

若要套用此外掛程式,請開啟你的 build.gradle.kts 檔案,並將下列項目新增至 plugins {} 區塊:

groovy
plugins {
    id("war")
}

執行應用程式 ​

你可以使用 run 任務來執行包含已設定 Gretty 外掛程式的 Servlet 應用程式。例如,若要執行 jetty-war 範例專案,請執行以下指令:

Bash
./gradlew :jetty-war:run

產生並部署 WAR 封存檔 ​

若要使用 War 外掛程式產生 WAR 封存檔,請執行 war 任務。對於 jetty-war 範例專案,指令如下:

Bash
./gradlew :jetty-war:war

任務完成後,jetty-war.war 將產生在對應模組的 build/libs 目錄中。

若要部署產生的封存檔,請將檔案複製到 Servlet 容器中的 jetty/webapps 目錄。

以下 Dockerfile 範例示範如何在 Jetty 或 Tomcat Servlet 容器中執行產生的 WAR 檔案:

Docker
FROM jetty:12.0.29
EXPOSE 8080:8080
COPY ./build/libs/jetty-war.war/ /var/lib/jetty/webapps
WORKDIR /var/lib/jetty
CMD ["java","-jar","/usr/local/jetty/start.jar"]
Docker
FROM tomcat:10.1.50
EXPOSE 8080:8080
COPY ./build/libs/tomcat-war.war/ /usr/local/tomcat/webapps
WORKDIR /usr/local/tomcat
CMD ["catalina.sh", "run"]

如需完整的程式碼範例,請參閱 jetty-war 與 tomcat-war。