作者 | 刘宇（阿里云 Serverless 产品经理）
在上篇《最全！即学即会 Serverless Devs 基础入门》中，我们阐述了工具链的重要性，并对安装方式 & 密钥配置进行了讲解。但是在 Serverless Devs 的规定中，一个 Yaml 可以被认为是一个 Serverless 应用，因此本文将继续带领各位了解下 Yaml 的使用规范。
Yaml的使用规范
Serverless Devs可以通过指定格式的Yaml对Serverless应用进行描述，在Serverless Devs的规定中，一个Yaml可以被认为是一个Serverless应用。
Yaml的格式需要按照 Serverless Devs 的规范，提供相对应的资源/行为描述文件，且该文件还需要符合以下条件：
- 拓展名可以是.yaml或.yml
- 格式必须符合Yaml规范 （https://yaml.org/spec/1.2.2/）
对于需要通过描述文件进行环境隔离的项目，建议将文件命名为 s-${ENV}.yaml 或 s-${ENV}.yml 格式。例如：s-prod.yaml。
在默认情况下，Serverless Devs 开发者工具会默认该描述文件的名称为s.yaml或s.yml，且s.yaml的优先级大于s.yml，即在一个 Serverless 应用下，同时出现s.yaml与s.yml时，系统会优先识别和使用s.yaml。
当然，开发者也可以通过-t,--template [templatePath]进行指定，例如，在某应用在生产环境下的描述文件名为s-prod.yml，则可以在执行相关命令时，增加参数-ts-prod.yml或者--templates-prod.yml。
描述文件格式/规范
关于 ServerlessDevs 所支持的资源/行为描述文件基本格式为：
edition: 1.0.0 # 命令行YAML规范版本，遵循语义化版本（Semantic Versioning）规范
name: applicationName # 应用名称
access: xxx-account1 # 秘钥别名
vars: # [全局变量，提供给各个服务使用]
Key: Value
Service: # 可以包括多个服务
ServiceName: # 服务名称
access: xxx-account1 # 秘钥别名，如果和项目的access相同，可省略
component: componentName # 组件名称
props: serviceProp # 组件的属性值
actions: serviceActions # 自定义执行逻辑
例如，一个相对完整的 Yaml 案例可以是：
edition: 1.0.0 # 命令行YAML规范版本，遵循语义化版本（Semantic Versioning）规范
name: FullStack # 项目名称
access: xxx-account1 # 秘钥别名
vars: # [全局变量，提供给各个服务使用]
logo: https://image.aliyun.com/xxxx.png
services:
nextjs-portal: # 服务名称
access: xxx-account1 # 秘钥别名，如果和项目的access相同，可省略
component: vue-component # 组件名称
props: # 组件的属性值
src: ./frontend_src
url: url
actions: # 自定义执行逻辑
pre-deploy: # 在deploy之前运行
- run: s exec -- publish # 要运行的命令行
path: ./backend_src # 命令行运行的路径
- run: s build # 要运行的命令行
path: ./backend_src # 命令行运行的路径
post-deploy: # 在deploy之后运行
- run: s clean
path: ./frontend_src
assets:
component: static
props:
cache-control: "public, max-age=604800, immutable"
www: "./public"
express-blog:
component: express
props:
app: ./express-blog
url: ${vars.domain}
actions:
pre-deploy:
- run: npm run build
path: ./express-blog
gateway:
component: serverless-gateway # 路由组件：HTTP URL和服务之间的映射规则
props:
routes:
- route: /~assets
value: ${assets.output.url}
- route: /
value: ${nextjs-portal.output.url}
index: index.html
- route: /~portal
value: ${nextjs-portal.output.url}
inex: index.html
- route: /~blog
value: ${express-blog.output.url}
元数据相关描述
在该格式中：
| 参数名 | 代表含义 |
|---|---|
| edition | 命令行YAML规范版本，遵循语义化版本（Semantic Versioning）规范 |
| name | 应用名称 |
| access | 秘钥别名，可以使用通过config命令配置的密钥信息，以及配置到环境变量的密钥信息 |
| vars | 全局变量，提供给各个服务使用，是一个Key-Value的形式 |
| Service | 应用所包含的服务，是一个Key-Value的形式 |
关于Service参数：
| 参数名 | 代表含义 |
|---|---|
| access | 秘钥别名，如果和项目的access相同，可省略 |
| component | 组件名称 |
| actions | 自定义执行逻辑 |
| props | 组件的属性值 |
变量赋值
Serverless Devs的Yaml文件支持多种变量格式：
- 获取当前机器中的环境变量：${env(环境变量)}，例如${env(secretId)}
- 获取外部文档的变量：${file(路径)}，例如${file(./path)}
- 获取全局变量：${vars.*}
- 获取其他项目的变量：${projectName.props.*}
- 获取Yaml中其他项目的结果变量：${projectName.output.*}
服务顺序
如果一个ServerlessApplication模型对应的Yaml文件中有过多的服务，系统会默认分析部署顺序，该部署顺序分为两个步骤：
- 分析项目中的依赖关系
- 有依赖关系的按照依赖关系从前到后部署，无依赖关系的按Yaml配置的从上到下部署
行为描述
在ServerlessApplication模型对应的Yaml文件中，可以针对服务，提供对应的行为操作，其基本格式是：
actions: # 自定义执行逻辑
pre-命令: # 在命令之前运行
- run: command # 要运行的操作
path: ./path # 运行操作的路径
post-命令: # 在命令之后运行
- run: command # 要运行的操作
path: ./path # 运行操作的路径
例如：
actions: # 自定义执行逻辑
pre-deploy: # 在deploy之前运行
- run: s exec -- publish # 要运行的命令行
path: ./backend_src # 命令行运行的路径
- run: s build # 要运行的命令行
path: ./backend_src # 命令行运行的路径
post-deploy: # 在deploy之后运行
- run: s clean
path: ./frontend_src
当ServerlessDevs开发者工具执行到该服务时，会在进行相关的命令之行之前，优先按照顺序执行pre-命令的操作，所有内容完成执行之后，再执行post-命令的操作。
以下面的Yaml为例：
edition: 1.0.0 # 命令行YAML规范版本，遵循语义化版本（Semantic Versioning）规范
name: FullStack # 项目名称
services:
nextjs-portal: # 服务名称
access: xxx-account1 # 秘钥别名，如果和项目的access相同，可省略
component: vue-component # 组件名称
props: # 组件的属性值
src: ./frontend_src
url: url
actions: # 自定义执行逻辑
pre-deploy: # 在deploy之前运行
- run: s exec -- publish # 要运行的命令行
path: ./backend_src # 命令行运行的路径
- run: s build # 要运行的命令行
path: ./backend_src # 命令行运行的路径
post-deploy: # 在deploy之后运行
- run: s clean
path: ./frontend_src
当开发者在当前应用下执行了deploy命令，系统将会按照以下顺序进行操作：
- 在./backend_src目录下执行s exec -- publish
- 在./backend_src目录下执行s build
- 调用组件vue-component的deploy方法，并将props和项目的基本信息传入到组件vue-component的deploy方法中
- 在./frontend_src目录下执行s clean
以上顺序仅适用于整个流程没有出错的前提下，如果流程出现错误，系统将会进行报错，并终止后续流程的执行。
通过命令操作应用
所谓的自定义命令指的是由组件决定的命令。由于 ServerlessDevs 开发者工具，本身并不具备任何业务相关的能力（值得包括不限于函数的部署、应用的构建、项目的测试等），所以，这些能力都将会由组件提供，通过 ServerlessDevs 开发者工具进行透出。
例如，某应用的资源/行为描述文件如下：
edition: 1.0.0 # 命令行YAML规范版本，遵循语义化版本（Semantic Versioning）规范
name: FullStack # 项目名称
access: xxx-account1
services:
backend: # 服务名称
component: django-component # 组件名称
props: # 组件的属性值
src: ./backend_src
url: url
user—frontend: # 服务名称
component: vue-component # 组件名称
props: # 组件的属性值
src: ./frontend_src_user
url: url
admin-frontend: # 服务名称
component: vue-component # 组件名称
props: # 组件的属性值
src: ./frontend_src_admin
url: url
通过该 Yaml 文件可以看出以下信息：
- 该应用的名字是FullStack，将会使用密钥xxx-account1;
- 该应用拥有三个服务：
- backend服务：使用了django-component组件
- user—frontend服务：使用了vue-component组件
- admin-frontend服务：使用了vue-component组件
如果此时django-component组件和vue-component组件支持的自定义命令为：
|
| django-component | vue-component |
| --- | --- | --- |
| deploy | 支持 | 支持 |
| remove | 支持 | 支持 |
| test | 支持 | 不支持 |
则可以通过自定义命令实现应用级操作和服务级操作。
1）应用级操作
在当前项目下，可以执行s [自定义命令]实现应用纬度的操作。
-
执行s deploy或者s remove时，由于backend、user—frontend、admin-frontend三个服务对应的组件，均支持deploy和remove方法，所以此时系统会按照服务的部署顺序，进行三个服务分别对应的组件的deploy或remove操作；此时，系统的exit code为0；
-
执行s test时，由于user—frontend、admin-frontend两个服务对应的组件并不支持test方法，所以此时系统会执行backend对应组件（django-component）的test操作；此时，系统会对user—frontend、admin-frontend两个服务进行警告，但是并不会报错，最终的exit code为0；
-
如果在执行相关的命令时，backend、user—frontend、admin-frontend三个服务任何一个服务在执行过程中出现了错误，系统则会报错，并终止下一步的操作，此时，系统的exit code为101；
2）服务级操作
在当前项目下，可以执行s [服务名] [自定义命令]实现服务级操作。
-
执行s backend deploy等，可以针对服务backend进行deploy相关的操作，如果顺利完成与其操作，系统的exit code为0；否则，出现错误，系统的exit code为101；
-
执行s admin-frontend test是，由于服务admin-frontend对应的test方法是不存在的，此时系统将会认为是未找到组件方法，系统的exit code为100；
多种操作模式下的工具体系
众所周之，目前大部分的Serverless开发者工具均是通过Yaml等进行资源描述，少部分的Serverless开发者工具是通过命令行直接操作，无论是通过Yaml进行资源描述，还是通过纯命令行的操作，可以说两者各有各的好处。而在ServerlessDevs开发者工具中，这两者均得以有效的支持。
Serverless Devs 开发者工具从根本上提供了两种使用方法。
- Yaml模式：需要依赖资源描述文档进行操作的模式
- Cli模式：可以在任何目录下直接执行，而不需要依赖资源描述文档；
这两者的核心区别是：
- 如果想要使用 Yaml 模式，在当前目录下，必须要有s.yaml/s.yml文件，或通过-t/--template指定的资源部描述文件；
- 如果想要试用 Cli 模式，则必须是 s cli 组件名方法参数的格式进行，此时不需要 Yaml 文件；
举一个非常简单的例子，如果有一个应用的资源描述文件s.yaml如下：
name: myApp
edition: 1.0.0
access: "myaccess"
services:
website-starter:
component: devsapp/website
props:
bucket: testbucket
backend-starter:
component: devsapp/demo
props:
service:
name: serviceName
function:
name: functionName
region: cn-hangzhou
此时，可以执行s deploy进行myApp应用部署，如果执行s backend-starter deploy则可以进行myApp应用下的backend-starter项目/服务部署。
此时，部署过程中，所需要的相关参数，可以通过该 Yaml 文件进行读取。
但是，在某些情况下，并不方便直接使用 ServerlessDevs 规范的 Yaml 文件（例如，将线上资源同步到本地，或者要将 Funcraft 的 Yaml 转换成为 Serverless Devs 的 Yaml），此时可以选择纯命令行形式，即s cli模式。
在 s cli模式下，由于不会读取 Yaml 等资源描述文件，所以很多参数都需要自行填写，这时的填写方法有两种：
- 通过 s cli天然支持的 -p/--prop参数，进行相关Yaml 参数的赋值，例如上述案例的s backend-starter deploy，此时可以改写成：
$ s cli devsapp/demo -p "{\"service\":{\"name\":\"serviceName\"},\"function\":{\"name\":\"functionName\"},\"region\":\"cn-hangzhou\"}"
- 通过 demo 组件本身所支持的一些参数，例如通过s clidevsapp/demo -h，可以得到帮助信息，部分内容如下：
--region [region] [C-Required] Specify the fc region, value: cn-hangzhou/cn-beijing/cn-beijing/cn-hangzhou/cn-shanghai/cn-qingdao/cn-zhangjiakou/cn-huhehaote/cn-shenzhen/cn-chengdu/cn-hongkong/ap-southeast-1/ap-southeast-2/ap-southeast-3/ap-southeast-5/ap-northeast-1/eu-central-1/eu-west-1/us-west-1/us-east-1/ap-south-1
--service-name [serviceName] [C-Required] Specify the fc service name
--function-name [functionName] [Optional] Specify the fc function name
此时，就可与通过下面的命令实现上述功能：
$ s cli devsapp/demo --region cn-hangzhou --service-name serviceName --function-name functionName
特点对比
| 模式 | 使用方法 | 优势 | 劣势 | 适用场景 |
|---|---|---|---|---|
| Yaml模式 | 在具有符合Serverless Devs规范，且存在资源/行为描述的Yaml文件的应用目录下，执行组件对应的命令，即可直接使用，例如s deploy，s servicename build等 | 可以一键部署一个完整的应用（例如，某个应用中规定了多个Service，可以通过该命令一键部署）；同时，通过资源/行为描述文档，可以更佳简单，清晰的对应用进行描述； | 需要学习Yaml的规范，且在某些时候与一些自动化流程进行结合，会比较复杂； | 部署、运维等操作，尤其是批量操作时更为合适； |
| 纯Cli模式 | 在任何目录下，通过子命令cli进行触发，同样适用全部组件，例如s cli deploy -p "{/"function/": /"function-name/"}"，s cli fc-api listFunctions --service-name my-service | 相对来说可以更加简单，快速上手工具，并且可以非常简单的与自动化流程进行结合，降低了Yaml格式/规范的学习难度 | 对于一些复杂项目而言，需要在命令行中写过多的参数，出错的概率会比较高； | 更适合项目的管理，源自化操作 |
设计思路
为什么要同时存在 Yaml 模式和 Cli 模式？
因为在长期的实践过程中，发现通过 Yaml 进行资源描述会相对来说更简单和方便，例如 K8S 等也都是通过 Yaml 进行资源描述的；但是，在某些情况下，Yaml 文件也可能成为一种负担，例如想要查看某个服务下的函数列表，查看某个地区下的服务列表，因为这样一个简单的事情要额外的去完成一个 Yaml 文件，就显得过于臃肿，所以，在 Serverless Devs 项目中，同时保留了两种使用方法。
附录
[1]Serverless Devs 社区 GitHub：
https://github.com/serverless-devs/serverless-devs
更多内容关注 Serverless 微信公众号（ID：serverlessdevs），汇集 Serverless 技术最全内容，定期举办 Serverless 活动、直播，用户最佳实践。