從 2.2.x 遷移至 3.0.x
本指南提供有關如何將您的 Ktor 應用程式從 2.2.x 版本遷移至 3.0.x 的說明。
Ktor Server
ApplicationEngine、ApplicationEnvironment 與 Application
我們引入了多項設計變更,以改進可設定性,並在 ApplicationEngine、ApplicationEnvironment 與 Application 執行個體之間提供更明確的分隔。
在 v3.0.0 之前,ApplicationEngine 管理 ApplicationEnvironment,而後者又負責管理 Application。
然而在目前的設計中,Application 負責建立、擁有並初始化 ApplicationEngine 與 ApplicationEnvironment。
此結構重整帶來了以下一系列的重大變更 (breaking changes):
ApplicationEngineEnvironmentBuilder與applicationEngineEnvironment類別已重新命名。start()與stop()方法已從ApplicationEngineEnvironment中移除。commandLineEnvironment()已移除。- 引入
ServerConfigBuilder。 embeddedServer()傳回EmbeddedServer而非ApplicationEngine。
這些變更將影響依賴於先前模型的現有程式碼。
重新命名的類別
| 套件 | 2.x.x | 3.0.x |
|---|---|---|
io.ktor:ktor-server-core | ApplicationEngineEnvironmentBuilder | ApplicationEnvironmentBuilder |
io.ktor:ktor-server-core | applicationEngineEnvironment | applicationEnvironment |
start() 與 stop() 方法已從 ApplicationEngineEnvironment 中移除
隨著 ApplicationEngineEnvironment 合併至 ApplicationEnvironment,start() 與 stop() 方法現在只能透過 ApplicationEngine 存取。
| 2.x.x | 3.0.x |
|---|---|
ApplicationEngineEnvironment.start() | ApplicationEngine.start() |
ApplicationEngineEnvironment.stop() | ApplicationEngine.stop() |
此外,在下表中您可以看到已移除的屬性清單及其目前對應的擁有權:
| 2.x.x | 3.0.x |
|---|---|
ApplicationEngineEnvironment.connectors | ApplicationEngine.Configuration.connectors |
ApplicationEnvironment.developmentMode | Application.developmentMode |
ApplicationEnvironment.monitor | Application.monitor |
ApplicationEnvironment.parentCoroutineContext | Application.parentCoroutineContext |
ApplicationEnvironment.rootPath | Application.rootPath |
擁有權的變更可透過以下範例說明:
import io.ktor.server.application.*
import io.ktor.server.cio.*
import io.ktor.server.engine.*
import org.slf4j.helpers.NOPLogger
fun defaultServer(module: Application.() -> Unit) =
embeddedServer(CIO,
environment = applicationEngineEnvironment {
log = NOPLogger.NOP_LOGGER
connector {
port = 8080
}
module(module)
}
)import io.ktor.server.application.*
import io.ktor.server.cio.*
import io.ktor.server.engine.*
import org.slf4j.helpers.NOPLogger
fun defaultServer(module: Application.() -> Unit) =
embeddedServer(CIO,
environment = applicationEnvironment { log = NOPLogger.NOP_LOGGER },
configure = {
connector {
port = 8080
}
},
module
)commandLineEnvironment() 已移除
用於從命令列引數建立 ApplicationEngineEnvironment 執行個體的 commandLineEnvironment() 函式已在 Ktor 3.0.0 中移除。取而代之的是,您可以使用 CommandLineConfig 函式將命令列引數剖析為組態物件。
若要將您的應用程式從 commandLineEnvironment 遷移至 CommandLineConfig,請將 commandLineEnvironment() 替換為如下所示的 configure 區塊。
fun main(args: Array<String>) {
embeddedServer(Netty, commandLineEnvironment(args) {
connector { port = 8080 }
module {
routing {
get("/") {
call.respondText("Hello, world!")
}
}
}
}) {
requestReadTimeoutSeconds = 5
responseWriteTimeoutSeconds = 5
}.start(wait = true)
}fun main(args: Array<String>) {
embeddedServer(
factory = Netty,
configure = {
val cliConfig = CommandLineConfig(args)
takeFrom(cliConfig.engineConfig)
loadCommonConfiguration(cliConfig.rootConfig.environment.config)
}
) {
routing {
get("/") {
call.respondText("Hello, world!")
}
}
}.start(wait = true)
}如需更多關於使用 embeddedServer 進行命令列組態的資訊,請參閱程式碼中的組態主題。
引入 ServerConfigBuilder
我們引入了一個新的實體 ServerConfigBuilder 用於設定伺服器屬性,並取代了先前的 ApplicationPropertiesBuilder 組態機制。 ServerConfigBuilder 用於建置 ServerConfig 類別的執行個體,該類別現在持有先前由 ApplicationProperties 管理的模組、路徑與環境詳細資訊。
下表總結了關鍵變更:
| 套件 | 2.x.x | 3.0.x |
|---|---|---|
io.ktor:ktor-server-core | ApplicationProperties | ServerConfig |
io.ktor:ktor-server-core | ApplicationPropertiesBuilder | ServerConfigBuilder |
此外,在 embeddedServer() 函式中,applicationProperties 屬性已重新命名為 rootConfig,以反映此新組態方法。
使用 embeddedServer() 時,請將 applicationProperties 屬性替換為 rootConfig。 以下是使用 serverConfig 區塊將伺服器的 developmentMode 明確設定為 true 的範例:
fun main(args: Array<String>) {
embeddedServer(Netty,
serverConfig {
developmentMode = true
module(Application::module)
},
configure = {
connector { port = 12345 }
}
).start(wait = true)
}引入 EmbeddedServer
引入了 EmbeddedServer 類別,並用來取代 ApplicationEngine 作為 embeddedServer() 函式的傳回型別。
如需更多關於模型變更的詳細資訊,請參閱 YouTrack 上的問題 KTOR-3857。
測試
withTestApplication 與 withApplication 已移除
withTestApplication 與 withApplication 函式(先前已在 2.0.0 版本中棄用)現在已從 ktor-server-test-host 套件中移除。
取而代之的是,請使用 testApplication 函式搭配現有的 Ktor 用戶端執行個體,對您的伺服器發出請求並驗證結果。
在下方的測試中,handleRequest 函式被替換為 client.get 請求:
@Test
fun testRootLegacyApi() {
withTestApplication(Application::module) {
handleRequest(HttpMethod.Get, "/").apply {
assertEquals(HttpStatusCode.OK, response.status())
assertEquals("Hello, world!", response.content)
}
}
}@Test
fun testRoot() = testApplication {
val response = client.get("/")
assertEquals(HttpStatusCode.OK, response.status)
assertEquals("Hello, world!", response.bodyAsText())
}如需更多資訊,請參閱 Ktor Server 中的測試。
TestApplication 模組載入
TestApplication 不再自動從組態檔案(例如 application.conf)載入模組。取而代之的是,您必須在 testApplication 函式中明確載入模組,或手動載入組態檔案。
明確模組載入
若要明確載入模組,請在 testApplication 中使用 application 函式。此方法允許您手動指定要載入哪些模組,從而更好地控制您的測試設定。
import io.ktor.client.request.*
import io.ktor.client.statement.*
import io.ktor.http.*
import io.ktor.server.testing.*
import kotlin.test.*
class ApplicationTest {
@Test
fun testRoot() = testApplication {
client.get("/").apply {
assertEquals(HttpStatusCode.OK, status)
assertEquals("Hello World!", bodyAsText())
}
}
}import com.example.plugins.*
import io.ktor.client.request.*
import io.ktor.client.statement.*
import io.ktor.http.*
import io.ktor.server.testing.*
import kotlin.test.*
class ApplicationTest {
@Test
fun testRoot() = testApplication {
application {
configureRouting()
}
client.get("/").apply {
assertEquals(HttpStatusCode.OK, status)
assertEquals("Hello World!", bodyAsText())
}
}
}從組態檔案載入模組
如果您想從組態檔案載入模組,請使用 environment 函式為您的測試指定組態檔案。
@Test
fun testHello() = testApplication {
environment {
config = ApplicationConfig(
"application-custom.conf"
)
}
}如需更多關於設定測試應用程式的資訊,請參閱 Ktor Server 中的測試 章節。
CallLogging 外掛程式套件已重新命名
由於拼字錯誤,CallLogging 外掛程式套件已重新命名。
| 2.x.x | 3.0.x |
|---|---|
io.ktor.server.plugins.callloging | io.ktor.server.plugins.calllogging |
ktor-server-host-common 模組已移除
由於 Application 需要了解 ApplicationEngine,ktor-server-host-common 模組的內容已併入 ktor-server-core,即 io.ktor.server.engine 套件。
請確保您的相依性已相應更新。在大多數情況下,您只需移除 ktor-server-host-common 相依性即可。
Locations 外掛程式已移除
Ktor 伺服器的 Locations 外掛程式已移除。若要建立型別安全的路由,請改用 Resources 外掛程式。這需要以下變更:
將
io.ktor:ktor-server-locations構件替換為io.ktor:ktor-server-resources。Resources外掛程式相依於 Kotlin 序列化外掛程式。若要新增序列化外掛程式,請參閱 kotlinx.serialization 設定。將外掛程式匯入從
io.ktor.server.locations.*更新為io.ktor.server.resources.*。此外,從
io.ktor.resources匯入Resource模組。
以下範例顯示如何實作這些變更:
import io.ktor.server.locations.*
@Location("/articles")
class article(val value: Int)
fun Application.module() {
install(Locations)
routing {
get<article> {
// Get all articles ...
call.respondText("List of articles")
}
}
}import io.ktor.resources.Resource
import io.ktor.server.resources.*
@Resource("/articles")
class Articles(val value: Int)
fun Application.module() {
install(Resources)
routing {
get<Articles> {
// Get all articles ...
call.respondText("List of articles")
}
}
}如需更多關於使用 Resources 的資訊,請參閱型別安全路由。
WebSockets 組態中 java.time 的替換
WebSockets 外掛程式組態已更新,改用 Kotlin 的 Duration 來設定 pingPeriod 與 timeout 屬性。這取代了先前使用的 java.time.Duration,以提供更符合 Kotlin 習慣的體驗。
若要將現有程式碼遷移至新格式,請使用 kotlin.time.Duration 類別的擴充函式與屬性來建構時間長度。在以下範例中,Duration.ofSeconds() 被替換為 Kotlin 的 seconds 擴充屬性:
import java.time.Duration
install(WebSockets) {
pingPeriod = Duration.ofSeconds(15)
timeout = Duration.ofSeconds(15)
//..
}import kotlin.time.Duration.Companion.seconds
install(WebSockets) {
pingPeriod = 15.seconds
timeout = 15.seconds
//..
}您可以根據需要對其他時間長度組態使用類似的 Kotlin 時間擴充屬性(minutes、hours 等)。如需更多資訊,請參閱 Duration 文件。
伺服器通訊端 .bind() 現在為掛起函式
為了支援 JS 與 WasmJS 環境中的非同步操作,TCPSocketBuilder 與 UDPSocketBuilder 中伺服器通訊端的 .bind() 函式已更新為掛起函式。這意味著現在必須在協同程式內呼叫 .bind()。
若要遷移,請確保僅在協同程式或掛起函式中呼叫 .bind()。以下是使用 runBlocking 的範例:
runBlocking {
val selectorManager = SelectorManager(Dispatchers.IO)
val serverSocket = aSocket(selectorManager).tcp().bind("127.0.0.1", 9002)
//...
}如需更多關於使用通訊端的資訊,請參閱 Sockets 文件。
多部分表單資料 (Multipart form data)
二進位與檔案項目的新預設限制
在 Ktor 3.0.0 中,使用 ApplicationCall.receiveMultipart() 接收二進位與檔案項目時引入了 50 MB 的預設限制。如果接收到的檔案或二進位項目超過 50 MB 的限制,則會擲回 IOException。
覆寫預設限制
如果您的應用程式先前依賴於處理大於 50 MB 的檔案且未進行明確組態,您將需要更新程式碼以避免非預期的行為。
若要覆寫預設限制,請在呼叫 .receiveMultipart() 時傳遞 formFieldLimit 參數:
val multipartData = call.receiveMultipart(formFieldLimit = 1024 * 1024 * 100)PartData.FileItem.streamProvider() 已棄用
在先前的 Ktor 版本中,PartData.FileItem 中的 .streamProvider() 函式用於將檔案項目的內容作為 InputStream 存取。從 Ktor 3.0.0 開始,此函式已棄用。
若要遷移您的應用程式,請將 .streamProvider() 替換為 .provider() 函式。.provider() 函式會傳回一個 ByteReadChannel,這是一個對協同程式友善、非阻塞的抽象,用於增量讀取位元組串流。 接著您可以使用 ByteReadChannel 提供的 .copyTo() 或 .copyAndClose() 方法,將資料直接從通道串流傳輸至檔案輸出。
在此範例中,.copyAndClose() 方法將資料從 ByteReadChannel 傳輸至檔案的 WritableByteChannel。
fun Application.main() {
routing {
post("/upload") {
val multipart = call.receiveMultipart()
multipart.forEachPart { partData ->
if (partData is PartData.FileItem) {
var fileName = partData.originalFileName as String
val file = File("uploads/$fileName")
file.writeBytes(partData.streamProvider().readBytes())
}
// ...
}
}
}
}fun Application.main() {
routing {
post("/upload") {
val multipart = call.receiveMultipart()
multipart.forEachPart { partData ->
if (partData is PartData.FileItem) {
var fileName = partData.originalFileName as String
val file = File("uploads/$fileName")
partData.provider().copyAndClose(file.writeChannel())
}
// ...
}
}
}
}如需完整範例以及更多關於處理多部分表單資料的資訊,請參閱多部分表單資料的請求處理。
工作階段加密方法更新
Sessions 外掛程式提供的加密方法已更新以增強安全性。
具體而言,SessionTransportTransformerEncrypt 方法先前是從解密後的工作階段值衍生 MAC,現在則是從加密後的值計算。
為確保與現有工作階段的相容性,Ktor 引入了 backwardCompatibleRead 屬性。對於目前的組態,請在 SessionTransportTransformerEncrypt 的建構函式中包含此屬性:
install(Sessions) {
cookie<UserSession>("user_session") {
// ...
transform(
SessionTransportTransformerEncrypt(
secretEncryptKey, // 此處填寫您的加密金鑰
secretSignKey, // 此處填寫您的簽署金鑰
backwardCompatibleRead = true
)
)
}
}如需更多關於 Ktor 中工作階段加密的資訊,請參閱簽署並加密工作階段資料。
Ktor Client
HttpResponse 的 content 屬性重新命名
在 Ktor 3.0.0 之前,HttpResponse 的 content 屬性提供了一個原始的 ByteReadChannel,用於讀取來自網路的回應內容。從 Ktor 3.0.0 開始,content 屬性已重新命名為 rawContent,以更精確地反映其用途。
SocketTimeoutException 現在是一個型別別名
來自 io.ktor.client.network.sockets 套件的 SocketTimeoutException 已從 Kotlin 類別轉換為 Java 類別的別名。此變更在某些情況下可能會導致 NoClassDefFoundError,並可能需要更新現有程式碼。
若要遷移您的應用程式,請確保您的程式碼未引用舊類別,並且使用最新的 Ktor 版本進行編譯。以下是更新例外檢查的方法:
if (exception is io.ktor.client.network.sockets.SocketTimeoutException) { ... }if (exception is java.net.SocketTimeoutException) { ... }共用模組 (Shared modules)
遷移至 kotlinx-io
隨著 3.0.0 版本的發布,Ktor 已轉向使用 kotlinx-io 程式庫,該程式庫在 Kotlin 各個程式庫之間提供了標準化且高效的 I/O API。此變更提高了效能、減少了記憶體分配,並簡化了 I/O 處理。如果您的專案與 Ktor 的底層 I/O API 互動,您可能需要更新程式碼以確保相容性。
這影響了許多類別,例如 ByteReadChannel 與 ByteWriteChannel。此外,以下 Ktor 類別現在由 kotlinx-io 支援,其先前的實作已被棄用:
| Ktor 2.x | Ktor 3.x |
|---|---|
io.ktor.utils.io.core.Buffer | kotlinx.io.Buffer |
io.ktor.utils.io.core.BytePacketBuilder | kotlinx.io.Sink |
io.ktor.utils.io.core.ByteReadPacket | kotlinx.io.Source |
io.ktor.utils.io.core.Input | kotlinx.io.Source |
io.ktor.utils.io.core.Output | kotlinx.io.Sink |
io.ktor.utils.io.core.Sink | kotlinx.io.Buffer |
io.ktor.utils.io.errors.EOFException | kotlinx.io.EOFException |
io.ktor.utils.io.errors.IOException | kotlinx.io.IOException |
棄用的 API 將被支援至 Ktor 4.0,但我們建議您儘早進行遷移。若要遷移您的應用程式,請更新您的程式碼以使用來自 kotlinx-io 的對應方法。
範例:串流 I/O
如果您正在處理大型檔案下載並需要高效的串流解決方案,您可以將手動位元組陣列處理替換為 kotlinx-io 優化的串流 API。
在 Ktor 2.x 中,處理大型檔案下載通常涉及使用 ByteReadChannel.readRemaining() 手動讀取可用位元組,並使用 File.appendBytes() 將其寫入檔案:
val client = HttpClient(CIO)
val file = File.createTempFile("files", "index")
runBlocking {
client.prepareGet("https://ktor.io/").execute { httpResponse ->
val channel: ByteReadChannel = httpResponse.body()
while (!channel.isClosedForRead) {
val packet = channel.readRemaining(DEFAULT_BUFFER_SIZE.toLong())
while (!packet.isEmpty) {
val bytes = packet.readBytes()
file.appendBytes(bytes)
println("Received ${file.length()} bytes from ${httpResponse.contentLength()}")
}
}
println("A file saved to ${file.path}")
}
}這種方法涉及多次記憶體分配與多餘的資料複製。
在 Ktor 3.x 中,ByteReadChannel.readRemaining() 現在會傳回一個 Source,從而可以使用 Source.transferTo() 進行資料串流:
val client = HttpClient(CIO)
val file = File.createTempFile("files", "index")
val stream = file.outputStream().asSink()
val fileSize = 100 * 1024 * 1024
val bufferSize: Long = 1024 * 1024
runBlocking {
client.prepareGet("https://httpbin.org/bytes/$fileSize").execute { httpResponse ->
val channel: ByteReadChannel = httpResponse.body()
var count = 0L
stream.use {
while (!channel.exhausted()) {
val chunk = channel.readRemaining(bufferSize)
count += chunk.remaining
chunk.transferTo(stream)
println("Received $count bytes from ${httpResponse.contentLength()}")
}
}
}
println("A file saved to ${file.path}")
}此方法將資料直接從通道傳輸至檔案的接收器 (sink),從而大幅減少記憶體分配並提高效能。
如需完整範例,請參閱 client-download-streaming。
如需更多關於 API 替換的詳細資訊,請參閱 kotlinx-io 文件。
屬性金鑰現在需要精確的型別比對
在 Ktor 3.0.0 中,AttributeKey 執行個體現在透過識別 (identity) 進行比較,且在儲存與檢索值時需要精確的型別比對。這確保了型別安全性並防止因型別不符而導致的非預期行為。
先前,擷取屬性時使用的泛型型別可能與儲存時不同,例如使用 getOrNull<Any>() 來獲取 AttributeKey<Boolean>。
若要遷移您的應用程式,請確保擷取型別與儲存型別完全相符:
val attrs = Attributes()
attrs.put(AttributeKey<Boolean>("key"), true)
attrs.getOrNull<Boolean>("key")移除空白構件
自 Ktor 1.0.0 以來,空白構件 io.ktor:ktor 曾被誤發布至 Maven。從 Ktor 3.0.0 開始,該構件已被移除。
如果您的專案將此構件作為相依性包含在內,您可以安全地將其移除。
