Roles

角色提供了一种方法，可以使用户在用户定义命令中组织和复用变量。

Roles provide a way to organize and reuse variables across user-defined commands.

Spring CLI 默认包含一个匿名的角色，该角色始终可用。如果没有指定特定角色，命令将使用默认角色。

By default, the Spring CLI includes an unnamed role that is always available. If no specific role is specified, commands use the default role.

要进一步自定义和区分角色，您可以将它们与特定名称关联。这些命名角色作为 YAML 文件储存在 .spring/roles 目录中，该目录位于 .spring/commands 目录旁边。

To further customize and differentiate roles, you can associate them with specific names. These named roles are stored as YAML files within the .spring/roles directory, located alongside the .spring/commands directory.

角色允许您定义可通过使用 Handlebars 在操作文件中访问的变量，从而允许您在命令之间共享数据。

Roles let you define variables that can be accessed in an action file by using Handlebars, letting you share data between commands.

此外，您可以使用角色为命令行选项提供值。如果命令行选项未指定值，且存在与命令选项同名的角色变量，则该命令将自动为该特定选项使用角色变量的值。

Furthermore, you can use roles to supply values for command line options. If a command line option does not have a specified value and a role variable with the same name as the command option exists, the command automatically uses the value of the role variable for that specific option.

File Structure

对于每个角色，将在 .spring/roles/vars 目录中创建对应的文件。例如，如果存在 qa 和 prod 角色，则该目录将如下所示：

For each role, a corresponding file is created in the .spring/roles/vars directory. For example, if there is a qa and prod role, the directory would look like the following:

$ tree .spring/roles/vars -lr
.spring/roles/vars
├── vars.yml
├── vars-qa.yml
└── vars-prod.yml

vars.yml 文件用于默认角色。

The vars.yml file is used for the default role.

此结构遵循使用特定于 Spring 的应用配置文件的相似模式。然而，角色变量与 Spring 配置文件并不具有相同的行为，例如除文件外还可以从其他位置（例如环境变量）检索值。

This structure follows a similar pattern to using profile-specific Spring application configuration files. However, role variables do not exhibit the same behavior as Spring profiles, such as retrieving values from other locations in addition to the file (such as environment variables).

Quick Start

在此快速开始中，我们将展示如何将变量添加到默认角色，以及在生成文件时使用这些变量的值。

In this quick start, we demonstrate how to add variables to the default role and use their values when generating a file.

首先，我们将角色变量 'greeting' 的值设置为 'Mondo':

Let’s begin by setting the value of the role variable 'greeting' to 'Mondo':

$ spring role set --key greeting --value Mondo
Key-value pair added to the default role

键值对储存在根项目目录下的 ./spring/roles/vars/vars.yml 文件中。

The key-value pair is stored in the ./spring/roles/vars/vars.yml file under the root project directory.

要检索变量的值，请使用以下命令：

To retrieve the value of the variable, use the following command:

$ spring role get --key greeting
Mondo

现在，我们创建另一个角色变量：

Now we create another role variable:

$ spring role set --key language --value Italian
Key-value pair added to the default role

现在，我们可以将这些变量纳入到用户定义命令中。我们创建一个名为 hello say 的用户定义命令：

Now we can incorporate these variables into a user-defined command. We create a user-defined command named hello say:

$ spring command new --command-name hello --sub-command-name say
Created user defined command /home/mark/testing-spring-cli/roles/myapp/.spring/commands/hello/say

在 .spring/commands/hello/say 目录中，您可以找到一个名为 command.yaml 的文件，它具有以下内容：

Inside the .spring/commands/hello/say directory, you can find a file named command.yaml that has the following contents:

command:
  description: Generate a new file with a hello message
  options:
    #
    - name: greeting
      description: who or what to say hello to
      dataType: string
      defaultValue: World
      inputType: text

请注意，命令行选项名称是 greeting，这与我们创建的角色变量的名称相匹配。

Note that the command line option name is greeting, which matches the name of the role variable we created.

在 .spring/commands/hello/say 目录中，有一个名为 hello.yaml 的操作文件，其内容如下：

Within the .spring/commands/hello/say directory, there is an action file named hello.yaml with the following contents:

actions:
  - generate:
      to: hello.txt
      text: Hello {{greeting}} on {{os-name}}.

现在，我们更新文件以包含：

Now we update the file to include:

actions:
  - generate:
      to: hello.txt
      text: Hello {{greeting}} on {{os-name}}. {{#if language}} {{language}} {{/if}}

在不传递 greeting 命令行选项运行命令时，greeting 的值将由同名的角色变量获取，而不是使用默认值 World。

When running the command without passing the greeting command-line option, the value of greeting is obtained from the role variable with the same name instead of using the default value of World.

此外，由于我们已经定义了角色变量语言，所以我们可以测试它的存在并将它的值包括在输出中。请注意，语言不是命令行选项。以下命令（显示附带的输出）进行了该操作：

Additionally, since we have defined the role variable language, we can test its existence and include its value in the output. Note that language is not a command line option. The following command (show with its output) does so:

$ spring hello say
Using Role variable instead of default command line option for key = greeting , value = Mondo from the default role
Generated /home/mark/testing-spring-cli/roles/myapp/hello.txt

生成的包含：

The generated file contains:

Hello Mondo on Linux.  Italian

{{greeting}} 的值来自角色变量，因为未将其作为命令行选项提供。

The value of {{greeting}} comes from the role variable because it was not provided as a command-line option.

{{language}} 变量不是命令行选项，但可以通过 Handlebars 表达式使用。

The {{language}} variable was not a command line option, but it is is available to use with Handlebars expressions.

现在，我们可以删除生成的文件。在交互式外壳中，我们运行 . ! rm hello.txt 并传递 greeting 命令行选项：

Now we can remove the generated file. in the interactive shell, we run . ! rm hello.txt and pass in the greeting command line option:

$ spring hello say --greeting amico

生成的包含：

The generated file contains:

Hello amico on Linux.  Italian

Setting Variables

如需设置角色变量的值，请使用 spring role set 命令：

To set a value for a role variable, use the spring role set command:

spring role set --key greeting --value Mondo

可以使用 --role 选项选择性地指定角色。

You can optionally specify the role by using the --role option.

Getting Variables

如需检索角色变量的值，请使用以下命令：

To retrieve the value of a role variable, use the following command:

spring role get --key greeting

可以使用 --role 选项选择性地指定角色。

You can optionally specify the role by using the --role option.

随后可在使用 Handlebars 模板化的操作文件中访问角色变量 greeting。有关示例，请参见 [快速入门部分，roles-guide-quick-start]。

The role variable greeting can then be accessed inside action files that use Handlebars templating. See the roles-guide-quick-start for an example.

角色变量还用于与用户定义的命令选项名称进行匹配。如果值未作为命令行选项明确提供，则将使用角色变量的值。

The role variable is also used to match against user-defined command option names. If a value is not explicitly provided as a command-line option, the value of the role variable is used.

您还可以使用特殊命令 . ! 在交互式外壳中查看包含角色变量的文件的全部内容：

You can also use the special command, . !, to view the full contents of the file that contains role variables when you are in the interactive shell:

spring:>. ! cat .spring/roles/vars/vars.yml
greeting: mondo

Adding a Role

如需添加角色，请使用以下命令：

To add a role, use the following command:

spring role add qa

此命令将创建一个名为 qa 的角色。

This command creates a role named qa.

一个名为 ./spring/roles/vars/vars-qa.yml 的文件在根项目目录下被创建了。

A file named ./spring/roles/vars/vars-qa.yml is created under the root project directory.

Listing Roles

如需列出可用的角色，请使用以下命令：

To list the available roles, use the following command:

spring role list

此命令将展示角色列表：

This command displays the list of roles:

┌────┐
│Name│
├────┤
│qa  │
└────┘

Removing a Role

如需删除角色，请使用以下命令：

To remove a role, use the following command:

spring role remove qa

该命令移除名为“qa”的角色。

This command removes the role named qa.