工作室：crate cargo_atelier

A cargo 命令，用于将 Smithy 模型作为构建过程的一部分使用。

用法

> cargo atelier --help
cargo-atelier 0.2.2
Tools for the Smithy IDL.

USAGE:
    cargo-atelier [FLAGS] <SUBCOMMAND>

FLAGS:
    -h, --help        Prints help information
    -n, --no-color    Turn off color in the output
    -V, --version     Prints version information
    -v, --verbose     The level of logging to perform; from off to trace

SUBCOMMANDS:
    convert     Convert model from one representation to another
    document    Create human-readable documentation from a model
    help        Prints this message or the help of the given subcommand(s)
    lint        Run standard linter rules on a model file
    validate    Run standard validators on a model file

lint 和 validate 命令都使用相同的机制来打印结果，并且默认使用彩色输出。由于可以使用不同的代码检查和验证规则，"报告的" 行会告知您哪个规则集确定了错误。

document 命令从模型创建文档，依赖于特定的特征来处理文本，以及依赖预定义特征来处理某些语义属性。它使用了 somedoc crate 来进行格式化，因此该工具指定的输出格式可以选择 somedoc 支持的任何格式。

示例 Lint

对于以下格式错误的 Smithy 文件，在 test-models/lint-test.smithy。

namespace org.example.smithy

@ThisIsNotAGoodName
structure thisIsMyStructure {
    lower: String,
    Upper: String,
    someJSONThing: someUnknownShape,
    OK: Boolean
}

string someUnknownShape

@trait
structure ThisIsNotAGoodName {}

代码检查运行时将输出以下问题。

> cargo atelier lint -i test-models/lint-test.smithy

[info] Shape names should conform to UpperCamelCase, i.e. ThisIsMyStructure
	Reported by NamingConventions on/for element `thisIsMyStructure`.

[info] Trait names should conform to lowerCamelCase, i.e. thisIsNotAGoodName
	Reported by NamingConventions on/for element `ThisIsNotAGoodName`.

[info] Member names should conform to lowerCamelCase, i.e. ok
	Reported by NamingConventions on/for element `thisIsMyStructure$OK`.

[info] Member name 'OK' appears to contain a known acronym, consider renaming i.e. ok
	Reported by NamingConventions on/for element `thisIsMyStructure`.

[info] Member names should conform to lowerCamelCase, i.e. someJsonThing
	Reported by NamingConventions on/for element `thisIsMyStructure$someJSONThing`.

[info] Member name 'someJSONThing' appears to contain a known acronym, consider renaming i.e. Json
	Reported by NamingConventions on/for element `thisIsMyStructure`.

[info] Shape names should conform to UpperCamelCase, i.e. SomeUnknownShape
	Reported by NamingConventions on/for element `someUnknownShape`.

[info] Member names should conform to lowerCamelCase, i.e. upper
	Reported by NamingConventions on/for element `thisIsMyStructure$Upper`.

示例 Validate

对于以下错误的 Smithy 文件，在 test-models/validation-test.smithy。

namespace org.example.smithy

structure MyStructure {
    known: String,
    wrongType: SomeOperation,
}

operation SomeOperation {
    input: SomeService
}

service SomeService {
    version: "1.0",
    operations: [MyStructure]
}

验证运行时将输出以下问题。

> cargo atelier validate -i test-models/validation-test.smithy

[error] Structure member may not refer to a service, operation, resource or apply.
	Reported by CorrectTypeReferences on/for element `MyStructure$wrongType`.

[warning] Structure member's type (smithy.api#NotString) cannot be resolved to a shape in this model.
	Reported by CorrectTypeReferences on/for element `MyStructure$unknown`.

[error] Service operation must be an operation.
	Reported by CorrectTypeReferences on/for element `SomeService`.

[error] Operation input may not refer to a service, operation, resource or apply.
	Reported by CorrectTypeReferences on/for element `SomeOperation`.

示例 Documentation

> cargo atelier document -i test-models/lint-test.smithy -w xwiki
{{comment}}
title: Smithy Model
{{/comment}}


Smith Version: 1.0

= Namespace org.example.smithy =

(% id="shape:ThisIsNotAGoodName" %) == ThisIsNotAGoodName (structure) ==

|=Trait|=Value|
|Is Trait|##true##|


(% id="shape:someUnknownShape" %) == someUnknownShape (string) ==

(% id="shape:thisIsMyStructure" %) == thisIsMyStructure (structure) ==

=== Members ===

* ##Upper##: ##smithy.api#String##
* ##lower##: ##smithy.api#String##
* ##OK##: ##smithy.api#Boolean##
* ##someJSONThing##: [[someUnknownShape>>.||anchor=shape:someUnknownShape]]

参数

任何命令都可能包含的通用参数。

• -V，--version；打印版本信息（并退出）。
• -h，--help；打印帮助信息（并退出）。
• -v, --verbose；开启更多日志，添加参数的次数越多，日志越多。
• --no-color；关闭颜色支持。

以下参数适用于所有文件输入。文件输入使用 atelier_assembler 包来读取多个文件并支持多种文件表示。默认情况下，模型汇编器不使用搜索路径来加载文件。但是，可以通过 -d 标志来更改这一点，该标志将在环境变量 $SMITHY_PATH 中找到的任何文件进行加载。或者，-s 参数提供了替代 $SMITHY_PATH 使用的环境变量名称。

• -d, --default-search-env；如果设置，则将标准环境变量 SMITHY_PATH 用作搜索路径。
• -, --in-file <in-file>；要读取的文件名，可以指定多个文件。
• -, --search-env <search-env>；用作搜索路径的环境变量名称。