(快速参考)

6 应用程序概要文件

版本 4.1.3

6 应用程序概要文件

使用 create-app 命令创建 Grails 应用程序时，默认使用“web”概要文件

grails create-app myapp

你可以使用 profile 参数指定不同的概要文件

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

概要文件封装了为指定概要文件设计而成的项目命令、模板和插件。可以在 Github 上找到概要文件的源，而概要文件本身以 JAR 文件的形式发布到 Grails 中央存储库。

要了解可用的概要文件，请使用 list-profiles 命令

$ grails list-profiles

有关特定概要文件的详细信息，请使用 profile-info 命令

$ grails profile-info rest-api

在 grails 项目中调用 Grails CLI 时，无法使用 profile-info 或 list-profiles 等命令。

概要文件存储库

默认情况下，Grails 会从 Grails 中央存储库中解析概要文件。但是，可以通过在 USER_HOME/.grails/settings.groovy 文件中指定存储库覆盖搜索的内容。

如果你希望用自定义存储库除了 Grails 中央存储库外解析概要文件，你必须在文件中指定 Grails 中央存储库

grails {
  profiles {
    repositories {
      myRepo {
        url = "http://foo.com/repo"
        snapshotsEnabled = true
      }
      grailsCentral {
        url = "https://repo.grails.org/grails/core"
        snapshotsEnabled = true
      }
    }
  }
}

Grails 使用 Aether 解析概要文件，因为在执行 `create-app` 命令时还没有 Gradle 实例可用。这意味着，如果需要，你也可以在 `USER_HOME/.m2/settings.xml` 文件中定义存储库和更高级配置（代理、身份验证等）。

也可以将概要文件存储库的简单证书直接存储在 `USER_HOME/.grails/settings.groovy` 文件中。

grails {
  profiles {
    repositories {
      myRepo {
        url = "http://foo.com/repo"
        snapshotsEnabled = true
        username = "user"
        password = "pass"
      }
      ...
    }
  }
}

概要文件默认设置

要创建使用自定义概要文件的应用程序，必须指定完整的项目符号。

$ grails create-app myapp --profile=com.mycompany.grails.profiles:myprofile:1.0.0

为了简化此过程，你可以在 `USER_HOME/.grails/settings.groovy` 文件中为给定概要文件定义默认设置。

grails {
  profiles {
    myprofile {
      groupId = "com.mycompany.grails.profiles"
      version = "1.0.0"
    }
    repositories {
      ...
    }
  }
}

通过指定默认值，使用该概要文件创建应用程序的命令变为

$ grails create-app myapp --profile=myprofile

6.1 创建概要文件

创建新概要文件的思路是，可以针对特定技术或组织设置一组默认命令和插件。

要创建新概要文件，可以使用 create-profile 命令，它将创建一个新的空概要文件，扩展基本概要文件

$ grails create-profile mycompany

以上命令将在执行命令的“mycompany”目录中创建一个新概要文件。如果你在目录内启动交互模式，将会得到用于创建概要文件的一组命令

$ cd mycompany
$ grails
| Enter a command name to run. Use TAB for completion:
grails>

create-command      create-creator-command      create-feature      create-generator-command    create-gradle-command   create-template

如下所示

create-command - 创建一条新的命令，当使用概要文件时，该命令将可用于 Grails CLI
create-creator-command - 创建可用于 CLI 的命令，该命令呈现模板（示例：create-controller）
create-generator-command - 创建可用于 CLI 的命令，该命令基于域类呈现模板（示例：generate-controller）
create-feature - 创建可与该概要文件一起使用的功能
create-gradle-command - 创建可调用 gradle 的 CLI 命令
create-template - 创建可由命令呈现的模板

要自定义概要文件的依赖项，可以在 `profile.yml` 中指定其他依赖项。

以下是示例 `profile.yml` 文件

features:
    defaults:
        - hibernate
        - asset-pipeline
build:
    plugins:
        - org.grails.grails-web
    excludes:
        - org.grails.grails-core
dependencies:
    compile:
        - "org.mycompany:myplugin:1.0.1"

通过采用以上配置，可以使用 `gradle install` 将概要文件发布到本地存储库。

$ gradle install

你现在可以使用 `create-app` 命令使用概要文件了

$ grails create-app myapp --profile mycompany

使用以上命令时，将使用“mycompany”概要文件创建该应用程序，该概要文件包括对“myplugin”插件的另一个依赖项，还包含“hibernate”和“asset-pipeline”功能（稍后将详细介绍功能）。

请注意，如果你自定义概要文件（组、版本等）的依赖项坐标，则可能需要使用完全限定的坐标来创建应用程序

$ grails create-app myapp --profile com.mycompany:mycompany:1.0.1

6.2 概要文件继承

一个配置文件可扩展一个或多个不同的父配置文件。若要定义配置文件继承，可修改配置文件的 build.gradle 并定义配置文件依赖项。例如，您通常希望扩展 base 配置文件

dependencies {
    runtime "org.grails.profiles:base:$baseProfileVersion"
}

从父配置文件继承会给您带来以下好处

执行 create-app 命令时，将首先复制父配置文件的框架
从父项合并依赖项和 build.gradle
从父项合并 application.yml 文件
继承来自父配置文件的 CLI 命令
继承来自父配置文件的功能

若要定义继承顺序，请确保以正确的顺序声明您的依赖项。例如

dependencies {
    runtime "org.grails.profiles:plugin:$baseProfileVersion"
    runtime "org.grails.profiles:web:$baseProfileVersion"
}

在以上代码段中，“plugin”配置文件的框架首先被复制，然后是 “web”配置文件。此外，“web”配置文件覆盖了 “plugin”配置文件中的命令，而如果依赖项顺序颠倒，“plugin”配置文件将覆盖“web”配置文件。

6.3 发布配置文件

将配置文件发布到 Grails 中央仓库

使用 create-profile 命令创建的任何配置文件都已使用 build.gradle 中定义的 grails-profile-publish 插件进行了配置

apply plugin: "org.grails.grails-profile-publish"

若要将配置文件使用此插件发布到 Grails 中央仓库，首先将源上传到 Github（不会接受闭源配置文件）。然后在 Bintray 上注册一个帐户，并在配置文件的 build.gradle 文件中按如下所示配置您的密钥

grailsPublish {
  user = 'YOUR USERNAME'
  key = 'YOUR KEY'
  githubSlug = 'your-repo/your-profile'
  license = 'Apache-2.0'
}

githubSlug 参数应指向您的 Github 储存库的路径。例如，如果您的储存库位于 https://github.com/foo/bar，那么您的 githubSlug 为 foo/bar

这样，您可以运行 gradle publishProfile 来发布您的配置文件

$ gradle publishProfile

该配置文件将上传到 Bintray。然后，您可以进入 Grails 配置文件储存库，并通过点击 Bintray 界面上的“包含我的软件包”按钮来请求包含您的配置文件（您必须登录才能看到此内容）。

将配置文件发布到内部储存库

前面提到的 grails-profile-publish 插件配置了 Gradle 的 Maven Publish 插件。为发布到内部储存库，您需要做的就是定义 build.gradle 中的储存库。例如

publishing {
    repositories {
        maven {
            credentials {
                username "foo"
                password "bar"
            }

            url "http://foo.com/repo"
        }
    }
}

配置后，您可以使用 gradle publish 发布您的插件

$ gradle publish

6.4 了解配置文件

配置文件是一个简单的目录，其中包含 profile.yml 文件，以及由该配置文件定义的包含“命令”、“框架”和“模板”的目录。示例

/web
    commands/
        create-controller.yml
        run-app.groovy
        ...
    features/
        asset-pipeline/
            skeleton
            feature.yml
    skeleton/
        grails-app/
            controllers/
            ...
        build.gradle
    templates/
        artifacts/
            Controller.groovy
    profile.yml

上面的示例是“web”配置文件结构的片段。profile.yml 文件用来描述该配置文件，并控制构建的配置方式。

了解 profile.yml 描述符

profile.yml 可以包含以下子元素。

1) 存储库

准备包含在构建中的 Maven 存储库列表。示例

repositories:
    - "https://repo.grails.org/grails/core"

2) build.repositories

准备包含在生成构建的构建脚本部分中的 Maven 存储库列表。示例

build:
    repositories:
        - "https://repo.grails.org/grails/core"

3) build.plugins

准备在生成的构建中配置的 Gradle 插件列表。示例

build:
    plugins:
        - eclipse
        - idea
        - org.grails.grails-core

4) build.excludes

准备从父配置文件中排除的 Gradle 插件列表

build:
    excludes:
        - org.grails.grails-core

5) 依赖项

准备配置的范围和依赖项映射。excludes 范围可以用来从父配置文件中排除。示例

dependencies:
    excludes:
        - "org.grails:hibernate:*"
    build:
        - "org.grails:grails-gradle-plugin:$grailsVersion"
    compile:
        - "org.springframework.boot:spring-boot-starter-logging"
        - "org.springframework.boot:spring-boot-autoconfigure"

6) features.defaults

如果没有指定显式功能，准备的默认功能列表。

features:
    defaults:
        - hibernate
        - asset-pipeline

7) skeleton.excludes

准备从父配置文件的框架中排除的文件列表（支持通配符）。

skeleton:
    excludes:
        - gradlew
        - gradlew.bat
        - gradle/

8) skeleton.parent.target

父配置文件的框架要复制到的目标文件夹。这可以用来创建多项目构建。

skeleton:
    parent:
        target: app

9) skeleton.binaryExtensions

哪些文件扩展名要从配置文件复制为二进制文件。从父配置文件继承和组合。

skeleton:
    binaryExtensions: [exe, zip]

10) skeleton.executable

准备在生成的应用程序中标记为可执行的文件模式。从父配置文件继承和组合。这些模式用 Ant 进行解析。

skeleton:
    executable:
      - "**/gradlew*"
      - "**/grailsw*"

11) 说明

在创建应用程序后向用户显示的文本

instructions: Here are some instructions

使用配置文件后会发生什么？

当运行 create-app 命令时，它将采用父配置文件的框架并将框架复制到新的项目结构中。

生成的 build.gradle 文件是通过获取 profile.yml 文件中定义的所有依赖项信息并生成所需的依赖项而得到的。

此外，此命令还会合并配置文件及其父配置文件中定义的所有 build.gradle 文件。

grails-app/conf/application.yml 文件也将合并到单个 YAML 文件中，该文件将考虑配置文件和所有父配置文件。

6.5 创建配置文件命令

配置文件可以使用 YAML 或 Groovy 脚本定义仅适用于该配置文件的新命令。下面显示的是用 YAML 定义的 create-controller 命令示例

description:
    - Creates a controller
    - usage: 'create-controller <<controller name>>'
    - completer: org.grails.cli.interactive.completers.DomainClassCompleter
    - argument: "Controller Name"
      description: "The name of the controller"
steps:
 - command: render
   template: templates/artifacts/Controller.groovy
   destination: grails-app/controllers/`artifact.package.path`/`artifact.name`Controller.groovy
 - command: render
   template: templates/testing/Controller.groovy
   destination: src/test/groovy/`artifact.package.path`/`artifact.name`ControllerSpec.groovy
 - command: mkdir
   location: grails-app/views/`artifact.propertyName`

用 YAML 定义的命令必须定义一个或多个步骤。每个步骤本身都是一个命令。可用的步骤类型包括

render - 将模板渲染到给定的目标（如在前一示例中所示）
mkdir - 创建由 location 参数指定的一个目录
execute - 执行由 class 参数指定的命令。该命令必须为一个实现了 Command 接口的类。
gradle - 执行由 tasks 参数指定的某个或多个 Gradle 任务。

例如，若要调用一个 Gradle 任务，你可以定义以下 YAML

description: Creates a WAR file for deployment to a container (like Tomcat)
minArguments: 0
usage: |
 war
steps:
 - command: gradle
   tasks:
     - war

如果你需要比声明性 YAML 方法更好的灵活性，你可以创建 Groovy 脚本命令。每个命令脚本均从 GroovyScriptCommand 类扩展，因此可用该类中的所有方法。

以下是用 Groovy 编写的 create-script 的一个示例

description( "Creates a Grails script" ) {
  usage "grails create-script <<SCRIPT NAME>>"
  argument name:'Script Name', description:"The name of the script to create"
  flag name:'force', description:"Whether to overwrite existing files"
}

def scriptName = args[0]
def model = model(scriptName)
def overwrite = flag('force') ? true : false

render  template: template('artifacts/Script.groovy'),
        destination: file("src/main/scripts/${model.lowerCaseName}.groovy"),
        model: model,
        overwrite: overwrite

有关创建 CLI 命令的更多信息，请参阅用户指南中命令行部分中有关创建自定义脚本的部分。

6.6 创建配置文件功能

配置文件功能是一组可共享的模板和依赖项集合，它可能跨越多个配置文件。通常，你创建一个具有多个功能的基础配置文件和从父级继承的子配置文件，因此子配置文件可以使用父级提供的功能。

要在配置文件的根目录中使用 create-feature 命令创建一个功能

$ grails create-feature myfeature

这将创建一个 myfeature/feature.yml 文件，如下所示

description: Description of the feature
# customize versions here
# dependencies:
#   compile:
#     - "org.grails.plugins:myplugin2:1.0"
#

一个更具体的示例。以下是从“asset-pipeline”功能中提取的 feature.yml 文件

description: Adds Asset Pipeline to a Grails project
build:
    plugins:
        - asset-pipeline
dependencies:
    build:
        - 'com.bertramlabs.plugins:asset-pipeline-gradle:2.5.0'
    runtime:
        - "org.grails.plugins:asset-pipeline"

一个功能的结构如下

FEATURE_DIR
    feature.yml
    skeleton/
        grails-app/
            conf/
                application.yml
        build.gradle

框架内容会被复制到应用程序树中，而 application.yml 和 build.gradle 会与其在配置文件中的对应者合并，通过使用。

使用 feature.yml，你可以定义其他依赖项。这使用户可以用可选功能创建应用程序。例如

$ grails create-app myapp --profile myprofile --features myfeature,hibernate

上述示例将使用你的新功能和“hibernate”功能创建一个新应用程序。

<< 5命令行

7对象关系映射 (GORM) >>

6 应用程序概要文件

目录

6 应用程序概要文件

概要文件存储库

概要文件默认设置

6.1 创建概要文件

6.2 概要文件继承

6.3 发布配置文件

将配置文件发布到 Grails 中央仓库

将配置文件发布到内部储存库

6.4 了解配置文件

了解 profile.yml 描述符

1) 存储库

2) build.repositories

3) build.plugins

4) build.excludes

5) 依赖项

6) features.defaults

7) skeleton.excludes

8) skeleton.parent.target

9) skeleton.binaryExtensions

10) skeleton.executable

11) 说明

使用配置文件后会发生什么？

6.5 创建配置文件命令

6.6 创建配置文件功能

命令行

约束

控制器

数据库映射

领域类

插件

服务

Servlet API