(快速參考)

2 開始使用

版本 6.2.0

2 開始使用

2.1 安裝需求

在安裝 Grails 之前，您需要安裝 Java 開發套件 (JDK)，其最低版本如下表所示。下載適用於您作業系統的 JDK，執行安裝程式，然後設定一個環境變數，稱為 JAVA_HOME，指向此安裝的位置。

Grails 版本

JDK 版本 (最低)

若要自動安裝 Grails，我們建議使用 SDKMAN，它可以大幅簡化安裝和管理多個 Grails 版本。

在某些平台上 (例如 macOS)，Java 安裝會自動偵測。但在許多情況下，您會想要手動設定 Java 的位置。例如，如果您使用 bash 或 Bourne Shell 的其他變體

export JAVA_HOME=/Library/Java/Home
export PATH="$PATH:$JAVA_HOME/bin"

在 Windows 上，您必須在 我的電腦/進階/環境變數 中設定這些環境變數

2.2 下載和安裝

開始使用 Grails 的第一步是安裝發行版。

在 *nix 系統上安裝 Grails 的最佳方式是使用 SDKMAN，它可以極大地簡化安裝和管理多個 Grails 版本。

使用 SDKMAN 安裝

若要使用 SDKMAN 安裝最新版本的 Grails，請在終端機上執行這項指令

$ sdk install grails

您也可以指定版本

$ sdk install grails 6.2.0

您可以在 SDKMAN 文件中找到有關 SDKMAN 使用的更多資訊

手動安裝

若要手動安裝，請按照下列步驟操作

下載 Grails 的二進位發行版，並將產生的 zip 檔案解壓縮到您選擇的位置
將 GRAILS_HOME 環境變數設定為您解壓縮 zip 檔案的位置

Unix/Linux

這通常是將類似下列內容 export GRAILS_HOME=/path/to/grails 加入您的設定檔
這可以透過將 export PATH="$PATH:$GRAILS_HOME/bin" 加入您的設定檔來完成

Windows

複製您已下載的 grails 資料夾內 bin 目錄的路徑，例如：

C:\path_to_grails\bin

前往環境變數，您通常可以搜尋或執行下列指令，輸入 env，然後按 Enter

Start + R

根據您的選擇，編輯使用者變數/系統變數中的路徑變數。
將複製的路徑貼到路徑變數中。

如果 Grails 正常運作，您現在應該可以在終端機視窗中輸入 grails --version，並看到類似下列內容的輸出

Grails Version: 6.2.0

2.3 建立應用程式

若要建立 Grails 應用程式，您首先需要熟悉 grails 指令的使用方式，其使用方式如下

$ grails <<command name>>

執行 create-app 以建立應用程式

$ grails create-app myapp

這將在目前目錄內建立一個包含專案的新目錄。在您的主控台中瀏覽至這個目錄

$ cd myapp

2.4 使用 Grails 建立簡單的 Web 應用程式

步驟 1：建立新專案

開啟您的命令提示字元或終端機。

瀏覽至您要建立 Grails 專案的目錄

$ cd your_project_directory

使用下列指令建立新的 Grails 專案

$ grails create-app myapp

步驟 2：存取專案目錄

切換至您剛才建立的「myapp」目錄

$ cd myapp

步驟 3：啟動 Grails 互動式主控台

透過執行「grails」指令啟動 Grails 互動式主控台

$ grails

步驟 4：建立控制器

在 Grails 互動式主控台中，您可以使用自動完成來建立控制器。輸入下列指令以建立名為「greeting」的控制器

grails> create-controller greeting

此指令將在 grails-app/controllers/myapp 目錄中產生一個名為「GreetingController.groovy」的新控制器。您可能會好奇為什麼會有額外的「myapp」目錄。這個結構符合 Java 開發中常用的慣例，其中類別會組織成套件。Grails 會自動將應用程式名稱包含在套件結構中。如果您未指定套件，Grails 預設會使用應用程式名稱。

如需建立控制器的更詳細資訊，您可以參閱建立控制器頁面上的文件。

步驟 5：編輯控制器

在文字編輯器中開啟位於「grails-app/controllers/myapp」目錄中的「GreetingController.groovy」檔案。

將下列程式碼加入「GreetingController.groovy」檔案

package myapp

class GreetingController {

    def index() {
        render "Hello, Congratulations for your first Grails application!"
    }
}

動作只是一個方法。在這個特定案例中，它呼叫 Grails 提供的特殊方法來呈現頁面。

步驟 6：執行應用程式

Grails 架構現在依賴 Gradle 任務來執行應用程式。若要啟動應用程式，請使用下列 Gradle bootRun 指令

$ ./gradlew bootRun

您的應用程式預設會在 8080 埠上執行。您可以在您的網路瀏覽器中透過以下網址存取它

https://127.0.0.1:8080/

現在，了解歡迎頁面是由下列 URL 對應決定的非常重要

class UrlMappings {
    static mappings = {
        "/$controller/$action?/$id?(.$format)?"{
            constraints {
                // apply constraints here
            }
        }

        "/"(view:"/index")
        "500"(view:'/error')
        "404"(view:'/notFound')
    }
}

這個對應指定根 URL（「/」）應顯示位於「grails-app/views/index.gsp」的「index.gsp」檢視。這個「index.gsp」檔案作為您的歡迎或登陸頁面。對應中的其他項目處理 HTTP 狀態碼 500 和 404 的錯誤頁面。

基於控制器和動作名稱的 Grails URL 約定

Grails 遵循依賴控制器及其動作名稱的 URL 約定。這個約定簡化了在您的網路應用程式中建立和存取各種頁面或功能。

在提供的程式碼範例中

package myapp

class GreetingController {

    def index() {
        render "Hello, Congratulations for your first Grails application!"
    }
}

GreetingController 類別代表 Grails 中的控制器。
在控制器內部，有一個定義為方法的 index 動作。在 Grails 中，動作本質上是控制器內部的方法，用於處理特定任務或回應使用者要求。

現在，讓我們了解 Grails URL 約定如何根據這個控制器和動作運作

URL 中的控制器名稱
- 控制器名稱，在本例中為「GreetingController」，用於 URL 中。不過，約定會將控制器名稱的第一個字母大寫，並移除「Controller」字尾。因此，「GreetingController」在 URL 中會變成「greeting」。
URL 中的動作名稱
- 預設情況下，如果您未在 URL 中指定動作，Grails 會假設「index」動作。因此，在本範例中，存取 URL /greeting

請參閱使用者指南的控制器和動作區段的結尾，以進一步了解預設動作。

選用：設定內容路徑

如果您想為應用程式設定內容路徑，請在「grails-app/conf/application.yml」檔案中建立組態屬性

server:
    servlet:
        context-path: /myapp

透過此組態，應用程式將會在下列位置提供

https://127.0.0.1:8080/myapp/

或者，您可以在使用 Gradle 執行 Grails 應用程式時，從命令列設定內容路徑。以下是執行方式

$ ./gradlew bootRun -Dgrails.server.servlet.context-path=/your-context-path

將 /your-context-path 取代為 Grails 應用程式所需的內容路徑。此命令會透過 -Dgrails.server.servlet.context-path 系統屬性，直接設定內容路徑。

例如，如果您希望應用程式在「https://127.0.0.1:8080/myapp」提供，可以使用下列命令

$ ./gradlew bootRun -Dgrails.server.servlet.context-path=/myapp

這讓您可以在不修改應用程式組態檔案的情況下，組態內容路徑，使其成為使用 Gradle 執行 Grails 應用程式時，一個彈性和便利的選項。

選用：變更伺服器連接埠

如果連接埠 8080 已在使用中，您可以使用 grails.server.port 系統屬性，在不同的連接埠上啟動伺服器

$ ./gradlew bootRun -Dgrails.server.port=9090

將「9090」替換為您偏好的連接埠。

Windows 使用者注意事項

如果您遇到與 Java 程序或檔案名稱長度相關的錯誤，可以使用 --stacktrace 旗標，或在「build.gradle」檔案中加入 grails { pathingJar = true }。

在 Windows 中，可能也需要將系統屬性置於引號中

./gradlew bootRun "-Dgrails.server.port=9090"

結論

現在，當您在網路瀏覽器中存取 Grails 應用程式時，它將會顯示「Hello, Congratulations on your first Grails application!」訊息。

請記住，您可以建立多個控制器和動作，以使用 Grails 建立更複雜的網路應用程式。每個動作都對應到不同的頁面，可透過根據控制器和動作名稱所產生的唯一網址存取。

2.5 使用互動模式

Grails 命令列介面 (CLI) 提供互動模式，您可以透過在終端機應用程式或 Linux 命令列中輸入「grails」來存取。

進入命令列介面後，您可以利用 TAB 鍵進行自動完成，以提升效率。例如

grails> create
create-app            create-plugin         create-webapp
create-controller     create-restapi
create-domain-class   create-web-plugin

此互動模式提供一種便利的方式，讓您可以探索可用的 Grails 命令和選項，讓您的 Grails 開發工作流程更有效率且更使用者友善。

如需瞭解互動模式功能的更多資訊，請參閱使用者指南中的互動模式區段。

2.6 在 IDE 中設定

由於 Grails 建立在 Spring Framework (Spring Boot)、Gradle 建置工具，以及 Groovy 程式語言上，因此可以使用最受歡迎的 JVM 整合開發環境 (IDE) 來開發 Grails 應用程式。有些 IDE 提供更專業的 Grails 支援，而其他 IDE 則可能提供管理相依關係/外掛程式、執行 Gradle 任務、程式碼完成和語法突顯等基本支援。

1. IntelliJ IDEA

IntelliJ IDEA 是廣泛用於 Grails 開發的 IDE。它提供對 Groovy 和 Grails 的全面支援，包括程式碼完成、智慧型程式碼分析和與 Grails 製成品的無縫整合等功能。

IntelliJ IDEA 還提供強大的資料庫工具，可與 Grails 的 GORM (Grails 物件關聯對應) 無縫運作。它提供社群版 (免費) 和終極版 (付費)，後者提供更進階的 Grails 支援，包括 Grails Forge 的嵌入式版本，以及 GSP 和 JSON 檢視的檢視解析度。

IntelliJ IDEA 網站

2. Visual Studio Code (VS Code)

Visual Studio Code 是由 Microsoft 開發的輕量級、開放原始碼程式碼編輯器。雖然它不是一個完整的 IDE，但它提供強大的 Grails 和 Groovy 開發擴充功能。您可以安裝 code-groovy 和 Grails for VS Code 等擴充功能，以提升您的 Grails 開發人員體驗。

VS Code 提供語法突顯、程式碼導覽和整合式終端機支援等功能。對於偏好輕量級且可自訂開發環境的開發人員來說，它是一個很棒的選擇。

Visual Studio Code (VS Code)

3. STS (Spring Tool Suite)

Spring Tool Suite (STS) 是一組專為 Spring Framework 開發設計的 IDE 工具，其版本基於 VS Code 和 Eclipse。本節重點介紹 Eclipse 版本。

STS 搭配 Groovy Development Tools 外掛程式 (可使用 Eclipse Marketplace 安裝) 使用時，可以成為一個有效的 Grails 開發人員平台。STS 不提供對 Grails 製成品或 GSP 檢視的特定支援。

Spring Tool Suite (STS)

4. Netbeans

Apache Netbeans 不提供對 Grails 的特定支援，但它會將 Grails 應用程式匯入為 Gradle 專案，並提供對 Groovy 和 GSP 檢視合理的編輯支援。

5. TextMate、VIM 等

有許多優秀的文字編輯器可與 Groovy 和 Grails 搭配使用。以下是部分參考資料

在 Textmate 中可使用套件來支援 Groovy/Grails。
可透過 Sublime Package Control 安裝外掛程式，以使用 Sublime Text Editor。
emacs-grails 擴充功能提供 Emacs 中 Grails 開發的基本支援。
請參閱這篇文章，以取得一些有用的提示，說明如何設定 VIM 作為您選擇的 Grails 編輯器。

這些文字編輯器，連同提供的擴充功能和組態，可以增強您的 Groovy 和 Grails 開發體驗，提供彈性和自訂功能，以符合您的程式設計偏好。

2.7 Grails 目錄結構和約定優先於組態

Grails 採用「約定優先於組態」方法來設定自身。在此方法中，使用檔案名稱和位置，而不是明確的組態。因此，熟悉 Grails 提供的目錄結構至關重要。以下是主要目錄的細目和相關區段連結

grails-app - Groovy 來源的頂層目錄
- conf - 組態來源
- controllers - Web 控制器 - 負責 MVC (Model-View-Controller) 中的「C」。
- domain - 應用程式網域 - 代表 MVC 中的「M」。
- i18n - 支援國際化 (i18n)。
- services - 服務層。
- taglib - 標籤庫。
- utils - 存放 Grails 特定的公用程式。
- views - Groovy Server Pages (GSP) 或 JSON Views - 負責 MVC 中的「V」。
- commands - 自訂 Grails 指令 - 建立您自己的 Grails CLI 指令。
src/main/groovy - 支援來源
src/test/groovy - 單元測試
src/integration-test/groovy - 整合測試 - 用於在整合層級測試 Grails 應用程式。

了解此目錄結構及其慣例是有效率的 Grails 開發的基礎。

2.8 執行和除錯應用程式

Grails 應用程式可以使用內建應用程式伺服器，使用 bootRun 指令執行。預設情況下，它會在 8080 埠上啟動伺服器

$ ./gradlew bootRun

若要指定不同的埠，你可以設定系統屬性 -Dgrails.server.port，如下所示

$ ./gradlew bootRun -Dgrails.server.port=8081

若要除錯 Grails 應用程式，你有兩個選項。你可以右鍵按一下 IDE 中的 Application.groovy 類別，然後選取適當的除錯動作，或者你可以使用下列指令執行應用程式，然後連線遠端除錯器

$ ./gradlew bootRun --debug-jvm

有關 bootRun 指令的更多資訊，請參閱 Grails 參考指南的 bootRun 區段。

2.9 測試應用程式

Grails 提供一個方便的功能，你可以使用 create-* 指令自動為你的應用程式產生單元和整合測試。這些產生的測試儲存在 src/test/groovy 和 src/integration-test/groovy 目錄中。但是，你必須自行填入這些測試適當的測試邏輯。你可以在專門用於單元和整合測試的區段中找到建立有效測試邏輯的全面指南。

若要開始執行你的測試，包括單元和整合測試，你可以使用 Gradle check 工作。請按照下列步驟操作

開啟你的終端機或命令提示字元，然後瀏覽到你的 Grails 專案的根目錄。
執行下列 Gradle 指令
```
$ ./gradlew check
```
透過執行 check 工作，你可以確保你的 Grails 專案中的所有測試，包括你建立並填入測試邏輯的測試，都會執行。這種全面的測試方法對你的應用程式的穩健性和整體品質有顯著的貢獻。
檢視測試報告：執行你的測試後，Grails 會產生測試報告，提供測試結果的寶貴見解。你通常可以在你的 Grails 專案的 build/reports/tests 目錄中找到這些報告。在網路瀏覽器中開啟這些報告，以檢視關於測試結果的詳細資訊，包括通過、失敗和略過的測試。

請記住，測試不只是一個流程；它是一種增強你的 Grails 應用程式可靠性的基本實務。檢視測試報告有助於你分析和了解測試結果，讓你可以更輕鬆地找出並解決任何問題。

透過遵循這些測試實務並檢閱測試報告，你可以自信地為你的使用者提供高品質的 Grails 應用程式。

2.10 部署應用程式

Grails 應用程式提供多種部署選項。

對於傳統的容器部署，例如 Tomcat 或 Jetty，您可以使用 Gradle war 任務來產生 Web 應用程式封存檔 (WAR) 檔案，如下所示

$ ./gradlew war

此任務會在 build/libs 目錄中產生一個附加檔名為 -plain 的 WAR 檔案，並準備好根據容器的指南進行部署。

預設情況下，war 任務會在 production 環境中執行。您可以透過在 Gradle 指令中覆寫它來指定不同的環境，例如 development

$ ./gradlew -Dgrails.env=dev war

如果您不想使用獨立的 Servlet 容器，您可以建立並執行 Grails WAR 檔案，就像執行一般的 Java 應用程式一樣

$ ./gradlew bootWar
$ java -jar build/libs/mywar-0.1.war

在部署 Grails 時，請確保容器的 JVM 使用 -server 選項執行，並分配足夠的記憶體。以下是建議的 VM 旗標

-server -Xmx1024M

2.11 支援的 Java EE 容器

Grails 架構要求執行時期容器支援 Servlet 3.0 以上版本。預設情況下，Grails 架構應用程式會與內嵌的 Tomcat 伺服器綑綁在一起。如需更多資訊，請參閱本文件中的部署部分。

此外，請閱讀 Grails 指南，以取得有關如何將 Grails 部署到各種熱門雲端服務的提示。

2.12 建立人工製品

Grails 提供一組有用的 CLI 指令，可執行各種任務，包括建立控制器和網域類別等必要的工件。這些指令簡化了開發流程，儘管您可以使用您偏好的整合開發環境 (IDE) 或文字編輯器來達成類似的結果。

例如，要建立應用程式的基礎，您通常需要使用 Grails 指令產生網域模型

$ grails create-app myapp
$ cd myapp
$ grails create-domain-class book

執行這些指令將會在 grails-app/domain/myapp/Book.groovy 中建立一個網域類別，如下列程式碼所示

package myapp

class Book {
}

Grails CLI 提供許多其他指令，您可以在 Grails 命令列參考指南中探索這些指令。

使用互動模式可透過提供自動完成功能並讓流程更順暢來增強開發體驗。

2.13 產生應用程式

使用 Grails Scaffolding 快速入門

要快速啟動您的 Grails 專案，您可以使用 runCommand Gradle 任務。此任務可讓您快速產生應用程式的必要結構。具體來說，在執行以下指令時，您可以為您的應用程式建立一個控制器（包括其單元測試）和相關的檢視

$ ./gradlew runCommand -Pargs="generate-all myapp.Book"

<< 1簡介

3從舊版本升級 >>

2 開始使用

目錄

2 開始使用

2.1 安裝需求

2.2 下載和安裝

使用 SDKMAN 安裝

手動安裝

Unix/Linux

Windows

2.3 建立應用程式

2.4 使用 Grails 建立簡單的 Web 應用程式

步驟 1：建立新專案

步驟 2：存取專案目錄

步驟 3：啟動 Grails 互動式主控台

步驟 4：建立控制器

步驟 5：編輯控制器

步驟 6：執行應用程式

選用：設定內容路徑

選用：變更伺服器連接埠

Windows 使用者注意事項

結論

2.5 使用互動模式

2.6 在 IDE 中設定

1. IntelliJ IDEA

2. Visual Studio Code (VS Code)

3. STS (Spring Tool Suite)

4. Netbeans

5. TextMate、VIM 等

2.7 Grails 目錄結構和約定優先於組態

2.8 執行和除錯應用程式

2.9 測試應用程式

2.10 部署應用程式

2.11 支援的 Java EE 容器

2.12 建立人工製品

2.13 產生應用程式

使用 Grails Scaffolding 快速入門

命令列

約束

控制器

資料庫對應

相依性版本

網域名稱類別

外掛程式

服務

Servlet API