使用 Kotlin 建立 Spring Boot 專案

這是「Spring Boot 與 Kotlin 入門」教學的第一部分：

使用 Kotlin 建立 Spring Boot 專案
在 Spring Boot 專案中新增資料類別
為 Spring Boot 專案新增資料庫支援
使用 Spring Data CrudRepository 進行資料庫存取

本教學的第一部分將展示如何使用 IntelliJ IDEA 中的專案精靈 (Project Wizard) 透過 Gradle 建立一個 Spring Boot 專案。

本教學不強制要求使用 Gradle 作為建構系統。如果您使用 Maven，也可以遵循相同的步驟。

開始之前

下載並安裝最新版本的 IntelliJ IDEA Ultimate Edition。

如果您使用 IntelliJ IDEA Community Edition 或其他 IDE，您可以透過 基於網頁的專案產生器 來產生 Spring Boot 專案。

建立 Spring Boot 專案

使用 IntelliJ IDEA Ultimate Edition 中的專案精靈來建立一個新的 Kotlin Spring Boot 專案：

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

2. 在左側面板中，選取 New Project | 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 下拉式選單中下載。

   

4. 確保您已指定所有欄位，然後點擊 Next (下一步)。

5. 選取教學所需的以下相依性 (dependencies)：

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

   

6. 點擊 Create (建立) 以產生並設定專案。

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

7. 完成後，您可以在 Project view (專案檢視) 中觀察到以下結構：

   

   所產生的 Gradle 專案與 Maven 的標準目錄佈局相符：

   • 在 main/kotlin 資料夾下有屬於應用程式的套件和類別。
   • 應用程式的進入點 (entry point) 是 DemoApplication.kt 檔案的 main() 方法。

探索專案的 Gradle 建構檔

開啟 build.gradle.kts 檔案：它是 Gradle Kotlin 建構腳本，其中包含應用程式所需相依性的列表。

此 Gradle 檔案對於 Spring Boot 來說是標準的，但它也包含必要的 Kotlin 相依性，包括 kotlin-spring Gradle 外掛程式 (plugin) – kotlin("plugin.spring")。

以下是完整腳本以及所有部分和相依性的解釋：

// build.gradle.kts
plugins {
    kotlin("jvm") version "1.9.25" // 要使用的 Kotlin 版本
    kotlin("plugin.spring") version "1.9.25" // Kotlin Spring 外掛程式
    id("org.springframework.boot") version "3.4.5"
    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-starter-data-jdbc")
    implementation("org.springframework.boot:spring-boot-starter-web")
    implementation("com.fasterxml.jackson.module:jackson-module-kotlin") // 用於與 JSON 協作的 Kotlin Jackson 擴充功能
    implementation("org.jetbrains.kotlin:kotlin-reflect") // Kotlin 反射函式庫，Spring 協作所需
    runtimeOnly("com.h2database:h2")
    testImplementation("org.springframework.boot:spring-boot-starter-test")
    testImplementation("org.jetbrains.kotlin:kotlin-test-junit5")
    testRuntimeOnly("org.junit.platform:junit-platform-launcher")
}

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

tasks.withType<Test> {
    useJUnitPlatform()
}

如您所見，Gradle 建構檔中新增了一些與 Kotlin 相關的 artifacts：

1. 在 plugins 區塊中，有兩個 Kotlin artifacts：

   • kotlin("jvm") – 此外掛程式定義了專案中使用的 Kotlin 版本
   • kotlin("plugin.spring") – Kotlin Spring 編譯器外掛程式，用於向 Kotlin 類別新增 open 修飾符 (modifier)，使其與 Spring Framework 功能相容

2. 在 dependencies 區塊中，列出了一些與 Kotlin 相關的模組：

   • com.fasterxml.jackson.module:jackson-module-kotlin – 此模組增加了對 Kotlin 類別和資料類別的序列化 (serialization) 和反序列化 (deserialization) 支援
   • org.jetbrains.kotlin:kotlin-reflect – Kotlin 反射函式庫 (reflection library)

3. 在相依性區段之後，您可以看到 kotlin 外掛程式的組態區塊。 您可以在此處為編譯器新增額外參數，以啟用或停用各種語言功能。

了解更多關於 Kotlin 編譯器選項的資訊，請參閱 。

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

開啟 DemoApplication.kt 檔案：

// 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 的 自動組態 (auto-configuration)、元件掃描 (component scan)，並且能夠在「應用程式類別」上定義額外組態。

程式進入點 – main()

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

它被宣告為 DemoApplication 類別之外的頂層函數 (top-level function)。main() 函數呼叫 Spring 的 runApplication(*args) 函數，以啟動 Spring Framework 應用程式。

可變引數 – args: Array<String>

如果您檢查 runApplication() 函數的宣告，您會看到函數的參數被標記為 vararg 修飾符：vararg args: String。 這意味著您可以向函數傳遞可變數量的 String 引數。

展開運算子 – (*args)

args 是 main() 函數的一個參數，宣告為 String 陣列。 由於這是一個 String 陣列，並且您想將其內容傳遞給函數，因此請使用展開運算子 (spread operator)（在陣列前加上星號 *）。

建立控制器

應用程式已準備就緒可以執行，但讓我們先更新其邏輯。

在 Spring 應用程式中，控制器 (controller) 用於處理網頁請求。 在與 DemoApplication.kt 檔案相同的套件中，建立 MessageController.kt 檔案，其中包含 MessageController 類別，如下所示：

// 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 控制器 (REST Controller)，因此您應該用 @RestController 註解來標記它。

這個註解表示這個類別將會被元件掃描 (component scan) 所識別，因為它與我們的 DemoApplication 類別位於同一個套件中。

@GetMapping 註解

@GetMapping 標記了 REST 控制器中實作對應 HTTP GET 呼叫端點 (endpoints) 的函數：

@RequestParam 註解

函數參數 name 被標記為 @RequestParam 註解。這個註解表示方法參數應該綁定到網頁請求參數。

因此，如果您在根目錄存取應用程式並提供一個名為「name」的請求參數，例如 /?name=<your-value>，該參數值將被用作呼叫 index() 函數的引數。

單一表達式函數 – index()

由於 index() 函數只包含一個語句，您可以將其宣告為單一表達式函數 (single-expression function)。

這表示可以省略花括號 (curly braces)，並且函數主體在等號 = 後面指定。

函數回傳型別的型別推斷

index() 函數沒有明確宣告回傳型別。相反地，編譯器透過查看等號 = 右側語句的結果來推斷回傳型別。

表達式 Hello, $name! 的型別是 String，因此函數的回傳型別也是 String。

字串模板 – $name

Hello, $name! 表達式在 Kotlin 中稱為字串模板 (String template)。

字串模板是包含嵌入式表達式的字串文字 (String literals)。

這是字串串聯 (String concatenation) 操作的便捷替代方案。

執行應用程式

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

1. 在 DemoApplication.kt 檔案中，點擊 main() 方法旁裝訂線 (gutter) 中的綠色 Run (執行) 圖示：

   

   您也可以在終端機中執行 ./gradlew bootRun 命令。

   這將在您的電腦上啟動本地伺服器。

2. 應用程式啟動後，開啟以下 URL：

   http://localhost:8080?name=John

   您應該會看到「Hello, John!」作為回應：

   

下一步

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

前往下一章