Skip to content
Server Plugin

型別安全路由

必要的相依性:io.ktor:ktor-server-resources

程式碼範例: resource-routing

原生伺服器Ktor 支援 Kotlin/Native,可讓您在無需額外執行階段或虛擬機的情況下執行伺服器。 支援:✅

Ktor 提供了 Resources 外掛程式,可讓您實作型別安全路由。為此,您需要建立一個作為具型別路由的類別,並使用 @Resource 關鍵字註解該類別。請注意,@Resource 註解具有 kotlinx.serialization 程式庫提供的 @Serializable 行為。

Ktor 用戶端提供了向伺服器發送型別化請求的功能。

新增相依性 ​

新增 kotlinx.serialization ​

鑑於資源類別應具備 @Serializable 行為,您需要按照設定 (Setup) 章節所述新增 Kotlin serialization 外掛程式。

新增 Resources 相依性 ​

若要使用 Resources,請將 ktor-server-resources 產物新增至您的組建指令碼中:

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

安裝 Resources ​

若要將 Resources 外掛程式安裝至您的應用程式, 請將其傳遞給指定模組模組可讓您透過對路由進行分組來建構應用程式。中的 install 函式。 以下範例展示如何安裝 Resources:

  • 在 embeddedServer() 函式呼叫中。
  • 在 Application 類別上明確定義的 module() 擴充方法中。
kotlin
import io.ktor.server.engine.*
import io.ktor.server.netty.*
import io.ktor.server.application.*
import io.ktor.server.resources.*

fun main() {
    embeddedServer(Netty, port = 8080) {
        install(Resources)
        // ...
    }.start(wait = true)
}
kotlin
import io.ktor.server.application.*
import io.ktor.server.resources.*
// ...
fun Application.module() {
    install(Resources)
    // ...
}

建立資源類別 ​

每個資源類別都應具有 @Resource 註解。 下方我們將探討幾個資源類別的範例——定義單一路徑區段、查詢與路徑參數等等。

資源 URL ​

以下範例展示如何定義 Articles 類別,該類別指定了回應 /articles 路徑的資源。

kotlin
import io.ktor.resources.*

@Resource("/articles")
class Articles()

包含查詢參數的資源 ​

下方的 Articles 類別具有一個 sort 字串屬性,該屬性充當查詢參數,並允許您定義在帶有 sort 查詢參數的路徑 /articles?sort=new 上回應的資源。

kotlin
@Resource("/articles")
class Articles(val sort: String? = "new")

包含巢狀類別的資源 ​

您可以巢狀定義類別,以建立包含多個路徑區段的資源。請注意,在這種情況下,巢狀類別應具有一個外層類別型別的屬性。 以下範例展示了一個在 /articles/new 路徑上回應的資源。

kotlin
@Resource("/articles")
class Articles() {
    @Resource("new")
    class New(val parent: Articles = Articles())
}

包含路徑參數的資源 ​

以下範例展示如何新增巢狀的 {id} 整數路徑參數,該參數會符合路徑區段並將其擷取為名為 id 的參數。

kotlin
@Resource("/articles")
class Articles() {
    @Resource("{id}")
    class Id(val parent: Articles = Articles(), val id: Long)
}

舉例來說,此資源可用於回應 /articles/12。

範例:用於 CRUD 操作的資源 ​

讓我們總結上述範例,並建立用於 CRUD 操作的 Articles 資源。

kotlin
@Resource("/articles")
class Articles(val sort: String? = "new") {
    @Resource("new")
    class New(val parent: Articles = Articles())

    @Resource("{id}")
    class Id(val parent: Articles = Articles(), val id: Long) {
        @Resource("edit")
        class Edit(val parent: Id)
    }
}

此資源可用於列出所有文章、發布新文章、編輯文章等。我們將在下一章介紹如何為此資源定義路由處理常式。

您可以在此處找到完整範例:resource-routing。

定義路由處理常式 ​

若要為具型別的資源定義路由處理常式,您需要將資源類別傳遞給動詞函式(get、post、put 等)。 例如,下方的路由處理常式會在 /articles 路徑上做出回應。

kotlin
@Resource("/articles")
class Articles()

fun Application.module() {
    install(Resources)
    routing {
        get<Articles> { articles ->
            // 取得所有文章 ...
            call.respondText("List of articles: $articles")
        }
    }
}

以下範例展示如何為在範例:用於 CRUD 操作的資源中建立的 Articles 資源定義路由處理常式。請注意,在路由處理常式內部,您可以將 Article 作為參數存取並取得其屬性值。

kotlin
fun Application.module() {
    install(Resources)
    routing {
        get<Articles> { article ->
            // 取得所有文章 ...
            call.respondText("List of articles sorted starting from ${article.sort}")
        }
        get<Articles.New> {
            // 顯示包含建立新文章欄位的頁面 ...
            call.respondText("Create a new article")
        }
        post<Articles> {
            // 儲存文章 ...
            call.respondText("An article is saved", status = HttpStatusCode.Created)
        }
        get<Articles.Id> { article ->
            // 顯示 ID 為 ${article.id} 的文章 ...
            call.respondText("An article with id ${article.id}", status = HttpStatusCode.OK)
        }
        get<Articles.Id.Edit> { article ->
            // 顯示包含編輯文章欄位的頁面 ...
            call.respondText("Edit an article with id ${article.parent.id}", status = HttpStatusCode.OK)
        }
        put<Articles.Id> { article ->
            // 更新文章 ...
            call.respondText("An article with id ${article.id} updated", status = HttpStatusCode.OK)
        }
        delete<Articles.Id> { article ->
            // 刪除文章 ...
            call.respondText("An article with id ${article.id} deleted", status = HttpStatusCode.OK)
        }
    }
}

以下是處理各個端點請求的一些訣竅:

  • get<Articles>

    此路由處理常式應該要傳回根據 sort 查詢參數排序的所有文章。 例如,這可以是包含所有文章的 HTML 頁面或 JSON 物件。

  • get<Articles.New>

    此端點以包含用於建立新文章之欄位的 Web 表單進行回應。

  • post<Articles>

    post<Articles> 端點應該要接收使用 Web 表單傳送的參數。 Ktor 還允許您使用 ContentNegotiation 外掛程式將 JSON 資料作為物件接收。

  • get<Articles.Id>

    此路由處理常式應該要傳回具有指定識別符號的文章。 這可以是顯示文章的 HTML 頁面或包含文章資料的 JSON 物件。

  • get<Articles.Id.Edit>

    此端點以包含用於編輯現有文章之欄位的 Web 表單進行回應。

  • put<Articles.Id>

    與 post<Articles> 端點類似,put 處理常式會接收使用 Web 表單傳送的表單參數。

  • delete<Articles.Id>

    此路由處理常式會刪除具有指定識別符號的文章。

您可以在此處找到完整範例:resource-routing。

除了將資源定義用於路由之外,它們還可用於建立連結。 這有時被稱為「反向路由」(reverse routing)。 如果您需要將這些連結新增至使用 HTML DSL 建立的 HTML 文件中,或者需要產生重新導向回應,從資源建立連結會非常有用。

Resources 外掛程式使用多載的 href 方法擴充了 Application,允許您從 Resource 產生連結。例如,下方的程式碼片段為上述定義的 Edit 資源建立了一個連結:

kotlin
val link: String = href(Articles.Id.Edit(Articles.Id(id = 123)))

由於祖父層級的 Articles 資源定義了預設值為 new 的 sort 查詢參數,因此 link 變數包含:

/articles/123/edit?sort=new

若要產生指定主機與通訊協定的 URL,您可以向 href 方法提供 URLBuilder。 也可以使用 URLBuilder 指定額外的查詢參數,如下列範例所示:

kotlin
val urlBuilder = URLBuilder(URLProtocol.HTTPS, "ktor.io", parameters = parametersOf("token", "123"))
href(Articles(sort = null), urlBuilder)
val link: String = urlBuilder.buildString()

隨後 link 變數包含:

https://ktor.io/articles?token=123

以下範例展示如何將從資源建立的連結新增至 HTML 回應中:

kotlin
get {
    call.respondHtml {
        body {
            this@module.apply {
                p {
                    val link: String = href(Articles())
                    a(link) { +"Get all articles" }
                }
                p {
                    val link: String = href(Articles.New())
                    a(link) { +"Create a new article" }
                }
                p {
                    val link: String = href(Articles.Id.Edit(Articles.Id(id = 123)))
                    a(link) { +"Edit an exising article" }
                }
                p {
                    val urlBuilder = URLBuilder(URLProtocol.HTTPS, "ktor.io", parameters = parametersOf("token", "123"))
                    href(Articles(sort = null), urlBuilder)
                    val link: String = urlBuilder.buildString()
                    i { a(link) { +link } }
                }
            }
        }
    }
}

您可以在此處找到完整範例:resource-routing。