Apache Grails 常用 CLI 命令与工具详解

Apache Grails 通过 grails 命令提供统一的脚手架与构建入口，底层驱动 Gradle。本文系统整理 Grails 6.x 的常用命令、真实回显与 Gradle 包装命令。示例登录账号为 root / q1w2e3r4。

一、CLI 概览

1.1 命令语法

grails [environment]* [target] [arguments]*

environment：可选环境（dev / test / prod），缺省为 dev。
target：命令名，如 run-app、create-app。
arguments：命令参数。

示例：

grails dev run-app
grails create-app books

1.2 查看帮助

grails help                     # 列出全部命令
grails help run-app             # 查看某命令用法

grails help 实测输出节选：

| Available Commands (type grails help 'command-name' for more info):
| Command Name                          Command Description
----------------------------------------------------------------------------------------------------
assemble                                Creates a JAR or WAR archive for production deployment
clean                                   Cleans a Grails application's compiled sources
compile                                 Compiles a Grails application
console                                 Runs the Grails interactive console
create-app                              Creates an application
create-controller                       Creates a controller
create-domain-class                     Creates a Domain Class
generate-all                            Generates a controller that performs CRUD operations and the associated views
run-app                                 Runs a Grails application
stop-app                                Stops the running Grails application
test-app                                Runs the applications tests
stats                                   Prints statistics about the project
...

二、工程创建类命令

2.1 create-app

创建应用骨架：

grails create-app demoapp

实测回显：

| Application created at /root/grails-lab/demoapp

指定 profile 与包名：

grails create-app myservice --profile=rest-api --group=com.example

--profile 可用值包括 web（默认）、rest-api、plugin。

2.2 create-plugin

创建可复用插件工程：

grails create-plugin myplugin

2.3 create-command / create-script

grails create-command my-command     # 创建应用命令
grails create-script my-script       # 创建 Grails 脚本

三、代码生成类命令

3.1 create-controller

grails create-controller Hello

实测回显：

| Created grails-app/controllers/demoapp/HelloController.groovy
| Created src/test/groovy/demoapp/HelloControllerSpec.groovy

3.2 create-domain-class

grails create-domain-class demoapp.Book

实测回显：

| Created grails-app/domain/demoapp/Book.groovy
| Created src/test/groovy/demoapp/BookSpec.groovy

3.3 create-service / create-interceptor / create-taglib

grails create-service Book
grails create-interceptor Auth
grails create-taglib MyTagLib

3.4 generate-all / generate-controller / generate-views

为域类生成 CRUD 控制器与视图：

grails generate-all demoapp.Book

实测回显节选：

| Scaffolding completed for grails-app/domain/demoapp/Book.groovy
| Rendered template index.gsp to destination grails-app/views/book/index.gsp
| Rendered template create.gsp to destination grails-app/views/book/create.gsp
| Views generated for grails-app/domain/demoapp/Book.groovy

也可仅生成控制器或视图：

grails generate-controller Book
grails generate-views Book

3.5 测试脚手架

grails create-unit-test Book
grails create-integration-test Book
grails create-functional-test Book

四、运行与调试类命令

4.1 run-app

启动应用（内嵌 Tomcat）：

export JAVA_OPTS="-Xmx512m"     # JVM 堆限制在 256–512MB 规范内
grails run-app

实测回显：

Grails application running at http://localhost:8080 in environment: development

指定环境与端口：

grails prod run-app
SERVER_PORT=9090 grails run-app

4.2 stop-app

grails stop-app

实测回显：

| Shutting down application...
| {"message":"Shutting down, bye..."}
| Application shutdown.

4.3 console / shell

进入交互式控制台，可执行 Grails 命令与 Groovy 脚本：

grails console
grails shell

4.4 run-script / run-command

grails run-script src/scripts/task.groovy
grails run-command create-domain-class demoapp.Author

五、构建与打包类命令

5.1 assemble（等价于打包 WAR/JAR）

grails assemble

产物位于 build/libs/ 下。Grails 6.x 不提供 war 命令，打包统一由 assemble 完成。

5.2 compile / clean

grails compile      # 编译应用
grails clean        # 清理编译产物

5.3 生产构建常用组合

grails clean && grails assemble

构建后的归档可直接用 java -jar 运行：

java -Xmx512m -jar build/libs/demoapp-0.1.jar

六、测试类命令

6.1 test-app

运行单元测试与集成测试：

grails test-app

限定测试类或类型：

grails test-app BookControllerSpec
grails test-app --unit
grails test-app --integration

6.2 dependency-report

打印依赖树，排查版本冲突：

grails dependency-report

七、信息与统计类命令

7.1 stats

grails stats

实测回显：

+----------------------+-------+-------+
| Name                 | Files |  LOC  |
+----------------------+-------+-------+
| Controllers          |     2 |    88 |
| URL Mappings         |     1 |    12 |
| Domain Classes       |     1 |     5 |
| Services             |     1 |    10 |
+----------------------+-------+-------+
| Totals               |     9 |   365 |
+----------------------+-------+-------+

7.2 url-mappings-report

查看应用 URL 路由：

grails url-mappings-report

7.3 其他诊断命令

grails plugin-info <plugin>     # 查看插件信息
grails list-plugins             # 列出仓库插件
grails bug-report               # 生成问题报告压缩包
grails schema-export            # 导出数据库 DDL

八、Gradle 包装命令（./gradlew）

grails 命令底层即 Gradle。工程自带 Gradle Wrapper，可直接使用 ./gradlew：

Grails 命令	等价 Gradle 命令
`grails run-app`	`./gradlew bootRun`
`grails test-app`	`./gradlew test`
`grails compile`	`./gradlew classes`
`grails clean`	`./gradlew clean`
`grails assemble`	`./gradlew assemble` 或 `./gradlew bootWar`
`grails console`	`./gradlew console`

示例：

./gradlew clean bootRun
./gradlew clean bootWar
./gradlew test --tests "demoapp.BookControllerSpec"

也可透传 Gradle 任务：

grails gradle tasks
grails gradle dependencies

九、常用命令速查表

命令	用途	典型用法
`create-app`	创建应用	`grails create-app demoapp`
`create-controller`	创建控制器	`grails create-controller Hello`
`create-domain-class`	创建域类	`grails create-domain-class Book`
`create-service`	创建服务	`grails create-service Book`
`generate-all`	生成 CRUD 控制器与视图	`grails generate-all Book`
`run-app`	启动应用	`grails run-app`
`stop-app`	停止应用	`grails stop-app`
`test-app`	运行测试	`grails test-app`
`assemble`	打包 JAR/WAR	`grails assemble`
`clean`	清理产物	`grails clean`
`compile`	编译	`grails compile`
`console`	交互式控制台	`grails console`
`stats`	工程统计	`grails stats`
`help`	查看帮助	`grails help run-app`

十、常见问题

Q1：grails 与 ./gradlew 有什么区别？ grails 是封装后的高层入口，语义更贴近框架；./gradlew 直接驱动构建，适合 CI 与自定义任务。两者底层一致。

Q2：为什么执行 grails war 报未知命令？ Grails 6.x 已移除 war 命令，使用 grails assemble 或 ./gradlew bootWar 打包。

Q3：首次执行命令很慢？ 首次运行需下载 Gradle 发行包（约 100MB+）与依赖，属正常现象；后续使用本地缓存会显著加快。

Q4：如何在 CI 中非交互运行？ 使用 ./gradlew --no-daemon 并配合 grails 的相应目标，避免守护进程与交互等待。