YAML入门:以创建一个Kubernetes deployment为例

YAML语言似乎已经成为了事实标准的“云配置”语言,无论是容器事实标准docker(主要是docker-compose使用)、SDN,还是容器编排王者kubernetes,又或是虚拟机时代的王者openstack采用的配置文件都是yaml文件格式。不过需要承认的是我个人最初刚接触yaml时还不是很适应(个人更适应json),在后续运维kubernetes时,每每都要去参考k8s doc中的各种k8s对象的模板才能把yaml文件写“正确”。本文是一篇译文,这篇文章很好地讲解了yaml语言的语法格式,并用kubernetes deployment配置来作为示例。至少我看完这篇文章后是受益多多,因此这里将该文章快速翻译出来,供广大的k8s爱好者、实践者参考。

本文翻译自《Introduction to YAML: Creating a Kubernetes deployment》。(译注:CNCF也转发了Openstack开发背后的主力推手Mirantis公司博客的这篇文章。)

在之前的文章中,我们一直在讨论如何使用Kubernetes来启动和操作资源实例。到目前为止,我们一直都专注于命令行操作。但其实有一种更简单,更有用的方法:使用YAML创建配置文件。在本文中,我们将了解YAML的工作原理,并使用它来先定义一个Kubernetes Pod,然后再定义一个Kubernetes Deployment。

YAML基础

如果您正在做与一些软件领域相关的事情 – 尤其是涉及Kubernetes,SDN和OpenStack等领域,那么你将很难“摆脱”YAML 。YAML是一种人类可读的、专门用于配置信息的文本格式,例如,在本文中,我们将使用YAML定义创建第一个Pod,然后是Deployment。YAML可以理解为Yet Another Markup Language的缩写,也可以理解为”YAML Ain’t Markup Language”的缩写,这取决于你问的是谁。

使用YAML进行K8s定义会带来许多优势,包括:

  • 方便:您不再需要将所有参数都添加到命令行中
  • 可维护: YAML文件可以添加到源代码版本控制仓库中,因此你可以跟踪文件的修改
  • 灵活性:通过YAML,您能够创建比在命令行上更为复杂的结构

YAML是JSON的超集,这意味着任何有效的JSON文件也是有效的YAML文件。所以一方面,如果你知道JSON并且你只想写自己的YAML(而不是阅读其他人的那些),那么你就完全可以开始了。另一方面,不幸的是,这不太可能。即使你只是想在网上找些例子,他们更有可能是YAML格式(非JSON),所以我们不妨来习惯这种格式。尽管如此,在某些情况下JSON格式可能更为方便,因此最好知道JSON仍然可供您使用。

幸运的是,在YAML中你只需要了解两种类型的结构:

  • Lists(列表)
  • Maps

没错!你可能会用maps of lists和lists of maps,等等,但是一旦你掌握了这两个结构,那么你就可以开始了。这并不是说你不能做更复杂的事情,但总的来说,这就是你开始时需要的全部内容了。

YAML Maps

让我们先来看看YAML maps。maps允许您关联键值对(name-value pairs),在尝试设置配置信息时,这非常方便。例如,您可能有一个如下所示的配置文件:

---
apiVersion: v1
kind: Pod

第一行是分隔符,除非您尝试在单个文件中定义多个结构,否则它是可选的。在那之后,如您所见,我们有两个值:v1 和Pod ,映射到两个键:apiVersion 和kind 。

当然,这种事情非常简单,它等价于下面的JSON内容:

{
   "apiVersion": "v1",
   "kind": "Pod"
}

请注意,在我们的YAML版本中,引号是可选的; 处理程序可以告诉您正在查看基于这种格式的一个字符串。

您还可以通过创建一个映射到另一个map而不是字符串的键来指定更为复杂的结构,如下所示:

---
apiVersion: v1
kind: Pod
metadata:
  name: rss-site
  labels:
    app: web

在这种情况下,我们有一个键: metadata,其值为一个带有2个键:name和labels的map。该labels键本身有一个map作为其值。您可以根据需要嵌套这些。

YAML处理程序之所以知道所有这些部分是如何相互关联的,是因为我们做了行缩进。在这个例子中,我使用了2个空格以便于阅读,但空格的数量并不重要 – 只要它至少为1,并且只要你的缩进是一致的。例如,name和labels处于相同的缩进级别,因此处理程序知道它们都是同一个map的一部分; 它知道app 是labels的值,因为它进一步缩进了。

**注意:永远不要在YAML文件中使用tab **

因此,如果我们将其转换为JSON,它将是如下所示这样的:

{
  "apiVersion": "v1",
  "kind": "Pod",
  "metadata": {
               "name": "rss-site",
               "labels": {
                          "app": "web"
                         }
              }
}

现在我们来看list类型。

YAML Lists

YAML lists实际上是一个对象序列。例如:

args:
  - sleep
  - "1000"
  - message
  - "Bring back Firefly!"

正如您在此处所看到的,您可以在list中包含几乎任意数量的元素,这些元素为以短划线( – )开始并相对于父项缩进一级。所以如果用JSON展示,将是这样:

{
   "args": ["sleep", "1000", "message", "Bring back Firefly!"]
}

当然,list中的元素也可以是maps:

---
apiVersion: v1
kind: Pod
metadata:
  name: rss-site
  labels:
    app: web
spec:
  containers:
    - name: front-end
      image: nginx
      ports:
        - containerPort: 80
    - name: rss-reader
      image: nickchase/rss-php-nginx:v1
      ports:
        - containerPort: 88

正如您在这里看到的,我们有一个container“对象” 列表,每个container都包含一个name,一个image和一个port列表。ports下的每个列表项本身都是一个containerPort及其值的map。

为了完整起见,让我们快速查看等效的JSON:

{
   "apiVersion": "v1",
   "kind": "Pod",
   "metadata": {
                 "name": "rss-site",
                 "labels": {
                             "app": "web"
                           }
               },
    "spec": {
       "containers": [{
                       "name": "front-end",
                       "image": "nginx",
                       "ports": [{
                                  "containerPort": "80"
                                 }]
                      },
                      {
                       "name": "rss-reader",
                       "image": "nickchase/rss-php-nginx:v1",
                       "ports": [{
                                  "containerPort": "88"
                                 }]
                      }]
            }
}

正如你所看到的,我们的例子开始变得更为复杂了,不过我们还没有遇到特别复杂的例子!难怪YAML如此快地取代JSON。

所以让我们回顾一下。我们了解了:

  • maps,它们是键值对的组
  • lists,它们包含独立的元素(成员)
  • maps of maps
  • maps of lists
  • lists of lists
  • lists of maps

基本上,无论你想要组合什么结构,你都可以用这两种结构来做。

使用YAML创建Pod

好了,现在我们已经掌握了基础知识,让我们看看如何使用它。我们将首先使用YAML创建Pod,然后再创建Deployment。

如果您尚未安装Kubernetes集群和kubectl,请在继续之前查看本系列中有关搭建Kubernetes的集群的文章。没关系,我们等一下……

回来了吗?好!让我们从Pod开始吧。

创建pod文件

在前面的示例中,我们使用YAML描述了一个简单的Pod:

—
apiVersion: v1
kind: Pod
metadata:
 name: rss-site
 labels:
   app: web
spec:
 containers:
   – name: front-end
     image: nginx
     ports:
       – containerPort: 80
   – name: rss-reader
     image: nickchase/rss-php-nginx:v1
     ports:
       – containerPort: 88

我们一行行分开看,我们从API版本开始; 这里只是v1。(当我们讲解Deployment时,我们必须指定不同的版本,因为v1中不存在Deployment。)

接下来,我们指定要创建Pod; 这里我们可能会指定deployment,job,service等其他类型,具体取决于我们要实现什么。

接下来我们指定metadata。这里我们指定Pod的name,以及我们用来识别Kubernetes pod的label。

最后,我们将指定构成pod的实际对象。该规范(spec)的属性包括容器,存储卷,或其他Kubernetes需要了解的属性,比如:重新在启动容器失败时重启的选项。您可以在Kubernetes API规范中找到Kubernetes Pod属性的完整列表。让我们仔细看看典型的容器定义:

...
 spec:
   containers:
     - name: front-end
       image: nginx
       ports:
         - containerPort: 80
     - name: rss-reader
...

在这种情况下,我们有一个简单、短小的定义:name(前端),它所基于容器镜像(nginx ),以及容器将在内部监听的一个端口(80 )。在这些中,实际上只是name是必须的,但一般来说,如果你想要它做任何有用的事情,你需要更多的信息。

您还可以指定更复杂的属性,例如在容器启动时运行的命令,使用的参数,工作目录,或者每次实例化容器时是否拉取镜像的新副本等。您还可以指定一些更深入的信息,例如容器退出日志的存放位置。以下是您可以为Container设置的属性:

  • name
  • image
  • command
  • args
  • workingDir
  • ports
  • env
  • resources
  • volumeMounts
  • livenessProbe
  • readinessProbe
  • lifecycle
  • terminationMessagePath
  • imagePullPolicy
  • securityContext
  • stdin
  • stdinOnce
  • tty

现在让我们继续并实际创建pod。

使用YAML文件创建Pod

当然,第一步是创建一个文本文件。将其命名为pod.yaml 并添加以下文本,就像我们之前指定的那样:

---
 apiVersion: v1
 kind: Pod
 metadata:
   name: rss-site
   labels:
     app: web
 spec:
   containers:
     - name: front-end
       image: nginx
       ports:
         - containerPort: 80
     - name: rss-reader
       image: nickchase/rss-php-nginx:v1
       ports:
         - containerPort: 88

保存文件。接下来告诉Kubernetes创建pod:

> kubectl create -f pod.yaml
pod "rss-site" created

如您所见,K8引用了我们Pod的名称。如果你要求一个pod列表,你可以看到下面内容:

> kubectl get pods
 NAME       READY     STATUS              RESTARTS   AGE
 rss-site   0/2       ContainerCreating   0          6s

如果您提前检查,您可以看到仍在创建中的pod。几秒钟后,您应该看到容器正在运行:

> kubectl get pods
NAME       READY     STATUS    RESTARTS   AGE
rss-site   2/2       Running   0          14s

从这里开始,您可以测试Pod(就像我们在上一篇文章中所做的那样),但最终我们想要创建一个Deployment,所以让我们继续并删除它,这样就没有任何名称冲突:

> kubectl delete pod rss-site
pod "rss-site" deleted

Pod创建故障诊断

当然,有时事情并没有像你期望的那样发展。也许您遇到了网络问题,或者您在YAML文件中输入了错误的内容。您可能会看到如下错误:

> kubectl get pods
NAME       READY     STATUS         RESTARTS   AGE
rss-site   1/2       ErrImagePull   0          9s

在这种情况下,我们可以看到我们的一个容器启动得很好,但是另一个容器出了问题。要追查问题,我们可以向Kubernetes询问有关Pod的更多信息:

> kubectl describe pod rss-site
Name:           rss-site
Namespace:      default
Node:           10.0.10.7/10.0.10.7
Start Time:     Sun, 08 Jan 2017 08:36:47 +0000
Labels:         app=web
Status:         Pending
IP:             10.200.18.2
Controllers:    <none>
Containers:
  front-end:
    Container ID:               docker://a42edaa6dfbfdf161f3df5bc6af05e740b97fd9ac3d35317a6dcda77b0310759
    Image:                      nginx
    Image ID:                   docker://sha256:01f818af747d88b4ebca7cdabd0c581e406e0e790be72678d257735fad84a15f
    Port:                       80/TCP
    State:                      Running
      Started:                  Sun, 08 Jan 2017 08:36:49 +0000
    Ready:                      True
    Restart Count:              0
    Environment Variables:      <none>
  rss-reader:
    Container ID:
    Image:                      nickchase/rss-php-nginx
    Image ID:
    Port:                       88/TCP
    State:                      Waiting
      Reason:                   ErrImagePull
    Ready:                      False
    Restart Count:              0
    Environment Variables:      <none>

Conditions:
  Type          Status
  Initialized   True
  Ready         False
  PodScheduled  True
No volumes.
QoS Tier:       BestEffort
Events:
  FirstSeen     LastSeen        Count   From                    SubobjectPath  Type             Reason                  Message
  ---------     --------        -----   ----                    -------------  -------- ------                  -------
  45s           45s             1       {default-scheduler }                   Normal           Scheduled               Successfully assigned rss-site to 10.0.10.7
  44s           44s             1       {kubelet 10.0.10.7}     spec.containers{front-end}      Normal          Pulling                 pulling image "nginx"
  45s           43s             2       {kubelet 10.0.10.7}                    Warning          MissingClusterDNS       kubelet does not have ClusterDNS IP configured and cannot create Pod using "ClusterFirst" policy. Falling back to DNSDefault policy.
  43s           43s             1       {kubelet 10.0.10.7}     spec.containers{front-end}      Normal          Pulled                  Successfully pulled image "nginx"
  43s           43s             1       {kubelet 10.0.10.7}     spec.containers{front-end}      Normal          Created                 Created container with docker id a42edaa6dfbf
  43s           43s             1       {kubelet 10.0.10.7}     spec.containers{front-end}      Normal          Started                 Started container with docker id a42edaa6dfbf
  43s           29s             2       {kubelet 10.0.10.7}     spec.containers{rss-reader}     Normal          Pulling                 pulling image "nickchase/rss-php-nginx"
  42s           26s             2       {kubelet 10.0.10.7}     spec.containers{rss-reader}     Warning         Failed                  Failed to pull image "nickchase/rss-php-nginx": Tag latest not found in repository docker.io/nickchase/rss-php-nginx
  42s           26s             2       {kubelet 10.0.10.7}                    Warning          FailedSync              Error syncing pod, skipping: failed to "StartContainer" for "rss-reader" with ErrImagePull: "Tag latest not found in repository docker.io/nickchase/rss-php-nginx"

  41s   12s     2       {kubelet 10.0.10.7}     spec.containers{rss-reader}    Normal   BackOff         Back-off pulling image "nickchase/rss-php-nginx"
  41s   12s     2       {kubelet 10.0.10.7}                                    Warning  FailedSync      Error syncing pod, skipping: failed to "StartContainer" for "rss-reader" with ImagePullBackOff: "Back-off pulling image \"nickchase/rss-php-nginx\""

正如您所看到的,这里有很多信息,但我们对事件(event)最感兴趣- 特别是一旦警告和错误开始出现。从这里我能够很快发现我忘了将”:v1″ label添加到我的image中,所以它正在寻找”:latest”标签,但该标签并不存在。

为了解决这个问题,我首先删除了Pod,然后修复了YAML文件并重新启动。相反,我可以修复镜像仓库(译注:比如增加:latest标签),以便Kubernetes可以找到它正在寻找的东西,并且它会继续,好像什么也没发生过一样。

现在我们已经成功运行起来一个Pod,接下来让我们看看为deployment做得同样的事情。

使用YAML创建Deployment

最后,我们要创建一个实际的deployment。然而,在我们这样做之前,很值得去了解一下我们实际上在做什么。

记住,K8管理基于容器的资源。在使用deployment的情况下,您将创建一组要管理的资源。例如,我们在上一个示例中创建了Pod的单个实例,我们可能会创建一个Deployment来告诉Kubernetes管理该Pod的一组副本 – 字面意思就是ReplicaSet – 以确保它们中的一定数量是始终可用。所以我们可以像这样开始我们的deployment定义:

---
 apiVersion: extensions/v1beta1
 kind: Deployment
 metadata:
   name: rss-site
 spec:
   replicas: 2

在这里,我们将apiVersion指定为”extensions/v1beta1″ – 记住,我们想要一个deployment, 但deployment不像pod那样在v1中。接下来我们指定name。我们还可以指定我们想要的任何其他元数据,但现在让我们保持简单。

最后,我们进入规范(spec)。在Pod规范中,我们提供了有关实际进入Pod的内容的信息; 我们将在这里使用deployment做同样的事情。在这种情况下,我们先描述我们要部署什么Pod,我们总是希望有 2个副本。当然,您可以根据需要设置此数字,并且还可以设置其他属性,例如定义受此部署影响的Pod的selector,或者在被认为“ready”之前,pod必须启动且没有任何错误的最小秒数。您可以在Kuberenetes v1beta1 API参考中找到Deployment规范属性的完整列表。

好的,现在我们知道我们需要2个副本,我们需要回答这个问题:“什么的副本?”它们由模板定义:

---
 apiVersion: extensions/v1beta1
 kind: Deployment
 metadata:
   name: rss-site
 spec:
   replicas: 2
   template:
     metadata:
       labels:
         app: web
     spec:
       containers:
         - name: front-end
           image: nginx
           ports:
             - containerPort: 80
         - name: rss-reader
           image: nickchase/rss-php-nginx:v1
           ports:
             - containerPort: 88

看起来熟悉?就应该是这样; 它与上一节中的Pod定义几乎完全相同,而且就是这样设计的。模板只是要复制的对象的定义 – 在其他情况下,可以通过自己创建的对象。

现在让我们继续创建deployment。将YAML添加到名为deployment.yaml 的文件中,并让Kubernetes创建它:

> kubectl create -f deployment.yaml
deployment "rss-site" created

要了解它是如何做的,我们可以检查deployment列表:

> kubectl get deployments
NAME       DESIRED   CURRENT   UP-TO-DATE   AVAILABLE   AGE
rss-site   2         2         2            1           7s

正如您所看到的,Kubernetes已经启动了两个副本,但只有一个可用。您可以像以前一样通过描述deployment来检查事件日志:

> kubectl describe deployment rss-site
Name:                   rss-site
Namespace:              default
CreationTimestamp:      Mon, 09 Jan 2017 17:42:14 +0000=
Labels:                 app=web
Selector:               app=web
Replicas:               2 updated | 2 total | 1 available | 1 unavailable
StrategyType:           RollingUpdate
MinReadySeconds:        0
RollingUpdateStrategy:  1 max unavailable, 1 max surge
OldReplicaSets:         <none>
NewReplicaSet:          rss-site-4056856218 (2/2 replicas created)
Events:
  FirstSeen     LastSeen        Count   From                            SubobjectPath   Type            Reason                  Message
  ---------     --------        -----   ----                            -------------   --------        ------                  -------
  46s           46s             1       {deployment-controller }               Normal           ScalingReplicaSet       Scaled up replica set rss-site-4056856218 to 2

正如你在这里看到的,没有问题,它还没有完成扩展(scale)。再过几秒钟,我们可以看到两个Pod都在运行:

> kubectl get deployments
NAME       DESIRED   CURRENT   UP-TO-DATE   AVAILABLE   AGE
rss-site   2         2         2            2           1m

到这里我们得到了什么

好的,让我们回顾一下。我们基本上涵盖了三个主题:

  • YAML是一种人类可读的基于文本的格式,通过使用键值对的map和list(以及相互嵌套)的组合,您可以轻松指定配置类型信息。
  • YAML是使用Kubernetes对象最方便的方法,在本文中我们研究了创建Pod和Deployments。
  • 通过要求Kubernetes 描述(describe)它们,您可以获得有关运行(或应该运行)对象的更多信息。

这是我们的基本YAML教程。我们将在未来几个月内处理大量与Kubernetes相关的内容,因此,如果您想了解具体内容,请在评论中告知我们,或在@MirantisIT上发推特。


我的网课“Kubernetes实战:高可用集群搭建、配置、运维与应用”在慕课网上线了,感谢小伙伴们学习支持!

我爱发短信:企业级短信平台定制开发专家 https://tonybai.com/
smspush : 可部署在企业内部的定制化短信平台,三网覆盖,不惧大并发接入,可定制扩展; 短信内容你来定,不再受约束, 接口丰富,支持长短信,签名可选。

著名云主机服务厂商DigitalOcean发布最新的主机计划,入门级Droplet配置升级为:1 core CPU、1G内存、25G高速SSD,价格5$/月。有使用DigitalOcean需求的朋友,可以打开这个链接地址:https://m.do.co/c/bff6eed92687 开启你的DO主机之路。

我的联系方式:

微博:https://weibo.com/bigwhite20xx
微信公众号:iamtonybai
博客:tonybai.com
github: https://github.com/bigwhite

微信赞赏:
img{512x368}

商务合作方式:撰稿、出书、培训、在线课程、合伙创业、咨询、广告合作。

Go2 Error Inspection前瞻

这几年关于Go语言未来演化的讨论成为了Gopher世界的热点,Go team官方对于Go语言的演化(以Go2为标签)也是十分上心,但吸取了其他语言,比如:Python3割裂社区的、不兼容演化的教训,Go team最终选择了一条尽可能地兼容Go1、稳健、平滑的演化之路,并逐渐开始落地。Go 1.11Go modules是Go team开启Go2演化进程的标志性事件。随着“Go 2 Draft Design”发布,Go team正在努力着手解决Go社区反响较为强烈的Error handlingError valuesGenerics(泛型)这三个问题。从目前的进展上来看,Go error value相关机制的改善近期率先在以Proposal形式出现,并给出了待社区反馈的参考实现(golang.org/x/exp/xerrors),并很可能是继Go module之后第二个落地的Go2 特性。在本文中,我们就和大家一起来前瞻性探索一下Go2 error inspection及其参考实现。

一. Go2要解决关于Error的哪些问题

从全局角度,Go亟需解决的关于Error的问题包含两个大的方面,一个是Error handling机制,即尝试解决代码中大量重复出现下面代码的问题:

if err != nil {

   .... ....

}

第二个要解决的就是有关测试error变量值,并根据error变量值来选择后续代码执行路线的问题(面向机器),同时也要解决如何将error信息更完整、更全面地呈现给人的问题(面向人)。

关于error handling,draft引入了handle和check的新设计机制,该draft目前还在discuss之中;而第二个问题的解决正如我们前面提到的,已经率先成为Proposal并给出了参考实现,也是我们在本文中要重点探讨的内容。

Go error最初被创新地设计为一个interface:

type error interface {

    Error() string

}

这种设计是符合OCP(open-close principle)的,但是由于在error value test方面相对模糊且在标准库中缺少统一机制,导致gopher们在使用error时体验并不好。这里我们先来回顾一下在这之前我们是如何测试error变量值的。

1. 与预先定义好的知名error变量进行值相等测试 (以下称方法1)

如下面例子中,我们通过将ReadByte调用返回的err与io包中预定义的error变量: EOF(var EOF = errors.New(“EOF”))进行值测试,并根据测试结果选择接下来的代码执行路线:

func main() {
    reader := strings.NewReader("string reader buffer demo")

    for {
        s, err := reader.ReadByte()
        if err == io.EOF {
            fmt.Println("end")
            return
        } else if err != nil {
            fmt.Println(err)
            return
        }
        fmt.Printf("%c\n", s)
    }
}

对于预先已经定义的error变量,这样的error test方法是非常自然的,多数程序员从学习C语言那个时候就已经熟知该方法了。但是这种方法的局限就在于“扩展不足”。这些预定义好的error变量要么在标准库中,要么在依赖的第三方包中,我们只能使用这么多且这些变量所携带的信息有限。如果包中没有预定义或是想让这些变量携带更多对程序员有益的错误信息,我们就还得用其他办法来做error变量的值测试和扩展定义。

**2. 使用type assertion和type switch来测试是否是某种error的实现 **

标准库中net包中OpError的一些method中就采用了这种方式:

// $GOROOT/src/net/net.go

func (e *OpError) Timeout() bool {
    if ne, ok := e.Err.(*os.SyscallError); ok {
        t, ok := ne.Err.(timeout)
        return ok && t.Timeout()
    }
    t, ok := e.Err.(timeout)
    return ok && t.Timeout()
}

一些包还提供了一些专用方法来测试判定特定的error实现类型,比如:os包提供的IsNotExist、IsPermission等方法。不过这些方法在实现层面也都是使用的type assertion。

**3. 通过字符串匹配 **

由于缺少标准的、统一的error变量的值测试方法,尤其是针对重新wrapped的error变量(加上自己了的context信息,隐藏了underlying的error变量类型信息),在上述两种方法都无法使用的情况下,基于error变量Error()方法返回的string进行字符串匹配来进行error变量测试的手段成为了广大Gopher最后的“救命稻草”,但是这种方法也是最为“丑陋”的,是Go team最不希望gopher们使用的。

// 一个demo,现实中可能不存在这样的逻辑

func writeTxtFile(path string, content string) error {
    f, err := os.OpenFile("notes.txt", os.O_RDWR, 0755)
    if err != nil {
        return fmt.Errorf("open txt file: %s failed, reason: %s", path, err.Error())
    }

    defer f.Close()

    // ... write something
    _, err = f.Write([]byte(content))
    if err != nil {
        return fmt.Errorf("write to txt file: %s failed, reason: %s", path, err.Error())
    }

    return nil
}

func main() {
    err := writeTxtFile("./notes.txt", "write txt test")
    if err != nil {
        s := err.Error()
        if strings.Contains(s, "open txt file") {
            fmt.Println("open txt file error:", s) //但是我们仍然无法根据打开txt文件的具体原因类型(比如权限、还是文件不存在)做出相应的动作
            return
        }

        if strings.Contains(s, "write to txt file") {
            fmt.Println("write txt file error:", s)
            return
        }
    }
}

归根结底,fmt.Errorf提供的error wrap功能将最原始的error信息隐藏了起来,使得我们没有办法通过方法1或2来对wrapped的error变量进行值测试。这也是go2 error新方案要解决的问题。

二. xerrors的使用

下面我们来结合一下参考实现golang.org/x/exp/xerrors来看看该proposal是如何解决上述问题的。

1. wrapping error变量的创建

从前面的问题描述,我们知道Go2亟需提供一种简单的、标准的包裹(wrap)其他error变量并生成新error变量的方法,生成的新error变量中将包含被wrapped的error变量的信息:

img{512x368}

xerrors通过Errorf来提供这个功能。下面是参考上图函数调用和error变量包裹关系的一个Demo:

//github.com/bigwhite/experiments/xerrors/wrapper/wrapper1.go

func function4() error {
    return xerrors.New("original_error")
}

func function3() error {
    err := function4()
    if err != nil {
        return xerrors.Errorf("wrap3: %w", err)
    }
    return nil
}

func function2() error {
    err := function3()
    if err != nil {
        return xerrors.Errorf("wrap2: %w", err)
    }
    return nil
}

func function1() error {
    err := function2()
    if err != nil {
        return xerrors.Errorf("wrap1: %w", err)
    }
    return nil
}

func main() {
    err := function1()
    if err != nil {
        fmt.Printf("%v\n", err)
        return
    }

    fmt.Printf("ok\n")
}

通过xerror.Errorf对已知error变量进行包裹后,返回的error变量所归属的类型实现了error、xerrors.Formatter和xerrors.Wrapper接口,携带了被包裹(wrap)变量的信息,而传统的通过fmt.Errorf生成的error变量仅仅实现了error接口,没有被包裹的error变量的任何信息。这些携带的信息将在后续error变量值测试时(Is和As)以及error变量信息展示时被充分利用。

img{512x368}

我们运行一下上面的demo(默认得到单行的错误信息输出):

$go run wrapper1.go
wrap1: wrap2: wrap3: original_error

如果使用”+v%”输出error信息,我们将得到下面输出(多行):

$go run wrapper1.go
wrap1:
    main.function1
        /Users/tony/go/src/github.com/bigwhite/experiments/xerrors/wrapper/wrapper1.go:32
  - wrap2:
    main.function2
        /Users/tony/go/src/github.com/bigwhite/experiments/xerrors/wrapper/wrapper1.go:24
  - wrap3:
    main.function3
        /Users/tony/go/src/github.com/bigwhite/experiments/xerrors/wrapper/wrapper1.go:16
  - original_error:
    main.function4
        /Users/tony/go/src/github.com/bigwhite/experiments/xerrors/wrapper/wrapper1.go:10

我们看到”+v%”还输出每个错误变量生成时的位置信息,这是因为xerrors.Errorf生成的变量类型:wrapError中携带了“位置信息(frame Frame)”:

// golang.org/x/exp/xerrors/fmt.go

type wrapError struct {
    msg   string
    err   error
    frame Frame
}

上面的demo仅是为了演示通过xerrors.Errorf wrap的error variable携带了error chain的信息,并可以输出这些信息。下面我们来看看在函数调用的外部,如何对wrapped error variable进行各种值test。

2. error value test

对应上面提到方法1(等值测试)和方法2(type断言的类型测试),xerrors提供了对应的Is和As方法,这两个方法最大的不同就是可以针对wrapped error变量,在变量的error chain上做逐个进行测试,只要某个chain上的error变量满足要求,则返回true。我们分别来看看!

1) Is方法

xerrors的Is方法原型如下:

func Is(err, target error) bool

Is会将target与err中的error chain上的每个error 信息进行等值比较,如果相同,则返回true。我们用下面这幅图来诠释一下其原理:

img{512x368}

对应的测试代码见下面:

// github.com/bigwhite/experiments/xerrors/errortest/errortest1.go

func main() {
    err1 := xerrors.New("1")
    err2 := xerrors.Errorf("wrap 2: %w", err1)
    err3 := xerrors.Errorf("wrap 3: %w", err2)

    erra := xerrors.New("a")

    b := xerrors.Is(err3, err1)
    fmt.Println("err3 is err1? -> ", b)

    b = xerrors.Is(err2, err1)
    fmt.Println("err2 is err1? -> ", b)

    b = xerrors.Is(err3, err2)
    fmt.Println("err3 is err2? -> ", b)

    b = xerrors.Is(erra, err1)
    fmt.Println("erra is err1? -> ", b)
}

运行结果:

err3 is err1? ->  true
err2 is err1? ->  true
err3 is err2? ->  true
erra is err1? ->  false

2) As方法

Is方法是在error chain上做值测试。有些时候我们更方便做类型测试,即某一个err是否是某error类型。xerror提供了As方法:

func As(err error, target interface{}) bool

As会将err中的error chain上的每个error type与target的类型做匹配,如果相同,则返回true,并且将匹配的那个error var的地址赋值给target,相当于通过As的target将error chain中类型匹配的那个error变量析出。我们也用下面这幅图来诠释一下其原理:

img{512x368}

对应的测试代码见下面:

// github.com/bigwhite/experiments/xerrors/errortest/errortest2.go

type MyError struct{}

func (MyError) Error() string {
    return "MyError"
}

func main() {
    err1 := MyError{}
    err2 := xerrors.Errorf("wrap 2: %w", err1)
    err3 := xerrors.Errorf("wrap 3: %w", err2)
    var err MyError

    b := xerrors.As(err3, &err)
    fmt.Println("err3 as MyError? -> ", b)
    fmt.Println("err is err1? -> ", xerrors.Is(err, err1))

    err4 := xerrors.Opaque(err3)
    b = xerrors.As(err4, &err)
    fmt.Println("err4 as MyError? -> ", b)
    b = xerrors.Is(err4, err3)
    fmt.Println("err4 is err3? -> ", b)
}

运行结果:

err3 as MyError? ->  true
err is err1? ->  true
err4 as MyError? ->  false
err4 is err3? ->  false

我们看到As方法从err3的error chain中匹配到MyError类型的err1,并将err1赋值给err变量析出。在后续的Is测试也证实了这一点。代码中还调用了xerrors的Opaque方法,该方法将传入的支持unwrap操作的error变量转换为一个不支持unwrap的类型的error变量。在最后的对err4(通过Opaque调用得到)的测试我们也可以看到:err4无法匹配MyError type,与err3的等值测试也返回false。

三. 小结

以上就是xerrors提供的有关Go2 error inspection机制的主要功能。注意:xerrors及其proposal仍然可能会变动(包括设计和具体的实现),因此这里不能保证本文demo示例在后续的版本中依然可以编译运行。本文中的示例代码可以在这里得到。

目前go官方的golang.org/x/exp repo中有两个版本的实现:golang.org/x/exp/errors和golang.org/x/exp/xerrors。差别在于前者没有提供errors.Errorf。如果我们将wrapper1.go中的xerrors换成golang.org/x/exp/errors,则会在编译的时候出现下面错误:

$go run wrapper1.go
go: finding golang.org/x/exp/errors latest
go: downloading golang.org/x/exp/errors v0.0.0-20190125153040-c74c464bbbf2
# command-line-arguments
./wrapper.go:15:10: undefined: errors.Errorf
./wrapper.go:16:10: undefined: errors.Errorf
./wrapper.go:27:10: undefined: errors.Errorf
./wrapper.go:28:10: undefined: errors.Errorf

从官方的说明情况来看,golang.org/x/exp/errors将来要么进化到golang.org/x/errors,并作为Go标准库的vendor(类似于http/2) 包;要么直接merge到Go标准库中,然后该库作废(类似于vgo)。无论哪种形式,errors在merge后,会由fmt.Errorf来提供xerrors.Errorf的功能。

而golang.org/x/exp/xerrors则是可以用于任何版本的。

目前Go team给出的初步计划是在Go 1.13 dev cycle中将该Go 2 error inspection机制加入到main branch,并就像当年的http/2、vgo一样期待Gopher社区对该机制的反馈、然后优化,直到成熟并被广大Gopher所接受。


我的网课“Kubernetes实战:高可用集群搭建、配置、运维与应用”在慕课网上线了,感谢小伙伴们学习支持!

我要发短信:企业级短信平台定制开发专家 https://tonybai.com/
smspush : 可部署在企业内部的定制化短信平台,三网覆盖,不惧大并发接入,可定制扩展; 短信内容你来定,不再受约束, 接口丰富,支持长短信,签名可选。

著名云主机服务厂商DigitalOcean发布最新的主机计划,入门级Droplet配置升级为:1 core CPU、1G内存、25G高速SSD,价格5$/月。有使用DigitalOcean需求的朋友,可以打开这个链接地址:https://m.do.co/c/bff6eed92687 开启你的DO主机之路。

我的联系方式:

微博:https://weibo.com/bigwhite20xx
微信公众号:iamtonybai
博客:tonybai.com
github: https://github.com/bigwhite

微信赞赏:
img{512x368}

商务合作方式:撰稿、出书、培训、在线课程、合伙创业、咨询、广告合作。

如发现本站页面被黑,比如:挂载广告、挖矿等恶意代码,请朋友们及时联系我。十分感谢! Go语言第一课 Go语言精进之路1 Go语言精进之路2 Go语言编程指南
商务合作请联系bigwhite.cn AT aliyun.com

欢迎使用邮件订阅我的博客

输入邮箱订阅本站,只要有新文章发布,就会第一时间发送邮件通知你哦!

这里是 Tony Bai的个人Blog,欢迎访问、订阅和留言! 订阅Feed请点击上面图片

如果您觉得这里的文章对您有帮助,请扫描上方二维码进行捐赠 ,加油后的Tony Bai将会为您呈现更多精彩的文章,谢谢!

如果您希望通过微信捐赠,请用微信客户端扫描下方赞赏码:

如果您希望通过比特币或以太币捐赠,可以扫描下方二维码:

比特币:

以太币:

如果您喜欢通过微信浏览本站内容,可以扫描下方二维码,订阅本站官方微信订阅号“iamtonybai”;点击二维码,可直达本人官方微博主页^_^:
本站Powered by Digital Ocean VPS。
选择Digital Ocean VPS主机,即可获得10美元现金充值,可 免费使用两个月哟! 著名主机提供商Linode 10$优惠码:linode10,在 这里注册即可免费获 得。阿里云推荐码: 1WFZ0V立享9折!


View Tony Bai's profile on LinkedIn
DigitalOcean Referral Badge

文章

评论

  • 正在加载...

分类

标签

归档



View My Stats