![](https://intranetproxy.alipay.com/skylark/lark/0/2022/jpeg/22456429/1653472041966-90808b24-8d6e-4d05-954c-e87dbd83bbae.jpeg#clientId=u912b3a73-0a88-4&crop=0&crop=0&crop=1&crop=1&from=paste&id=u10420423&margin=%5Bobject%20Object%5D&originHeight=383&originWidth=900&originalType=url&ratio=1&rotation=0&showTitle=false&status=done&style=none&taskId=u17df7d1c-e1dd-4616-9156-4d132f104eb&title=)
作者 | 劉宇（阿里雲 Serverless 產品經理）

在上篇《[最全！即學即會 Serverless Devs 基礎入門](http://mp.weixin.qq.com/s?__biz=MzI4NzI5MDM1MQ==&mid=2247511276&idx=1&sn=3c624887e1f59f7a905bb2918c1a8658&chksm=ebcd0a6cdcba837a9e754c117177ab0686b42aad274a9d0772f34f7580b052f74db644be9ee2&scene=21#wechat_redirect)》中，我們闡述了工具鏈的重要性，並對安裝方式 & 金鑰配置進行了講解。但是在 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/) （[https://yaml.org/spec/1.2.2/](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命令](https://github.com/Serverless-Devs/Serverless-Devs/blob/master/docs/zh/command/config.md#config-add-%E5%91%BD%E4%BB%A4)配置的金鑰資訊，以及[配置到環境變數的金鑰資訊](https://github.com/Serverless-Devs/Serverless-Devs/blob/master/docs/zh/command/config.md#%E9%80%9A%E8%BF%87%E7%8E%AF%E5%A2%83%E5%8F%98%E9%87%8F%E9%85%8D%E7%BD%AE%E5%AF%86%E9%92%A5%E4%BF%A1%E6%81%AF) |
| **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檔案中有過多的服務，系統會預設分析部署順序，該部署順序分為兩個步驟：

1. 分析專案中的依賴關係
1. 有依賴關係的按照依賴關係從前到後部署，無依賴關係的按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命令，系統將會按照以下順序進行操作：

1. 在./backend_src目錄下執行s exec -- publish
1. 在./backend_src目錄下執行s build
1. 呼叫元件vue-component的deploy方法，並將props和專案的基本資訊傳入到元件vue-component的deploy方法中
1. 在./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 檔案可以看出以下資訊：

1. 該應用的名字是FullStack，將會使用金鑰xxx-account1;
1. 該應用擁有三個服務：
   - 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_

![](https://intranetproxy.alipay.com/skylark/lark/0/2022/jpeg/22456429/1653472042192-977e687b-d8f6-4239-807c-d3b9b152c20a.jpeg#clientId=u912b3a73-0a88-4&crop=0&crop=0&crop=1&crop=1&from=paste&id=u16c1c70c&margin=%5Bobject%20Object%5D&originHeight=600&originWidth=1080&originalType=url&ratio=1&rotation=0&showTitle=false&status=done&style=none&taskId=uafda6365-4b9d-46a6-a20b-8ecbd315361&title=)

最全！即學即會 Serverless Devs 基礎入門（下）

相關文章