第三十天：為 TeamCity 設計的 Kotlin DSL

13th鐵人賽 teamcity devops kotlin dsl

聖佑

2021-10-05 23:52:29

984 瀏覽

分享至

一直以來，我們使用 TeamCity 時都是透過 Web UI 來設定，不論 Project 的 VCS、Build Configuration 都是。雖然 Web UI 可以 100% 地完成我們想做的所有設定，但這些設定都是儲存在 TeamCity 的資料庫裡，您一定要進到 TeamCity 裡才能看到。這些設定無法文件化的描述、無法做版本管理，在做類似的專案設定時也沒辦法快速複製或自動化。

設定即程式碼（Configuration as Code）

在接觸 DevOps 領域時，您一定聽過 Configuration as Code，意思就是將所有的「設定」以「程式碼」的方式紀錄。因為是程式碼，所以我們就可以用版本管理系統管理；因為是程式碼，所以我們可以直接執行來達成自動化。

假如您有使用過其他 CI 伺服器或服務的話，您可能會看過其他 CI 使用 YAML 來做 Configuration as Code。但 TeamCity 走跟他們不太一樣的路線，其採用 Kotlin DSL 做為 Configuration as Code 的格式。DSL 全名為 Domain-Specific Language，意思是針對該應用領域的邏輯及詞彙來設計的專用語言，讓非程式人員也能輕鬆上手。而 Kotlin 因為具備不少語法糖，所以非常適合拿來做為 DSL 語言。

那為什麼 TeamCity 選擇 Kotlin DSL 而不用 YAML 呢？主要有幾個原因：

YAML 的格式雖然簡單但非常依賴縮排，只要縮排一有錯誤，設定檔就會出錯。
YAML 格式本身沒有型別（Type），因此 IDE 很難針對這種格式做語法提示、自動完成、語法偵錯及智能修正。
Kotlin DSL 本身就是 Kotlin 程式碼，這代表假如今天有任何需求，開發者甚至能直接用 Kotlin 擴充功能。

開啟專案支援 Kotlin DSL 設定

要讓 TeamCity 專案支援 Kotlin DSL 很簡單，尤其當我們的專案已經使用 Git 做版本管理時，TeamCity 可以將 Kotlin DSL 產生出來並直接 Commit 到版本管理系統內。首先進到 Shopping Cart 專案設定，點選左邊側邊欄的 Versioned Settings：

在 Versioned Settings 設定頁，將同步設定從原本的 Use settings from a parent project 改成 Synchronization enabled，接著設定 Project settings VCS root 為專案的 Git 來源、Settings format 選 Kotlin，其他保持預設，完成後按 Apply 套用。

TeamCity 會將目前所有的專案設定以 Kotlin DSL 的格式輸出成檔案，並自動將輸出檔 Commit & Push 到版本管理系統裡。在這邊要稍為注意一下的是，在開啟同步設定的過程中，TeamCity 會暫時把 Web UI 轉成唯讀（Read-only）模式，直到完成 Commit & Push 且完成跟 TeamCity 的同步後就會恢複。

若只是想看一下 TeamCity 的 Kotlin DSL 設定檔輸出格式，暫時還不想開啟同步設定模式的話，也可以到專案設定首頁，點選右上角的 Actions 下拉式選單，選擇 Download settings in Kotlin format...

TeamCity 就會把目前專案的 Kotlin DSL 設定檔以 Zip 檔的格式下載下來。

編輯 TeamCity Kotlin DSL

回到 IntelliJ IDEA，我們先將剛剛 TeamCity 輸出 Kotlin DSL 設定檔的那個 Commit 從版本管理系統 Pull 下來。我們會看到在這個 Commit 裡，TeamCity 在專案原始碼裡加了一個 .teamcity 的資料夾，裡面有 2 個檔案：

settings.kts：包含所有專案設定的主要 Kotlin DSL 檔案。
pom.xml：讓 IDE 可以抓到編輯 Kotlin DSL 時所需要的所有相依套件，以及執行編譯或運行測試所需要的工具。

為了讓 IntelliJ IDEA 能真正識別這 2 個檔案以及具備程式碼提示等 IDE 功能，我們需要先將 .teamcity 資料夾變成一個 Module。請先點選 File > Project Structure，接著切換到 Project settings 底下的 Modules，點選 + 按鈕後選擇 Import Module。

在彈出式視窗裡選擇專案底下的 .teamcity 資料夾後按 Open 開啟。再選擇 Maven 做為 Module 使用的相依管理工具，接著按 Finish 關閉視窗，再按 OK 完成 Project Structure 設定。

完成 Module 設定後，IntelliJ IDEA 會花一些時間把所有需要的相依及工具載入。接著我們再打開 .teamcity/settings.kts 時，就會發現所有的程式碼都已經正確上色，輸入程式碼時也會有自動完成的提示了！

以 Kotlin DSL 自動化設定專案

學會了輸出 Kotlin DSL 的技巧後，我們也能將這個用在自動化設定專案上。也就是說，我們可以在新專案裡新增一樣的 TeamCity Kotlin DSL 目錄結構，當我們在 TeamCity 裡建立這個專案時，TeamCity 會自動抓到這個專案根目錄底下 .teamcity 的內容，然後自動根據裡面的 Kotlin DSL 幫我們設定。

首先我們先建立一個全新的 Kotlin 專案，完成一些功能後，依照前一步的方式新增 Module 及 .teamcity 底下的所有檔案，settings.kts 裡可以寫一段最基本跑 Gradle Build 的 Build Step，完成後就 Commit & Push 到 VCS 上：

import jetbrains.buildServer.configs.kotlin.v2019_2.*
import jetbrains.buildServer.configs.kotlin.v2019_2.buildSteps.gradle

version = "2021.1"

project {

    buildType(Build)
}

object Build : BuildType({
    name = "Build"

    vcs {
        root(DslContext.settingsRoot)
    }

    steps {
        gradle {
            tasks = "clean build"
            gradleWrapperPath = ""
        }
    }
})

接著到 TeamCity 建立新專案，以剛剛做好的專案為 Repository 來源，我們會發現 TeamCity 在抓取資料時自動發現 .teamcity 設定檔已存在，會詢問我們是不是直接依照設定檔內容設定即可？按確定後，TeamCity 就自動完成了所有設定，我們再進到 Build Configuration 裡就會看到剛設定的 Build Step 都已經自動設定好了。