之前的系列文 Kotlin 手刻 Ktor 從零開始 用 32 篇手刻了一個叫 Relix 的框架，把 Routing、Pipeline、Plugin、receive<T>() 這些機制都自己做過一遍，那個系列回答的問題是「框架是怎麼做出來的」

不過手刻完之後，Relix 主要是教學用框架，跑在 JDK 內建的 HttpServer 上，很多真實情況直接不處理，設定管理、資料庫、migration、認證、部署這些平常工作每天要面對的東西，刻意都沒碰，因為它們跟「理解框架機制」無關

所以這個系列反過來，用正式的 Ktor，把一個服務從開專案一路做到可以部署的程度，重點從「理解框架怎麼做」換成「把框架用好」

跟 Relix 系列的關係

兩個系列是獨立的，沒看過 Relix 系列完全可以直接從這裡開始，這個系列講到的每個 Ktor 機制都會從頭解釋，不會假設你知道 Relix 是什麼

看過的人則會多一層對照，講到 Routing、Pipeline、Plugin、receive 這些機制時，會回頭對照「手刻時我們是怎麼做的、Ktor 實際怎麼解」，同一個問題看過兩種解法，印象會深很多

最具體的一個例子是 Relix 系列收尾時留的伏筆，Relix 的 middleware 是一串函式包一串函式，誰包住誰完全由 install 順序決定，可是 plugin 是各自獨立安裝的，彼此不知道對方存在，這個排序問題我們當時用「你自己顧好 install 順序」帶過去了，Ktor 的 phase-based pipeline 就是在解這個問題

系列會怎麼寫

這個系列有一條貫穿的主線，一個 Todo API，從 day 05 加上第一個端點開始，跟著整個系列一路長大，接上 JSON、加輸入驗證、用 DI 抽出 repository、用 Exposed 把記憶體實作換成真的資料庫、用 Authentication 保護路由，最後部署出去

所以這不是一篇篇互不相干的功能教學，每篇講的內容最後都會回到同一個專案上，day 32 會做完整組裝，day 33 補上瀏覽器入口，day 34 打包並放進容器

系列路線圖

大致會這樣走

測試怎麼安排

呈現方式延續 Relix 系列，每篇會先交代這次要固定的行為，測試程式碼則放在對應的實驗或實作附近，文章不走 baby step，理由跟之前一樣，一輪一輪的測試循環會把文章拉得很長，想講的主題反而被流程蓋過去

測試段落的位置會隨篇章的性質變動。加新端點的那幾篇，行為事先就講得清楚，測試寫在實作前面當規格。裝 plugin、把框架預設行為挖出來的那種則相反，先做出來看清楚框架給了什麼，再用測試把要固定的部分寫下來

原則很簡單，每篇列進規格，後續不能悄悄改掉的行為都要有測試，測試用官方的 testApplication，不啟動真的 server、不綁 port，day 03 會先把這套測試慣例建立起來，探索性實驗會提供可重現的步驟，暫時不保證的行為也會直接標出來，設定、建置與部署這類主題則不硬塞測試，改用指令確認結果

那套測試覆蓋的是 plugin 到 handler 這幾層，不含 socket 跟 engine，真的起一台 server、綁真的 port、從外面打進去的 end to end 測試留到 day 35

技術版本與工具

整個系列鎖定 Ktor 3.5.2 (2026-08-04 發佈)，所有程式碼都在這個版本上驗證過，相依套件用官方提供的 Gradle version catalog 管理，版本統一放在一個檔案裡，day 02 建專案時會講

其他的選擇

• 建置工具用 Gradle + Kotlin
• JSON 用 kotlinx.serialization
• 資料庫走 Exposed + HikariCP，這是 JDBC 的路線，底層是阻塞的，系列裡會把「阻塞 I/O 遇上協程該怎麼辦」講清楚，不會假裝它是非阻塞
• DI 用官方的 ktor-server-di plugin，Ktor 3.2 開始提供，不用再另外掛 Koin
• 測試用官方的 testApplication

開始之前

這個系列假設你會 Kotlin 的基礎語法，data class、null safety、trailing lambda 這些要看得懂，不需要先懂協程的內部運作，Ktor 的 DSL 大量用到 lambda with receiver，遇到的時候會說明

也不需要看過 Relix 系列，對照的段落我會把 Relix 那邊的做法簡短重述一次，你不用回頭補課，當然，如果你看完這個系列之後對「框架內部怎麼運作」有興趣，再回去看那個系列，順序反過來也完全成立

小結

如果你想知道 routing 或 pipeline 在框架內部是怎麼實作的，Relix 系列會比這個系列合適，這裡不會再重做一次底層機制

這個系列把 Ktor 當成要用在正式專案上的框架來對待，每個 plugin 為什麼裝、參數為什麼這樣設、測試怎麼寫才不會綁在實作細節上，最後交出一個有資料庫、有認證、測試完整、可以部署的 Todo API

下一篇

下一篇從建專案開始，用 Gradle 和官方的 version catalog 建立一個 Ktor 3.5.2 專案，確認 build、run、test 都跑得動，後面 33 篇都會在這個專案上一路疊上去

參考資料

• Ktor 官方文件
• Ktor 官方文件 - Creating a new Ktor project
• Ktor 官方文件 - Testing
• Ktor 官方文件 - Dependency injection
• Ktor 官方文件 - Releases
• Exposed 官方文件
• Gradle 官方文件 - Version catalogs
• Kotlin 手刻 Ktor 從零開始 系列導讀

同步刊登於 Blog

圖片來源：AI 產生