Apache Grails 配置参数详解

Apache Grails 的配置层构建在 Spring Boot 的配置机制之上，核心配置文件位于 grails-app/conf/application.yml（也可使用 application.groovy）。本文系统梳理 Grails 6.x 的常用配置项，示例账号统一为 root / q1w2e3r4。

一、配置体系概览

1.1 配置文件位置与优先级

Grails 应用默认读取以下几个位置（后者覆盖前者）：

顺序	位置	说明
1	`application.yml` / `application.groovy`	主配置，`grails-app/conf/` 下
2	环境变量 / JVM 系统属性	如 `SERVER_PORT`、`-Dserver.port=`
3	命令行参数	`--server.port=9090`
4	外部配置	`--spring.config.location=` 指定的文件

grails-app/conf/application.yml 默认包含三个 YAML 文档段（以 --- 分隔）：基础段、MIME/URL 映射段、数据源段。

1.2 application.groovy 等价写法

若偏好 Groovy DSL，可改用 grails-app/conf/application.groovy：

server.port = 8090

dataSource {
    pooled = true
    driverClassName = 'org.h2.Driver'
    username = 'sa'
    password = ''
}

application.yml 与 application.groovy 内容等价，二选一即可，同时存在时以 .groovy 为准。

二、服务器与运行配置

2.1 监听端口 server.port

默认端口为 8080，可在 application.yml 中显式指定：

server:
    port: 8090

也可通过环境变量覆盖，便于多实例部署：

SERVER_PORT=9090 grails run-app

2.2 上下文路径与地址

server:
    port: 8080
    address: 0.0.0.0
    servlet:
        context-path: /myapp

2.3 内嵌 Tomcat 参数

server:
    tomcat:
        max-threads: 200
        min-spare-threads: 10
        max-connections: 8192
        uri-encoding: UTF-8

2.4 JVM 堆内存

运行应用时建议将堆内存限定在 256–512MB（规范区间）：

export JAVA_OPTS="-Xmx512m -Xms256m"
grails run-app

三、数据源配置 dataSource

3.1 通用属性

dataSource:
    pooled: true                 # 使用连接池
    jmxExport: true
    driverClassName: org.h2.Driver
    username: sa
    password: ''

3.2 H2 内存数据库（开发默认）

environments:
    development:
        dataSource:
            dbCreate: create-drop
            url: jdbc:h2:mem:devDb;LOCK_TIMEOUT=10000;DB_CLOSE_ON_EXIT=FALSE

dbCreate 取值含义：

取值	行为
`create-drop`	启动建表、关闭删表（开发默认）
`update`	增量更新表结构（测试默认）
`create`	每次启动重建表结构
`none`	不做任何 DDL（生产默认）

3.3 MySQL 数据源（生产推荐）

dataSource:
    pooled: true
    driverClassName: com.mysql.cj.jdbc.Driver
    dialect: org.hibernate.dialect.MySQL8Dialect
    username: 'grails'
    password: 'q1w2e3r4'
    properties:
        initialSize: 5
        maxActive: 50
        minIdle: 5
        maxWait: 10000
        validationQuery: SELECT 1
        testOnBorrow: true
        testWhileIdle: true

environments:
    production:
        dataSource:
            dbCreate: none
            url: jdbc:mysql://127.0.0.1:3306/grailsdb?useUnicode=true&characterEncoding=UTF-8&serverTimezone=Asia/Shanghai

对应的 JDBC 驱动依赖需在 build.gradle 中声明：

runtimeOnly 'mysql:mysql-connector-java:8.0.33'

3.4 多数据源

dataSource 下的名字即数据源逻辑名，可使用 dataSource_xxx 声明多个：

dataSource_secondary:
    pooled: true
    driverClassName: org.h2.Driver
    url: jdbc:h2:mem:secondDb

四、多环境配置 environments

4.1 内置环境

Grails 内置三个环境：development（开发）、test（测试）、production（生产）。默认使用 development。

4.2 环境切换

命令行指定：

grails prod run-app
grails test run-app

或在 application.yml 中设置：

grails:
    env: production

4.3 按环境覆盖配置

environments:
    development:
        server:
            port: 8080
        dataSource:
            dbCreate: create-drop
    test:
        dataSource:
            dbCreate: update
    production:
        server:
            port: 80
        dataSource:
            dbCreate: none

五、控制器与 URL 映射

5.1 控制器默认作用域

grails:
    controllers:
        defaultScope: singleton

defaultScope 取值 singleton（默认，单例，性能更好）或 prototype（每次请求新实例）。

5.2 URL 映射缓存

grails:
    urlmapping:
        cache:
            maxsize: 1000

5.3 MIME 类型

application.yml 第二段默认定义了大量 MIME 映射，例如：

grails:
    mime:
        types:
            json:
              - application/json
              - text/json
            html:
              - text/html
              - application/xhtml+xml
            xml:
              - text/xml
              - application/xml

用于内容协商，例如 /hello/index.json 会以 JSON 响应。

六、GORM 配置

6.1 Hibernate 二级缓存

hibernate:
    cache:
        queries: false
        use_second_level_cache: false
        use_query_cache: false

6.2 GORM Reactor 事件

grails:
    gorm:
        reactor:
            events: false   # 默认关闭以提升性能，需要时开启

6.3 域类级映射

除全局配置外，域类内可声明映射：

class Book {
    String title
    static mapping = {
        table 'book_tbl'
        title column: 'book_title'
        cache true
    }
    static constraints = {
        title blank: false, maxSize: 255
    }
}

七、日志配置 logback

Grails 6.x 默认使用 grails-app/conf/logback.xml（也可用 logback.groovy）。示例：

<configuration>
    <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
        </encoder>
    </appender>

    <logger name="org.hibernate" level="warn"/>
    <logger name="org.springframework" level="info"/>
    <root level="info">
        <appender-ref ref="STDOUT"/>
    </root>
</configuration>

等价 Groovy DSL（logback.groovy）：

appender('STDOUT', ConsoleAppender) {
    encoder(PatternLayoutEncoder) { pattern = '%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n' }
}
root(INFO, ['STDOUT'])

八、静态资源与 Profile

8.1 静态资源目录

Grails 约定静态资源位于 grails-app/assets/，由 Asset Pipeline 处理，默认访问路径为 /assets/**：

grails-app/assets/
├── images/
├── javascripts/
├── stylesheets/
└── favicon.ico

模板中引用：

<link rel="stylesheet" href="${assetPath(src: 'main.css')}"/>

8.2 Profile（应用画像）

application.yml 中的 grails.profile 决定工程形态：

grails:
    profile: web

常见 profile：web（Web 应用，含 GORM Hibernate）、rest-api（REST 服务）、plugin（插件）。profile 在 create-app 时通过 --profile 指定：

grails create-app myservice --profile=rest-api

8.3 视图与编解码

grails:
    views:
        default:
            codec: html
        gsp:
            encoding: UTF-8
            htmlcodec: xml
            codecs:
                expression: html
                scriptlet: html
                taglib: none
                staticparts: none
    converters:
        encoding: UTF-8

九、Spring Boot 相关配置

Grails 直接复用 Spring Boot 配置项：

spring:
    jmx:
        unique-names: true
    main:
        banner-mode: "off"
    devtools:
        restart:
            additional-exclude:
                - '*.gsp'
                - '**/*.gson'
info:
    app:
        name: demoapp
        version: 0.1

十、常见问题

Q1：改了 application.yml 需要重启吗？ 开发模式下 Grails 有热重载机制，但配置变更（尤其数据源）建议重启 run-app 以确保生效。

Q2：生产环境 dbCreate 设什么？ 生产应设为 none，由数据库迁移工具（如 Liquibase/Flyway）管理表结构。

Q3：如何为不同环境注入不同密钥？ 推荐使用环境变量或外部配置文件，避免将生产密码写入 application.yml。

Q4：server.port、SERVER_PORT 冲突时以谁为准？ 环境变量优先级高于 application.yml 中的同名配置项。