深入浅出FE（十六）深入浅出YAML

雨点打透心脏的1/2处 2022-12-31 03:24 172阅读 0赞

YAML 并不是一种新奇的语言，YAML 首次发表于 2001 年，距离现在已经过去差不多 20 个年头。YAML 虽然不如 JSON、XML 之类的语言流行，应用也没有那么广泛，但是 YAML 也有它的优势。

# 一、简介 #

**YAML** 是一种较为人性化的**数据序列化语言**，可以配合目前大多数编程语言使用。

YAML 的语法比较简洁直观，特点是使用空格来表达层次结构，其最大优势在于**数据结构**方面的表达，所以 YAML 更多应用于**编写配置文件**，其文件一般以 **.yml** 为后缀。

> **YAML** 目前的官方全称为 “ **YAML Ain't Markup Language**（YAML 不是标记语言）”，但有意思的是，其实 YAML 最初的含义是 “ **Yet Another Markup Language**（还是一种标记语言）”。  
> 目前 YAML 的最新版本为 1.2（第三个版本），本文将以  **YAML 1.2** 的标准进行讲解。

--------------------

# 二、基本语法 #

### 大小写敏感 ###

*  就是字面上的意思

One: 1
    one: 2

### 用缩进表示层级关系 ###

*  缩进**只能使用空格**，不能用 TAB 字符
 *  缩进的**空格数量不重要**，但是**同一层级的元素左侧必须对齐**

# YAML
    one:
      two: 2
      three:
        four: 4
        five: 5
    
    // 以上的内容转成 JSON 后
    "one": {
      "two": 2,
      "three": {
        "four": 4,
        "five": 5 
      }
    }

### 用 \# 表示注释 ###

*  只支持单行注释

# 我是注释
    # 我也是注释

### 一个文件中可以包含多个文件的内容 ###

*  用“ **---** ”即**三个破折号**表示一份内容的**开始**
 *  用“ **...** ”即**三个小数点**表示一份内容的**结束**（非必需）

---
    # 这是第一份内容
    one: 1
    # 其他内容...
    ...
    
    ---
    # 这是第二份内容
    two: 2
    # 其他内容...

## 数据结构与类型 ##

### 对象（Mapping） ###

表示以键值对（key: value）形式出现的数据

*  使用“**冒号+空格**”来分开**键**与**值**

# YAML
    key: value
    
    // JSON
    "key": "value"

*  支持多层嵌套（**用缩进表示层级关系**）

# YAML
    key:
      child-key1: value1
      child-key2: value2
    
    // JSON
    "key": {
      "child-key1": "value1",
      "child-key2": "value2",
    }

*  支持**流式风格（ Flow style）**的语法（用花括号包裹，用逗号加空格分隔，类似 JSON）

# YAML
    key: { child-key1: value1, child-key2: value2 }
    
    // JSON
    "key": { "child-key1": "value1", "child-key2": "value2" }

*  使用**问号“?”**声明一个复杂对象，允许你使用多个词汇（数组）来组成键

# YAML
    ?
      - keypart1
      - keypart2
    :
      - value1
      - value2

### 数组（Sequence） ###

*  一组以**区块格式（Block Format）（即“破折号+空格”）**开头的数据组成一个数组

# YAML
    values:
      - value1
      - value2
      - value3
    
    // JSON
    "values": [ "value1", "value2", "value3" ]

*  同时也支持**内联格式（Inline Format）**来表达（用方括号包裹，逗号加空格分隔，类似 JSON）

# YAML
    values: [value1, value2, value3]
    
    // JSON
    "values": [ "value1", "value2", "value3" ]

*  支持多维数组（**用缩进表示层级关系**）

# YAML
    values:
      -
        - value1
        - value2
      -
        - value3
        - value4
    
    // JSON
    "values": [ [ "value1", "value2"], ["value3", "value4"] ]

### 标量（Scalars） ###

表示 YAML 中最基本的数据类型

### 字符串（String） ###

*  字符串**一般不需要用引号包裹**，但是如果字符串中**使用了反斜杠“\\”开头的转义字符就必须使用引号包裹**

# YAML
    strings:
      - Hello without quote # 不用引号包裹
      - Hello
       world # 拆成多行后会自动在中间添加空格
      - 'Hello with single quotes' # 单引号包裹
      - "Hello with double quotes" # 双引号包裹
      - "I am fine. \u263A" # 使用双引号包裹时支持 Unicode 编码
      - "\x0d\x0a is \r\n" # 使用双引号包裹时还支持 Hex 编码
      - 'He said: "Hello!"' # 单双引号支持嵌套"
    
    // JSON
    "strings":
      [ "Hello without quote",
        "Hello world",
        "Hello with single quotes",
        "Hello with double quotes",
        "I am fine. ☺",
        "\r\n is \r\n",
        "He said: 'Hello!'" ]

*  对于多行的文字，YAML 提供了两种特殊的语法支持

**保留换行(Newlines preserved)**

> 使用 **竖线符“ | ”**来表示该语法，每行的缩进和行尾空白都会被去掉，而额外的缩进会被保留

# YAML
    lines: |
      我是第一行
      我是第二行
        我是吴彦祖
          我是第四行
      我是第五行
    
    // JSON
    "lines": "我是第一行\n我是第二行\n  我是吴彦祖\n     我是第四行\n我是第五行"

**折叠换行(Newlines folded)**

> 使用 **右尖括号“ > ”**来表示该语法，只有空白行才会被识别为换行，原来的换行符都会被转换成空格

# YAML
    lines: >
      我是第一行
      我也是第一行
      我仍是第一行
      我依旧是第一行
    
      我是第二行
      这么巧我也是第二行
    
    // JSON
    "lines": "我是第一行 我也是第一行 我仍是第一行 我依旧是第一行\n我是第二行 这么巧我也是第二行"

### 布尔值（Boolean） ###

*  “true”、“True”、“TRUE”、“yes”、“Yes”和“YES”皆为**真**
 *  “false”、“False”、“FALSE”、“no”、“No”和“NO”皆为**假**

# YAML
    boolean:
      - true # True、TRUE
      - yes # Yes、YES
      - false # False、FALSE
      - no # No、NO
    
    // JSON
    "boolean": [ true, true, false, false ]

### 整数（Integer） ###

*  支持二进制表示

# YAML
    int:
      - 666
      - 0001_0000 # 二进制表示
    
    // JSON
    "int": [ 666, 4096 ]

### 浮点数（Floating Point） ###

*  支持科学计数法

# YAML
    float:
      - 3.14
      - 6.8523015e+5 # 使用科学计数法
    
    // JSON
    "float": [ 3.14, 685230.15 ]

### 空（Null） ###

*  “null”、“Null”和“~”都是空，不指定值默认也是空

# YAML
    nulls:
      - null
      - Null
      - ~
      -
    
    // JSON
    "nulls": [ null, null, null, null ]

### 时间戳（Timestamp） ###

*  YAML 也支持 **ISO 8601** 格式的时间数据

> 这里使用 JavaScript 对象进行对比

# YAML
    date1: 2020-05-26
    date2: 2020-05-26T01:00:00+08:00
    dete3: 2020-05-26T02:00:00.10+08:00
    date4: 2020-05-26 03:00:00.10 +8
    
    // JavaScript
    date1: Tue May 26 2020 08:00:00 GMT+0800 (中国标准时间),
    date2: Tue May 26 2020 01:00:00 GMT+0800 (中国标准时间),
    dete3: Tue May 26 2020 02:00:00 GMT+0800 (中国标准时间),
    date4: Tue May 26 2020 03:00:00 GMT+0800 (中国标准时间)

### 类型转换 ###

*  YAML 支持使用**严格类型标签“!!”**（双感叹号+目标类型）来强制转换类型

# YAML
    a: !!float '666' # !! 为严格类型标签
    b: '666' # 其实双引号也算是类型转换符
    c: !!str 666 # 整数转为字符串
    d: !!str 666.66 # 浮点数转为字符串
    e: !!str true # 布尔值转为字符串
    f: !!str yes # 布尔值转为字符串
    
    // JSON
    "a": 666,
    "b": "666",
    "c": "666",
    "d": "666.66",
    "e": "true"
    "f": "yes"

### 其他高级类型 ###

YAML 也可以使用一些更高级的类型，但是并不一定兼容所有解析器，包括**集合（Sets）**、**有序映射（Ordered Map）**、**十六进制数据（Hexdecimal）**和**二进制数据（Binary）。**

**本文将不会对这几种类型进行讲解，感兴趣的读者可以自行搜索研究。**

## 数据重用与合并 ##

*  为了保持内容的简洁，避免过多重复的定义，YAML 提供了由**锚点标签“&”**和**引用标签“\*”**组成的语法，利用这套语法可以快速引用相同的一些数据...

# YAML
    a: &anchor # 设置锚点
      one: 1
      two: 2
      three: 3
    b: *anchor # 引用锚点
    
    // JSON
    "a": {
      "one": 1,
      "two": 2,
      "three": 3
    },
    "b": {
      "one": 1,
      "two": 2,
      "three": 3
    }

*  配合**合并标签“<<”**使用可以与任意数据进行合并，你可以把这套操作想象成面向对象语言中的继承...

# YAML
    human: &base # 添加名为 base 的锚点
        body: 1
        hair: 999
    singer:
        <<: *base # 引用 base 锚点，实例化时会自动展开
        skill: sing # 添加额外的属性
    programer:
        <<: *base # 引用 base 锚点，实例化时会自动展开
        hair: 6 # 覆写 base 中的属性
        skill: code # 添加额外的属性
    
    // JSON
    "human": { "body": 1, "hair": 999 },
    "singer": { "body": 1, "hair": 999, "skill": "sing" },
    "programer": { "body": 1, "hair": 6, "skill": "code" }

--------------------

## 相关资料 ##

*  **YAML 官方网站**[https://yaml.org][https_yaml.org]
 *  **YAML 1.2 官方文档**[https://yaml.org/spec/1.2/spec.html][https_yaml.org_spec_1.2_spec.html]
 *  **YAML - 维基百科**[https://zh.wikipedia.org/wiki/YAML][https_zh.wikipedia.org_wiki_YAML]
 *  **YAML to JSON （格式在线转换）**[https://www.json2yaml.com/convert-yaml-to-json][https_www.json2yaml.com_convert-yaml-to-json]

--------------------

## 三、YAML用法 ##

*  stages
 *  cache
 *  only
 *  when
 *  before\_script，script， after\_script
 *  artifacts
 *  hidden\_job && extends
 *  reserved keywords - include

## stages: ##

stages是用来定义一个pipeline的，一个pipeline就像一个流水线，由一系列job来构成。比如在发布（publish）之前要做lint，test，build，那么这四个job就构成一个pipeline，写成下面的样子：

stages
      - lint
      - test
      - build
      - publish

然后你在gitlab的pipeline下面就能看到下面的图：  
![91a1212293be2b007dd4bc6627ed8087.png][]

上面我们虽然定义了一个pipeline，和4个job名称，但是具体每个job做什么还是不清楚的，接下来我们学习怎么定义一个job。

## job ##

以上面的lint为例，我们需要执行`npm run lint`命令来查看有没有lint错误，那么这个job可以写成：

job-lint:
      stage: lint
      script: npm run lint

这里`job-lint`是任务名称，`script`是要在终端执行的命令，`stage`表示这个job属于哪个stage（pipeline的某个节点）。job名称这里要注意一点是，不能使用保留字，比如：不能把一个job的名字称为stages或者image，就像变量名不能用if一样。相关文档可以看[这里][Link 1]。

一个stage下可以有多个job，比如：打包的时候要打包到windows，mac，linux下，可以这样：

job-build-mac:
      stage: build
    job-build-win;
      stage: build
    job-build-linux:
      stage: build

有时候，我们希望一些任务是在某些场景下执行的，比如：打tag的时候再build，这时候可以使用only/except。

### variables ###

在跑一个job的过程中，我们可能会需要环境变量，比如development,production，一个url，又或者是一个不希望显示在控制台的token，都可以作为一个环境变量，设置一个环境变量通常有3种方式：在项目设置中，在yml文件中，或者通过api。

通过项目设置界面来配置环境变量的入口如下：  
![41f9ea1444c9724d9a26c73fd32eb7a9.png][]  
在variables下可以配置变量名和值，通常是需要保密的变量

当然我们也可以设置在yml中：

variables:
      TEST: "HELLO WORLD"

然后就可以在脚本中引用：

script:
        - echo $TEST

### only/except ###

以上面的场景为例，我们可以这样写job-build:

job-build:
      stage: build
      script: npm run build
      only:
        - tags

这样，上面的job就只有在我们push tags时才会触发。如果我们希望一个job只在某一类分支有提交的时候触发，可以这样:

job-bugfix-build:
      stage: build
      script: npm run build
      only:
        - /^bugfix-.+$/

上面这个例子只有在bugfix为前缀的分支产生提交的时候，才会触发job-bugfix-build。

然而，这样并不足以让这个任务跑起来，因为CI是跑在docker里面的，在执行run lint之前，我们需要把node环境搭起来，这就需要image保留字了：

image: node:12.18

添加了image之后，在任务开始之前，还要安装依赖，我们使用before\_script来完成这件事:

# 使用node镜像
    image: node:12.18
    
    # 安装依赖
    before_script:
     - npm install

有时候我们希望在某些场景下不执行某项任务，这时可以使用expect，比如不对hotfix进行lint：

job-lint-except-hotfix:
      script: 
        - npm run lint
      except: /^hotfix-.+$/

### when ###

说了only,再说说when，`when` 是用来决定当前置任务失败时，当前job是否执行，以及如何执行的问题。比如我们希望lint成功了再执行build：

build_job:
      when: on_success
      stage: build
      needs: lint_job

再比如我们在执行发布的时候，希望手动点击发布按钮来执行发布：

publish_job:
      when: manual
      stage: publish
      script: npm run deploy

### artifacts ###

在前面提到的build job中，我们会使用webpack生成压缩，混淆后的代码，此时我们需要把它保存或者下载下来，这时就要用到artifacts了。用法如下：

build_job:
      script: npm run build
      artifacts:
        name: "$CI_COMMIT_REF_NAME"
        paths: dist/

artifacts最终会被打包成一个压缩文件，这里的path表示要添加到压缩文件的文件或文件夹，name表示生成的压缩文件的名字。然后在对应的任务详情特面就可以下载：  
![e26e521f704a8ca71e01cc0d941dce82.png][]

### include ###

正如通过程序通过模块来实现代码复用一样，CI的yml配置可以通过include实现配置复用：

include:
      - remote: 'https://gitlab.com/awesome-project/raw/master/.before-script-template.yml'
      - local: '/templates/.after-script-template.yml'
      - template: Auto-DevOps.gitlab-ci.yml

这样，我们可以把一些公用的环境变量或者job放到一个公共repo中，然后在其他项目中通过`remote`来引用。

最后，github actions与gitlab ci在概念上很相似，不过配置的写法不太一样，官方还贴心的出了迁移文档：[migrating-from-gitlab-cicd-to-github-actions][]

四、实例：

variables:
      DOCKER_DRIVER: overlay2
      DOCKER_HOST: tcp://localhost:8888
    
    .dind service: &dind_service
      - alias: docker
      name: ...
      command:
        - --insecure-registry=....
    
    cache:
      key: node-modules
      paths:
        - ./node_modules
    
    stages:
      - install
      - build
      - image
    
    install dependency:
      stage: install
      image: ...
      script:
        - npm config set registry 仓库地址
        - sudo npm install
    
    npm build：
      stage: build
      image: ...
    script:
      - sudo npm run build
      - sudo takill node
    artifacts:
      name: "$CI_COMMIT_SHORT_SHA"
      paths: 
        - build
    
    build images:
      build: image
      image: ...
      services: *dind_service 
      script:
        - cp /opt/frontend/Dockerfile
        - docker build ...
        - docker push ...
      dependencies:
        - npm build
      tags:
        - docker
      only:
        refs:
        - /^master/
        - /^qa/
        - /^dev/
        variables:
        - $CI_COMMIT_MESSAGE =~ /^build/

上面的YAML文件大致意思为：一旦分支为master 、 qa 、 dev开头有提交信息为build开头的提交会触发build这个job

参考：  
[https://gitlab.com/help/ci/yaml/README][https_gitlab.com_help_ci_yaml_README]

[https_yaml.org]: https://link.zhihu.com/?target=https%3A//yaml.org
[https_yaml.org_spec_1.2_spec.html]: https://link.zhihu.com/?target=https%3A//yaml.org/spec/1.2/spec.html
[https_zh.wikipedia.org_wiki_YAML]: https://link.zhihu.com/?target=https%3A//zh.wikipedia.org/wiki/YAML
[https_www.json2yaml.com_convert-yaml-to-json]: https://link.zhihu.com/?target=https%3A//www.json2yaml.com/convert-yaml-to-json
[91a1212293be2b007dd4bc6627ed8087.png]: /images/20221120/0476dffb29d340969ac6f111fae55d52.png
[Link 1]: https://gitlab.com/help/ci/yaml/README#unavailable-names-for-jobs
[41f9ea1444c9724d9a26c73fd32eb7a9.png]: /images/20221120/7364cb4ca713419e9d62aea8ed6f9075.png
[e26e521f704a8ca71e01cc0d941dce82.png]: /images/20221120/f70dea41eea0426f8c859a8fb27cd28b.png
[migrating-from-gitlab-cicd-to-github-actions]: https://docs.github.com/en/free-pro-team@latest/actions/learn-github-actions/migrating-from-gitlab-cicd-to-github-actions
[https_gitlab.com_help_ci_yaml_README]: https://gitlab.com/help/ci/yaml/README