工作階段 (Sessions)
必要相依性:io.ktor:ktor-server-sessions
程式碼範例: session-cookie-client、 session-cookie-server、 session-header-server
原生伺服器Ktor 支援 Kotlin/Native,可讓您在無需額外執行階段或虛擬機的情況下執行伺服器。 支援:✅
Sessions 外掛程式提供了一種在不同 HTTP 請求之間保留資料的機制。常見的使用案例包括儲存已登入使用者的 ID、購物車內容,或在用戶端保留使用者偏好設定。在 Ktor 中,你可以使用 Cookie 或自訂標頭來實作工作階段,選擇將工作階段資料儲存在伺服器上還是傳遞給用戶端,對工作階段資料進行簽名與加密等。
在本主題中,我們將介紹如何安裝 Sessions 外掛程式、進行配置,以及在路由處理常式中存取工作階段資料。
新增相依性
若要啟用對工作階段的支援,你需要在組建指令碼中包含 ktor-server-sessions 構件:
implementation(ktorLibs.server.sessions)implementation ktorLibs.server.sessions<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-server-sessions-jvm</artifactId>
<version>${ktor_version}</version>
</dependency>安裝 Sessions
若要將 Sessions 外掛程式安裝至你的應用程式中, 請在指定的 模組模組可讓您透過對路由進行分組來建構應用程式。 中將其傳遞給 install 函式。 以下範例示範如何安裝 Sessions:
- 在
embeddedServer()函式呼叫中。 - 在
Application類別上明確定義的module()擴充函式中。
import io.ktor.server.engine.*
import io.ktor.server.netty.*
import io.ktor.server.application.*
import io.ktor.server.sessions.*
fun main() {
embeddedServer(Netty, port = 8080) {
install(Sessions)
// ...
}.start(wait = true)
}import io.ktor.server.application.*
import io.ktor.server.sessions.*
// ...
fun Application.module() {
install(Sessions)
// ...
}Sessions 外掛程式也可以安裝到特定路由。 如果你需要為不同的應用程式資源使用不同的 Sessions 配置,這會非常有用。
工作階段配置概覽
若要配置 Sessions 外掛程式,你需要執行以下步驟:
建立資料類別:在配置工作階段之前,你需要建立一個用於儲存工作階段資料的 資料類別 (data class)。
選擇如何在伺服器與用戶端之間傳遞資料:使用 Cookie 或自訂標頭。Cookie 更適合純 HTML 應用程式,而自訂標頭則適用於 API。
選擇工作階段有效負載的儲存位置:儲存在用戶端或伺服器上。你可以使用 Cookie/標頭值將序列化的工作階段資料傳遞給用戶端,也可以將有效負載儲存在伺服器上並僅傳遞工作階段識別碼。
如果你想在伺服器上儲存工作階段有效負載,你可以選擇其儲存方式:儲存在伺服器記憶體中或資料夾中。你也可以實作自訂存儲來保存工作階段資料。
保護工作階段資料:為了保護傳遞給用戶端的敏感工作階段資料,你需要對工作階段有效負載進行簽名與加密。
配置 Sessions 後,你可以在路由處理常式中取得並設定工作階段資料。
建立資料類別
在配置工作階段之前,你需要建立一個用於儲存工作階段資料的 資料類別 (data class)。 例如,下方的 UserSession 類別將用於儲存工作階段 ID 和頁面檢視次數:
@Serializable
data class UserSession(val id: String, val count: Int)如果你打算使用多個工作階段,則需要建立多個資料類別。
傳遞工作階段資料:Cookie 與標頭
Cookie
若要使用 Cookie 傳遞工作階段資料,請在 install(Sessions) 區塊內呼叫帶有指定名稱和資料類別的 cookie 函式:
install(Sessions) {
cookie<UserSession>("user_session")
}在上述範例中,工作階段資料將透過新增至 Set-Cookie 標頭的 user_session 屬性傳遞給用戶端。你可以透過在 cookie 區塊中傳遞引數來配置其他 Cookie 屬性。例如,以下程式碼片段示範如何指定 Cookie 的路徑和過期時間:
install(Sessions) {
cookie<UserSession>("user_session") {
cookie.path = "/"
cookie.maxAgeInSeconds = 10
}
}如果未明確公開所需的屬性,請使用 extensions 屬性。例如,你可以透過以下方式傳遞 SameSite 屬性:
install(Sessions) {
cookie<UserSession>("user_session") {
cookie.extensions["SameSite"] = "lax"
}
}若要進一步了解可用的配置設定,請參閱 CookieConfiguration。
標頭
若要使用自訂標頭傳遞工作階段資料,請在 install(Sessions) 區塊內呼叫帶有指定名稱和資料類別的 header 函式:
install(Sessions) {
header<CartSession>("cart_session")
}在上述範例中,工作階段資料將使用 cart_session 自訂標頭傳遞給用戶端。 在用戶端,你需要將此標頭附加到每個請求中以取得工作階段資料。
如果你使用 CORS 外掛程式來處理跨來源請求,請將自訂標頭新增至 CORS 配置中,如下所示:
install(CORS) {
allowHeader("cart_session")
exposeHeader("cart_session")
}僅在修改時傳送工作階段資料
預設情況下,Ktor 會在每個回應中傳送工作階段資料,即使資料未發生變更。
若要僅在工作階段資料被修改時才傳送,請在工作階段配置中啟用 sendOnlyIfModified 旗標:
install(Sessions) {
cookie<MySession>("SESSION") {
sendOnlyIfModified = true
}
}儲存工作階段有效負載:用戶端與伺服器
在 Ktor 中,你可以透過兩種方式管理工作階段資料:
在用戶端和伺服器之間傳遞工作階段資料。
如果僅將工作階段名稱傳遞給 cookie 或 header 函式,則工作階段資料將在用戶端和伺服器之間傳遞。在這種情況下,你需要簽名並加密工作階段有效負載,以保護傳遞給用戶端的敏感工作階段資料。
在伺服器上儲存工作階段資料,並僅在用戶端和伺服器之間傳遞工作階段 ID。
在這種情況下,你可以選擇有效負載在伺服器上的儲存位置。例如,你可以將工作階段資料儲存在記憶體中、指定的資料夾中,或者實作自己的自訂存儲。
在伺服器上儲存工作階段有效負載
Ktor 允許你在伺服器上儲存工作階段資料,並僅在伺服器與用戶端之間傳遞工作階段 ID。在此情況下,你可以選擇有效負載在伺服器上的保存位置。
記憶體內儲存
SessionStorageMemory 允許在記憶體中儲存工作階段內容。此存儲會在伺服器執行期間保留資料,一旦伺服器停止就會捨棄資訊。例如,你可以如下在伺服器記憶體中儲存 Cookie:
cookie<CartSession>("cart_session", SessionStorageMemory()) {
}你可以在此處找到完整的範例:session-cookie-server。
請注意,SessionStorageMemory 僅適用於開發環境。
目錄儲存
directorySessionStorage 可用於將工作階段資料儲存在指定目錄下的檔案中。例如,若要將工作階段資料儲存在 build/.sessions 目錄下的檔案中,請依此方式建立 directorySessionStorage:
header<CartSession>("cart_session", directorySessionStorage(File("build/.sessions"))) {
}你可以在此處找到完整的範例:session-header-server。
自訂儲存
Ktor 提供了 SessionStorage 介面,可讓你實作自訂存儲。
interface SessionStorage {
suspend fun invalidate(id: String)
suspend fun write(id: String, value: String)
suspend fun read(id: String): String
}這三個函式都是掛起函式 (suspending function)。你可以將 SessionStorageMemory 作為參考。
保護工作階段資料
對工作階段資料進行簽名
對工作階段資料進行簽名可以防止工作階段內容被修改,但允許使用者檢視該內容。 若要簽名工作階段,請將簽名金鑰傳遞給 SessionTransportTransformerMessageAuthentication 建構函式,並將此執行個體傳遞給 transform 函式:
install(Sessions) {
val secretSignKey = "6819b57a326945c1968f45236589".hexToByteArray()
cookie<CartSession>("cart_session", SessionStorageMemory()) {
cookie.path = "/"
transform(SessionTransportTransformerMessageAuthentication(secretSignKey))
}
}SessionTransportTransformerMessageAuthentication 預設使用 HmacSHA256 作為驗證演算法,此演算法可以變更。
對工作階段資料進行簽名與加密
對工作階段資料進行簽名與加密可以防止讀取和修改工作階段內容。 若要簽名並加密工作階段,請將簽名/加密金鑰傳遞給 SessionTransportTransformerEncrypt 建構函式,並將此執行個體傳遞給 transform 函式:
install(Sessions) {
val secretEncryptKey = "00112233445566778899aabbccddeeff".hexToByteArray()
val secretSignKey = "6819b57a326945c1968f45236589".hexToByteArray()
cookie<UserSession>("user_session") {
cookie.path = "/"
cookie.maxAgeInSeconds = 10
transform(SessionTransportTransformerEncrypt(secretEncryptKey, secretSignKey))
}
}請注意,加密方法已在 Ktor 版本 3.0.0 中更新。 如果你正在從較早版本進行遷移,請在 SessionTransportTransformerEncrypt 的建構函式中使用 backwardCompatibleRead 屬性, 以確保與現有工作階段相容。
預設情況下,SessionTransportTransformerEncrypt 使用 AES 和 HmacSHA256 演算法,這些演算法可以變更。
取得與設定工作階段內容
若要為特定路由設定工作階段內容,請使用 call.sessions 屬性。set 方法允許你建立新的工作階段執行個體:
get("/login") {
call.sessions.set(UserSession(id = "123abc", count = 0))
call.respondRedirect("/user")
}若要取得工作階段內容,你可以呼叫 get,並傳入已註冊的工作階段型別作為型別參數:
get("/user") {
val userSession = call.sessions.get<UserSession>()
if (userSession != null) {
}若要修改工作階段(例如累加計數器),你需要呼叫資料類別的 copy 方法:
get("/user") {
val userSession = call.sessions.get<UserSession>()
if (userSession != null) {
call.sessions.set(userSession.copy(count = userSession.count + 1))
call.respondText("Session ID is ${userSession.id}. Reload count is ${userSession.count}.")
} else {
call.respondText("Session doesn't exist or is expired.")
}
}當你因任何原因需要清除工作階段時(例如使用者登出時),請呼叫 clear 函式:
get("/logout") {
call.sessions.clear<UserSession>()
call.respondRedirect("/user")
}你可以在此處找到完整的範例:session-cookie-client。
延遲擷取工作階段
預設情況下,Ktor 會為每個包含工作階段的請求嘗試從存儲中讀取工作階段,而不管 該路由是否實際需要它。這種行為可能會導致不必要的開銷 —— 特別是在使用自訂工作階段存儲的應用程式中。
你可以透過啟用 io.ktor.server.sessions.deferred 系統屬性來延遲工作階段的載入:
System.setProperty("io.ktor.server.sessions.deferred", "true")範例
以下可執行的範例示範了如何使用 Sessions 外掛程式:
- session-cookie-client 示範如何使用 Cookie 將已簽名與加密的工作階段有效負載傳遞給用戶端。
- session-cookie-server 示範如何將工作階段有效負載保存在伺服器記憶體中,並使用 Cookie 將已簽名的工作階段 ID 傳遞給用戶端。
- session-header-server 示範如何將工作階段有效負載保存在伺服器的目錄儲存中,並使用自訂標頭將已簽名的工作階段 ID 傳遞給用戶端。
