Skip to content

使用 Kotlin 建立 Spring Boot 專案 ​

本教學的第一部分將介紹如何在 IntelliJ IDEA 中使用專案精靈,透過 Gradle 建立一個 Spring Boot 專案。

本教學不強制要求使用 Gradle 作為建置系統。如果你使用 Maven,也可以依照相同的步驟操作。

開始之前 ​

下載並安裝最新版本的 IntelliJ IDEA,並使用 Ultimate 訂閱。

如果你使用的 IntelliJ IDEA 沒有 Ultimate 訂閱,或是使用其他 IDE,可以透過 網頁版專案產生器 來產生 Spring Boot 專案。

建立 Spring Boot 專案 ​

使用 IntelliJ IDEA 中的專案精靈建立一個新的 Kotlin Spring Boot 專案:

  1. 在 IntelliJ IDEA 中,選取 File | New | Project。

  2. 在左側面板的 Generators 區段中選取 Spring Boot。

  3. 在 New Project 視窗中指定以下欄位與選項:

    • Name:demo

    • Language:Kotlin

    • Type:Gradle - Kotlin

      此選項指定了建置系統與 DSL。

    • Package name:com.example.demo

    • JDK:Java JDK

      本教學使用 Amazon Corretto 版本 23。 如果你尚未安裝 JDK,可以從下拉式清單中下載。

    • Java:17

      如果你尚未安裝 Java 17,可以從 JDK 下拉式清單中下載。

    建立 Spring Boot 專案

  4. 確認已指定所有欄位後,點擊 Next。

  5. 選取本教學所需的以下相依性:

    • Web | Spring Web
    • SQL | Spring Data JDBC
    • SQL | H2 Database

    設定 Spring Boot 專案

  6. 點擊 Create 以產生並設定專案。

    IDE 將產生並開啟新專案。下載並匯入專案相依性可能需要一些時間。

  7. 完成後,你可以在 Project 檢視中看到以下結構:

    設定 Spring Boot 專案

    產生的 Gradle 專案符合 Maven 的標準目錄結構:

    • main/kotlin 資料夾下的套件與類別屬於該應用程式。
    • 應用程式的入口點是 DemoApplication.kt 檔案中的 main() 方法。

探索專案的 Gradle 建置檔案 ​

開啟 build.gradle.kts 檔案:這是 Gradle Kotlin 建置指令碼,其中包含應用程式所需的相依性清單。

此 Gradle 檔案符合 Spring Boot 的標準格式,但同時也包含了必要的 Kotlin 相依性,包括 kotlin-spring Gradle 外掛程式 – kotlin("plugin.spring")。

以下是完整的指令碼,並附有各部分與相依性的說明:

kotlin
// build.gradle.kts
plugins {
    kotlin("jvm") version "2.3.21" // 要使用的 Kotlin 版本
    kotlin("plugin.spring") version "2.3.21" // Kotlin Spring 外掛程式
    id("org.springframework.boot") version "4.1.1"
    id("io.spring.dependency-management") version "1.1.7"
}

group = "com.example"
version = "0.0.1-SNAPSHOT"

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(17)
    }
}

repositories {
    mavenCentral()
}

dependencies {
    implementation("org.springframework.boot:spring-boot-h2console")
    implementation("org.springframework.boot:spring-boot-starter-data-jdbc")
    implementation("org.springframework.boot:spring-boot-starter-webmvc")
    implementation("org.jetbrains.kotlin:kotlin-reflect") // Kotlin 反射程式庫,用於搭配 Spring
    implementation("tools.jackson.module:jackson-module-kotlin") // 適用於 Kotlin 的 Jackson 擴充套件,用於處理 JSON
    runtimeOnly("com.h2database:h2")
    testImplementation("org.springframework.boot:spring-boot-starter-data-jdbc-test")
    testImplementation("org.springframework.boot:spring-boot-starter-webmvc-test")
    testImplementation("org.jetbrains.kotlin:kotlin-test-junit5")
    testRuntimeOnly("org.junit.platform:junit-platform-launcher")
}

kotlin {
    compilerOptions {
        freeCompilerArgs.addAll("-Xjsr305=strict", "-Xannotation-default-target=param-property") // `-Xjsr305=strict` 啟用 JSR-305 註解的嚴格模式
    }
}

tasks.withType<Test> {
    useJUnitPlatform()
}

如你所見,Gradle 建置檔案中新增了幾個與 Kotlin 相關的構件:

  1. 在 plugins 區塊中,有兩個 Kotlin 構件:

    • kotlin("jvm") 外掛程式定義了專案中使用的 Kotlin 版本。
    • Kotlin Spring 編譯器外掛程式 kotlin("plugin.spring"),它會為 Kotlin 類別新增 open 修飾詞,使其與 Spring 架構的功能相容。
  2. 在 dependencies 區塊中,列出了幾個與 Kotlin 相關的模組:

    • tools.jackson.module:jackson-module-kotlin 模組新增了對 Kotlin 類別和資料類別序列化與反序列化的支援。
    • org.jetbrains.kotlin:kotlin-reflect 是一個 Kotlin 反射程式庫,能完整支援反射功能。
  3. 在相依性區段之後,可以看到 kotlin 外掛程式的設定區塊。 你可以在此處向編譯器新增額外引數,以啟用或停用各種語言特性。

在 Kotlin Gradle 外掛程式中的編譯器選項 中進一步了解 Kotlin 編譯器選項。

探索產生的 Spring Boot 應用程式 ​

開啟 DemoApplication.kt 檔案:

kotlin
// DemoApplication.kt
package com.example.demo

import org.springframework.boot.autoconfigure.SpringBootApplication
import org.springframework.boot.runApplication

@SpringBootApplication
class DemoApplication

fun main(args: Array<String>) {
    runApplication<DemoApplication>(*args)
}
宣告類別 – class DemoApplication

在套件宣告和 import 陳述式之後,你可以看到第一個類別宣告:class DemoApplication。

在 Kotlin 中,如果一個類別不包含任何成員(屬性或函式),你可以完全省略類別主體({})。

@SpringBootApplication 註解

@SpringBootApplication 註解 是 Spring Boot 應用程式中的便利註解。 它啟用了 Spring Boot 的自動組態、組件掃描,並允許在其「應用程式類別」上定義額外設定。

程式進入點 – main()

main() 函式是應用程式的入口點。

它被宣告為 DemoApplication 類別之外的頂層函式。main() 函式會呼叫 Spring 的 runApplication(*args) 函式,以透過 Spring 架構啟動應用程式。

可變參數 – args: Array<String>

如果檢查 runApplication() 函式的宣告,你會發現該函式的參數帶有 vararg 修飾詞:vararg args: String。 這表示你可以向該函式傳遞可變數量的 String 引數。

展開運算子 – (*args)

args 是傳遞給 main() 函式的參數,宣告為字串陣列。 由於這是一個字串陣列,而你希望將其內容傳遞給函式,因此請使用展開運算子(在陣列前加上星號 *)。

建立控制器 ​

應用程式已準備好執行,但讓我們先更新其邏輯。

在 Spring 應用程式中,控制器用於處理 Web 請求。 在相同的套件中、與 DemoApplication.kt 檔案相鄰的位置,建立 MessageController.kt 檔案,其中包含 MessageController 類別,內容如下:

kotlin
// MessageController.kt
package com.example.demo

import org.springframework.web.bind.annotation.GetMapping
import org.springframework.web.bind.annotation.RequestParam
import org.springframework.web.bind.annotation.RestController

@RestController
class MessageController {
    @GetMapping("/")
    fun index(@RequestParam("name") name: String) = "Hello, $name!"
}
@RestController 註解

你需要告訴 Spring MessageController 是一個 REST 控制器,因此應該使用 @RestController 註解標記它。

此註解表示該類別將被組件掃描納入,因為它與我們的 DemoApplication 類別位於相同的套件中。

@GetMapping 註解

@GetMapping 用於標記 REST 控制器中實作對應 HTTP GET 呼叫之端點的函式:

kotlin
@GetMapping("/")
fun index(@RequestParam("name") name: String) = "Hello, $name!"
@RequestParam 註解

函式參數 name 使用 @RequestParam 註解標記。此註解表示方法參數應繫結到 Web 請求參數。

因此,如果你存取應用程式的根路徑並提供名為 "name" 的請求參數(例如 /?name=<your-value>),該參數值將作為呼叫 index() 函式的引數。

單一運算式函式 – index()

由於 index() 函式僅包含一個陳述式,因此你可以將其宣告為單一運算式函式。

這表示可以省略花括號,並將主體直接指定在等號 = 之後。

函式傳回型別的型別推論

index() 函式並未明確宣告傳回型別。相反地,編譯器會根據等號 = 右側陳述式的結果來推論傳回型別。

Hello, $name! 運算式的型別為 String,因此該函式的傳回型別也是 String。

字串範本 – $name

Hello, $name! 運算式在 Kotlin 中稱為字串範本。

字串範本是包含內嵌運算式的字串常值。

這是字串連接操作的便利替代方案。

執行應用程式 ​

Spring 應用程式現在已準備好執行:

  1. 在 DemoApplication.kt 檔案中,點擊 main() 方法旁邊欄中的綠色 Run 圖示:

    執行 Spring Boot 應用程式

    你也可以在終端中執行 ./gradlew bootRun 指令。

    這會在你的電腦上啟動本機伺服器。

  2. 應用程式啟動後,請開啟以下 URL:

    text
    http://localhost:8080?name=John

    你應該會看到回應印出 "Hello, John!":

    Spring 應用程式回應

下一步 ​

在本教學的下一部分中,你將學習 Kotlin 資料類別以及如何在應用程式中使用它們。