(快速參考)

4 設定

版本 6.2.0

4 設定

在一個採用「慣例優於組態」的架構中，我們現在探討這個主題，這似乎有點奇怪。使用 Grails 的預設設定，你實際上可以在完全不進行任何組態的情況下開發應用程式，就像快速入門中展示的那樣，但重要的是在需要時學習在哪裡以及如何覆寫慣例。使用者指南的後續章節將提到你可以使用哪些組態設定，但不會提到如何設定它們。假設你至少已讀過本章的第一節！

4.1 基本組態

Grails 中的組態通常分為 2 個領域：建置組態和執行時期組態。

建置組態通常透過 Gradle 和 build.gradle 檔案完成。執行時期組態預設在 grails-app/conf/application.yml 檔案中以 YAML 指定。

如果你偏好使用 Grails 2.0 風格的 Groovy 組態，那麼可以使用 Groovy 的 ConfigSlurper 語法來指定組態。有兩個 Groovy 組態檔案可用：grails-app/conf/application.groovy 和 grails-app/conf/runtime.groovy

對不依賴應用程式類別的組態，請使用 application.groovy
對依賴應用程式類別的組態，請使用 runtime.groovy

這個區分是有必要的，因為在 application.groovy 中定義的組態值可供 Grails CLI 使用，而 Grails CLI 需要在應用程式編譯之前載入 application.groovy。當 CLI 執行這些命令時，application.groovy 中對應用程式類別的參照會導致例外發生

Error occurred running Grails CLI:
startup failed:script14738267015581837265078.groovy: 13: unable to resolve class com.foo.Bar

對於 Groovy 組態，下列變數可供組態指令碼使用

變數說明

userHome

正在執行 Grails 應用程式的帳戶的家目錄位置。

grailsHome

你安裝 Grails 的目錄位置。如果設定了 GRAILS_HOME 環境變數，則會使用它。

appName

應用程式名稱，如 build.gradle 中所示。

appVersion

應用程式版本，如 build.gradle 中所示。

例如

my.tmp.dir = "${userHome}/.grails/tmp"

使用 GrailsApplication 存取組態

如果你要讀取執行時期組態設定，也就是在 application.yml 中定義的設定，請使用 grailsApplication 物件，它在控制器和標籤庫中可用做變數

class MyController {
    def hello() {
        def recipient = grailsApplication.config.getProperty('foo.bar.hello')

        render "Hello ${recipient}"
    }
}

grailsApplication 物件的 config 屬性是 Config 介面的實例，並提供許多有用的方法來讀取應用程式的組態。

特別是，getProperty 方法（如上所示）對於有效率地擷取組態屬性很有用，同時指定屬性類型（預設類型為字串）和/或提供預設的備用值。

class MyController {

    def hello(Recipient recipient) {
        //Retrieve Integer property 'foo.bar.max.hellos', otherwise use value of 5
        def max = grailsApplication.config.getProperty('foo.bar.max.hellos', Integer, 5)

        //Retrieve property 'foo.bar.greeting' without specifying type (default is String), otherwise use value "Hello"
        def greeting = grailsApplication.config.getProperty('foo.bar.greeting', "Hello")

        def message = (recipient.receivedHelloCount >= max) ?
          "Sorry, you've been greeted the max number of times" :  "${greeting}, ${recipient}"
        }

        render message
    }
}

請注意，Config 實例是基於 Spring 的 PropertySource 概念合併的組態，並從環境、系統屬性和本機應用程式組態中讀取組態，將它們合併成一個單一物件。

GrailsApplication 可以輕鬆注入到服務和其他 Grails 製品中

import grails.core.*

class MyService {
    GrailsApplication grailsApplication

    String greeting() {
        def recipient = grailsApplication.config.getProperty('foo.bar.hello')
        return "Hello ${recipient}"
    }
}

GrailsConfigurationAware 介面

在執行階段動態存取組態會對應用程式的效能產生輕微的影響。另一種方法是實作 GrailsConfigurationAware 介面，它提供一個 `setConfiguration` 方法，在類別初始化時接受應用程式組態作為參數。然後，你可以將相關的組態屬性指定給類別的執行個體屬性，以供稍後使用。

`Config` 執行個體具有與注入的 `GrailsApplication` config 物件相同的屬性和用法。以下是前一個範例中的服務類別，它使用 `GrailsConfigurationAware`，而不是注入 `GrailsApplication`

import grails.core.support.GrailsConfigurationAware

class MyService implements GrailsConfigurationAware {

    String recipient

    String greeting() {
        return "Hello ${recipient}"
    }

    void setConfiguration(Config config) {
        recipient = config.getProperty('foo.bar.hello')
    }

}

Spring 值註解

你可以使用 Spring 的 Value 註解來注入組態值

import org.springframework.beans.factory.annotation.*

class MyController {
    @Value('${foo.bar.hello}')
    String recipient

    def hello() {
        render "Hello ${recipient}"
    }
}

在 Groovy 程式碼中，你必須在 `Value` 註解的值周圍使用單引號，否則它會被解釋為 GString，而不是 Spring 表達式。

如你所見，在存取組態設定時，你使用與定義它們時相同的點號表示法。

4.1.1 YML 格式 Config 的選項

`application.yml` 檔案是在 Grails 3.0 中引入的，而 YAML 現在是組態檔案的首選格式。

使用系統屬性/命令列參數

假設你正在使用 `JDBC_CONNECTION_STRING` 命令列參數，並且你想要在 yml 檔案中存取相同的內容，那麼可以按照下列方式進行

production:
    dataSource:
        url: '${JDBC_CONNECTION_STRING}'

同樣地，可以存取系統參數。

如果你使用 `./gradlew bootRun` 來啟動應用程式，則需要在 `build.gradle` 中加入這一段，以修改 `bootRun` 目標

bootRun {
    systemProperties = System.properties
}

對於測試，需要將 `test` 任務變更如下

test {
    systemProperties = System.properties
}

外部組態

Grails 預設會從 `./config` 或目前目錄讀取 `application.(properties|yml)`。由於 Grails 是 SpringBoot，因此組態選項也可用，有關文件，請參閱：https://spring-docs.dev.org.tw/spring-boot/docs/2.7.16/reference/html/features.html#features.external-config.files

4.1.2 內建選項

Grails 有一組核心設定值得了解。它們的預設值適用於大多數專案，但了解它們的作用很重要，因為你可能稍後需要其中一個或多個。

執行階段設定

在執行階段，即 `grails-app/conf/application.yml`，還有更多核心設定

grails.enable.native2ascii - 如果不需要 Grails i18n 屬性檔案的 native2ascii 轉換，請將此設定為 false（預設值：true）。
grails.views.default.codec - 設定 GSP 的預設編碼機制 - 可以是 'none'、'html' 或 'base64'（預設值：'none'）。若要降低 XSS 攻擊風險，請將此設定為 'html'。
grails.views.gsp.encoding - 用於 GSP 原始檔的檔案編碼（預設值：'utf-8'）。
grails.mime.file.extensions - 是否使用檔案副檔名在內容協商中指定 MIME 類型（預設值：true）。
grails.mime.types - 支援的 MIME 類型清單，用於內容協商。
grails.serverURL - 指定絕對連結伺服器 URL 部分的字串，包括伺服器名稱，例如 grails.serverURL="http://my.yourportal.com"。請參閱 createLink。重導也會使用此設定。
grails.views.gsp.sitemesh.preprocess - 決定是否執行 SiteMesh 前置處理。停用此設定會降低網頁呈現速度，但如果您需要 SiteMesh 來剖析從 GSP 檢視產生的 HTML，停用此設定是正確的選擇。如果您不了解這個進階屬性，不用擔心：請將它設定為 true。
grails.reload.excludes 和 grails.reload.includes - 設定這些指令會決定專案特定原始檔的重新載入行為。每個指令都會取得一個字串清單，其中包含專案原始檔的類別名稱，這些類別名稱應從重新載入行為中排除或包含，具體取決於使用 bootRun 任務在開發環境中執行應用程式時。如果設定了 grails.reload.includes 指令，則只會重新載入清單中的類別。

4.1.3 記錄

從 Grails 3.0 開始，記錄由 Logback 記錄架構處理，並且可以使用 grails-app/conf/logback.xml 檔案進行設定。

從 Grails 5.1.2 開始，已移除對 Groovy 設定 (grails-app/conf/logback.groovy) 的支援 (由 logback 1.2.9 移除)。您可以透過將 logback-groovy-config 函式庫新增到專案中，來新增 Groovy 設定。

如需設定記錄的詳細資訊，請參閱 Logback 文件中的相關主題。

4.1.3.1 記錄器名稱

Grails 人工製品 (控制器、服務 …) 會自動注入 log 屬性。

在 Grails 3.3.0 之前，Grails 人工製品的記錄器名稱遵循慣例 grails.app.<type>.<className>，其中 type 是人工製品的類型，例如 controllers 或 services，而 className 是人工製品的完整限定名稱。

Grails 3.3.x 簡化了記錄器名稱。以下範例說明了變更

BookController.groovy 位於 grails-app/controllers/com/company，未註解 @Slf4j