本文翻译自《Boosting your kubectl productivity》。

第一部分：什么是kubectl？

1. 通过命令完成(command completion)减少输入

命令完成是提高你的kubectl生产力的最有用但经常被忽视的技巧之一。

命令完成允许您使用Tab键自动完成kubectl命令的各个部分。这适用于子命令，选项和参数，包括资源名称等难以输入的内容。

在这里你可以看到kubectl命令完成的动作：

命令完成在Bash和Zsh shell下均可用。

在官方文档中包含有关设置命令完成的详细说明，下面的章节我们再带着大家回顾一下。

命令完成的工作原理

通常，命令完成是一个shell功能，它通过completion script(完成脚本)的方式工作。完成脚本是一个shell脚本，用于定义特定命令的完成行为。获取完成脚本可以完成相应的命令。

Kubectl可以使用以下命令自动生成并打印出Bash和Zsh的完成脚本：

$kubectl completion bash
# or
$kubectl completion zsh

理论上，在适当的shell中获取此命令的输出可以完成kubectl命令。

但是，在实践中，Bash（包括Linux和macOS之间的差异）和Zsh的细节不同。以下部分解释了所有这些情况：

• 在Linux上为Bash设置命令完成
• 在macOS上设置Bash的命令完成
• 设置Zsh的命令完成

在Linux上的Bash

Bash的完成脚本取决于bash-completion项目，因此您必须先安装它。

您可以使用各种包管理器安装bash-completion 。例如：

$sudo apt-get install bash-completion
# or
$yum install bash-completion

您可以使用以下命令测试是否正确安装了bash-completion：

$type _init_completion

如果这输出shell函数的代码，则已正确安装bash-completion。如果该命令输出not found错误，则必须将以下行添加到您的~/.bashrc文件中：

$source /usr/share/bash-completion/bash_completion

是否必须将此行添加到您的~/.bashrc文件中，取决于您用于安装bash-completion的包管理器。对于APT来说，这是必要的，对于yum，则无需。

安装bash-completion后，您必须进行设置，以便在所有shell会话中获取kubectl 完成脚本。

一种方法是将以下行添加到您的~/.bashrc文件中：

source <(kubectl completion bash)

另一种可能性是将kubectl完成脚本添加到/etc/bash_completion.d目录中（如果它不存在则创建它）：

$kubectl completion bash >/etc/bash_completion.d/kubectl

/etc/bash_completion.d目录中的所有完成脚本都是由bash-completion自动获取的。

两种方法都是等价的。

重新加载shell后，kubectl命令完成应该正常工作！

在MacOS上的Bash

有了macOS，就会出现轻微的复杂情况。原因是macOS上的Bash默认版本是3.2，这已经过时了。遗憾的是，kubectl完成脚本至少需要Bash 4.1，因此不适用于Bash 3.2。

Apple在macOS中包含过时版本的Bash的原因是较新版本使用Apple不支持的GPLv3许可证。

这意味着，要在macOS上使用kubectl命令完成，您必须安装较新版本的Bash。您甚至可以将它设为新的默认shell，这将为您节省很多此类麻烦。这实际上并不困难，您可以在我之前编写的macOS文章中的升级Bash中找到说明。

在继续之前，请确保您现在确实使用的是Bash 4.1或更新版本（请查看bash –version）。

Bash的完成脚本取决于bash-completion项目，因此您必须先安装它。

您可以使用Homebrew安装bash-completion ：

$brew install bash-completion@2

bash-completion v2的@2代表。kubectl完成脚本需要bash-completion v2，而bash-completion v2至少需要Bash 4.1。这就是您不能在低于4.1的Bash版本上使用kubectl完成脚本的原因。

该brew install命令的输出包含一个“警告”部分，其中包含将以下行添加到您的~/.bash_profile文件的说明：

export BASH_COMPLETION_COMPAT_DIR=/usr/local/etc/bash_completion.d
[[ -r "/usr/local/etc/profile.d/bash_completion.sh" ]] && . "/usr/local/etc/profile.d/bash_completion.sh"

您必须这样做才能完成bash-completion的安装。但是，我建议将这些行添加到您~/.bashrc文件中而不是~/.bash_profile文件中。这能确保子shell中也可以使用bash-completion。

重新加载shell后，可以使用以下命令测试是否正确安装了bash-completion：

$type _init_completion

如果这输出shell函数的代码，那么你就完成了。

现在，您必须进行设置以便kubectl 完成脚本在所有shell会话中获取。

一种方法是将以下行添加到您的~/.bashrc文件中：

source <(kubectl completion bash)

另一种可能性是将kubectl完成脚本添加到/usr/local/etc/bash_completion.d目录：

$kubectl completion bash >/usr/local/etc/bash_completion.d/kubectl

这仅在您使用Homebrew安装bash-completion时才有效。在这种情况下，bash-completion会在此目录中提供所有完成脚本。

如果您还使用Homebrew安装了kubectl，您甚至不必执行上述步骤，因为完成脚本应该已经通过kubectl howbrew formula放在/usr/local/etc/bash_completion.d目录中了。在这种情况下，kubectl完成应该在安装bash-completion后自动开始工作。

最后，所有这些方法都是等效的。

重新加载shell后，kubectl完成应该正常工作！

Zsh

Zsh的完成脚本没有任何依赖项。因此，您所要做的就是设置所有内容，以便在所有shell会话中获取源代码。

您可以通过在~/.zshrc文件中添加以下行来完成此操作：

source <(kubectl completion zsh)

如果在重新加载shell后出现错误:command not found: compdef，则必须启用compdef内置功能，您可以通过将以下内容添加到~/.zshrc文件的开头来执行此操作：

autoload -Uz compinit
compinit

2. 快速查找资源规范

创建YAML资源定义时，您需要知道这些资源的字段及其含义。一个可以查找到此类信息的位置是在API参考文档中，那里包含了所有资源的完整规范。

但是，每次需要查找某些内容时都要切换到Web浏览器很乏味。因此，kubectl提供了kubectl explain命令，可以打印出终端中所有资源的资源规范。

kubectl explain用法如下：

$kubectl explain resource[.field]...

该命令输出所请求资源或字段的规范。kubectl explain显示的信息与API参考中的信息相同。

默认情况下，kubectl explain仅显示单个级别的字段。您可以使用显示整个字段树的标志:–recursive：

$kubectl explain deployment.spec --recursive

如果您不确定可以使用哪些资源名称，可以使用kubectl explain以下命令显示所有这些名称：

$kubectl api-resources

此命令以复数形式显示资源名称（例如，deployments而不是deployment）。对于拥有短名称的资源，它还显示该资源的短名称（例如：deploy）。不要担心这些差异，对于kubectl来说，所有这些名称变体都是等同的。也就是说，你可以在kubectl explain中使用它们中的任何一个。

例如，以下所有命令都是等效的：

$kubectl explain deployments.spec
# or
$kubectl explain deployment.spec
# or
$kubectl explain deploy.spec

3. 使用自定义列输出格式

kubectl get命令的默认输出格式（用于读取资源）如下：

$kubectl get pods
NAME                      READY   STATUS    RESTARTS   AGE
engine-544b6b6467-22qr6   1/1     Running   0          78d
engine-544b6b6467-lw5t8   1/1     Running   0          78d
engine-544b6b6467-tvgmg   1/1     Running   0          78d
web-ui-6db964458-8pdw4    1/1     Running   0          78d

这对于人类而言，是一种很好的可读格式，但它只包含有限的信息。如您所见，每个资源只显示一些字段（与完整资源定义相比）。

这就是自定义列输出格式的用武之地。它允许您自由定义要显示在其中的列和数据。您可以选择要在输出中显示为单独列的资源的任何字段

自定义列输出选项的用法如下：

-o custom-columns=<header>:<jsonpath>[,<header>:<jsonpath>]...

您必须将每个输出列定义为一

<

header>:对：

• <

header> 是列的名称，您可以选择任何您想要的。
* 是一个选择资源字段的表达式（在下面更详细地说明）。

我们来看一个简单的例子：

$ kubectl get pods -o custom-columns='NAME:metadata.name'
NAME
engine-544b6b6467-22qr6
engine-544b6b6467-lw5t8
engine-544b6b6467-tvgmg
web-ui-6db964458-8pdw4

这里，输出包含一个显示所有Pod名称的列。

选择Pod名称的表达式是metadata.name。这样做的原因是Pod的名称在Pod资源字段的metadata的name字段中定义（您可以在API参考中查找或使用kubectl explain pod.metadata.name）。

现在，假设您要在输出中添加一个附加列，例如，显示每个Pod正在运行的节点。为此，您只需向自定义列选项添加适当的列规范：

$kubectl get pods \
  -o custom-columns='NAME:metadata.name,NODE:spec.nodeName'
NAME                      NODE
engine-544b6b6467-22qr6   ip-10-0-80-67.ec2.internal
engine-544b6b6467-lw5t8   ip-10-0-36-80.ec2.internal
engine-544b6b6467-tvgmg   ip-10-0-118-34.ec2.internal
web-ui-6db964458-8pdw4    ip-10-0-118-34.ec2.internal

选择节点名称的表达式是spec.nodeName。这是因为已调度Pod的节点保存在Pod的spec.nodeName字段中（请参阅参考资料kubectl explain pod.spec.nodeName）。

请注意，Kubernetes资源字段区分大小写。

您可以通过这种方式将资源的任何字段设置为输出列。只需浏览资源规范并尝试使用您喜欢的任何字段！

但首先，让我们仔细看看这些字段选择表达式。

JSONPath表达式

选择资源字段的表达式基于JSONPath。

JSONPath是一种从JSON文档中提取数据的语言（类似于XPath for XML）。选择单个字段只是JSONPath的最基本用法。它有很多功能，如列表选择器，过滤器等。

但是，kubectl explain仅支持JSONPath功能的一部分。以下通过示例用法总结了这些支持的功能：

# Select all elements of a list
$kubectl get pods -o custom-columns='DATA:spec.containers[*].image'

# Select a specific element of a list
$kubectl get pods -o custom-columns='DATA:spec.containers[0].image'

# Select those elements of a list that match a filter expression
$kubectl get pods -o custom-columns='DATA:spec.containers[?(@.image!="nginx")].image'

# Select all fields under a specific location, regardless of their name
$kubectl get pods -o custom-columns='DATA:metadata.*'

# Select all fields with a specific name, regardless of their location
$kubectl get pods -o custom-columns='DATA:..image'

特别重要的是[]操作符。Kubernetes资源的许多字段都是列表，此运算符允许您选择这些列表中的项目。它通常与通配符一起使用，[*]以选择列表中的所有项目。

您将在下面找到一些使用此表示法的示例。

示例应用程序

使用自定义列输出格式的可能性是无穷无尽的，因为您可以在输出中显示资源的任何字段或字段组合。以下是一些示例应用程序，但您可以自己探索并找到对您有用的应用程序！

提示：如果您经常使用其中一个命令，则可以为其创建shell别名。

显示Pods的容器镜像

$kubectl get pods \
  -o custom-columns='NAME:metadata.name,IMAGES:spec.containers[*].image'
NAME                       IMAGES
engine-544b6b6467-22qr6    rabbitmq:3.7.8-management,nginx
engine-544b6b6467-lw5t8    rabbitmq:3.7.8-management,nginx
engine-544b6b6467-tvgmg    rabbitmq:3.7.8-management,nginx
web-ui-6db964458-8pdw4     wordpress

此命令显示每个Pod的所有容器镜像的名称。

请记住，Pod可能包含多个容器。在这种情况下，单个Pod的容器镜像在同一列中显示为逗号分隔列表。

显示节点的可用区域

$kubectl get nodes \
  -o custom-columns='NAME:metadata.name,ZONE:metadata.labels.failure-domain\.beta\.kubernetes\.io/zone'
NAME                          ZONE
ip-10-0-118-34.ec2.internal   us-east-1b
ip-10-0-36-80.ec2.internal    us-east-1a
ip-10-0-80-67.ec2.internal    us-east-1b

如果您的Kubernetes群集部署在公共云基础架构（例如AWS，Azure或GCP）上，则此命令非常有用。它显示每个节点所在的可用区域。

可用区域是云的概念，表示地理区域内的一个可复制点。

每个节点的可用区域通过特殊标签failure-domain.beta.kubernetes.io/zone获得。如果集群在公共云基础结构上运行，则会自动创建此标签，并将其值设置为节点的可用区域的名称。

标签不是Kubernetes资源规范的一部分，因此您无法在API参考中找到上述标签。但是，如果将节点输出为YAML或JSON，则可以看到它（以及所有其他标签）：

$kubectl get nodes -o yaml
# or
$kubectl get nodes -o json

除了探索资源规范之外，这通常是发现有关资源的更多信息的好方法。

我的网课“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

微信赞赏：

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

我有一个习惯，那就是随时记录下编程过程中遇到的问题（包括问题现场、问题起因以及对问题的分析），并喜欢阶段性的对一段时间内的编码过程的得与失进行回顾和总结。内容可以包括：对编程语法的新认知、遇坑填坑的经历、一些让自己豁然开朗的小tip/小实践等。记录和总结的多了，感觉有价值的，就成文发在博客上的；一些小的点，或是还没有想清楚的事情，或思路没法结构化统一的，就放在资料库里备用。“写Go代码时遇到的那些问题”这个系列也是基于这个思路做的。

在这一篇中，我把“所遇到的问题”划分为三类：语言类、库与工具类、实践类，这样应该更便于大家分类阅读和理解。另外借这篇文章，我们先来看一下Go语言当前的State，资料来自于twitter、reddit、golang-dev forum、github上golang项目的issue/cl以及各种gophercon的talk资料。

零. Go语言当前状态

1. vgo

Go 1.10在中国农历春节期间正式发布。随后Go team进入了Go 1.11的开发周期。

在2017年的Go语言用户调查报告结果中，缺少良好的包管理工具以及Generics依然是Gopher面临的最为棘手的挑战和难题的Top2，Go team也终于开始认真对待这两个问题了，尤其是包依赖管理的问题。在今年2月末，Russ Cox在自己的博客上连续发表了七篇博文，详细阐述了vgo – 带版本感知和支持的Go命令行工具的设计思路和实现方案，并在3月末正式提交了”versioned-go proposal“。

目前相对成熟的包管理方案是:

"语义化版本"
+manifest文件(手工维护的依赖约束描述文件)
+lock文件(工具自动生成的传递依赖描述文件)
+版本选择引擎工具（比如dep中的gps - Go Packaging Solver）

与之相比，vgo既有继承，更有创新。继承的是对语义化版本的支持，创新的则是semantic import versioning、最小版本选择minimal version selection等新机制，不变的则是对Go1语法的兼容。按照Russ Cox的计划，Go 1.11很可能会提供一个试验性的vgo实现（当然vgo所呈现的形式估计是merge到go tools中），让广大gopher试用和反馈，然后会像vendor机制那样，在后续Go版本中逐渐成为默认选项。

2. wasm porting

知名开源项目gopherjs的作者Richard Musiol上个月提交了一个proposal: WebAssembly architecture for Go，主旨在于让Gopher也可以用Go编写前端代码，让Go编写的代码可以在浏览器中运行。当然这并不是真的让Go能像js那样直接运行于浏览器或nodejs上，而是将Go编译为WebAssembly，wasm中间字节码，再在浏览器或nodejs初始化的运行环境中运行。这里根据自己的理解粗略画了一幅二进制机器码的go app与中间码的wasm的运行层次对比图，希望对大家有用：

wasm porting已经完成了第一次commit ，很大可能会随着go1.11一并发布第一个版本。

3. 非协作式的goroutine抢占式调度

当前goroutine的“抢占式”调度依靠的是compiler在函数中自动插入的“cooperative preemption point”来实现的，但这种方式在使用过程中依然有各种各样的问题，比如：检查点的性能损耗、诡异的全面延迟问题以及调试上的困难。近期负责go runtime gc设计与实现的Austin Clements提出了一个proposal：non-cooperative goroutine preemption ，该proposal将去除cooperative preemption point，而改为利用构建和记录每条指令的stack和register map的方式实现goroutine的抢占， 该proposal预计将在go 1.12中实现。

4. Go的历史与未来

在GopherConRu 2018大会上，来自Go team的核心成员Brad Fitzpatrick做了“Go的历史与未来”的主题演讲 ，Bradfitz“爆料”了关于Go2的几个可能，考虑到Bradfitz在Go team中的位置，这些可能性还是具有很大可信度的：

1). 绝不像Perl6和Python3那样分裂社区
2). Go1的包可以import Go2的package
3). Go2很可能加入Generics，Ian Lance Taylor应该在主导该Proposal
4). Go2在error handling方面会有改进，但不会是try--catch那种形式
5). 相比于Go1，Go2仅会在1-3个方面做出重大变化
6). Go2可能会有一个新的标准库，并且该标准库会比现有的标准库更小，很多功能放到标准库外面
7). 但Go2会在标准库外面给出最流行、推荐的、可能认证的常用包列表，这些在标准库外面的包可以持续更新，而不像那些在标准库中的包，只能半年更新一次。

一. 语言篇

1. len(channel)的使用

len是Go语言的一个built-in函数，它支持接受array、slice、map、string、channel类型的参数，并返回对应类型的”长度” – 一个整型值：

len(s)   

如果s是string，len(s)返回字符串中的字节个数
如何s是[n]T, *[n]T的数组类型，len(s)返回数组的长度n
如果s是[]T的Slice类型，len(s)返回slice的当前长度
如果s是map[K]T的map类型，len(s)返回map中的已定义的key的个数
如果s是chan T类型，那么len(s)返回当前在buffered channel中排队（尚未读取）的元素个数

不过我们在代码经常见到的是len函数针对数组、slice、string类型的调用，而len与channel的联合使用却很少。那是不是说len(channel)就不可用了呢？我们先来看看len(channel)的语义。

• 当channel为unbuffered channel时，len(channel)总是返回0；
• 当channel为buffered channel时，len(channel)返回当前channel中尚未被读取的元素个数。

这样一来，所谓len(channel)中的channel就是针对buffered channel。len(channel)从语义上来说一般会被用来做“判满”、”判有”和”判空”逻辑：

// 判空

if len(channel) == 0 {
    // 这时：channel 空了 ?
}

// 判有

if len(channel) > 0 {
    // 这时：channel 有数据了 ?
}

// 判满
if len(channel) == cap(channel) {
    // 这时:   channel 满了 ?
}

大家看到了，我在上面代码中注释：“空了”、“有数据了”和“满了”的后面打上了问号！channel多用于多个goroutine间的通讯，一旦多个goroutine共同读写channel，len(channel)就会在多个goroutine间形成”竞态条件”，单存的依靠len(channel)来判断队列状态，不能保证在后续真正读写channel的时候channel状态是不变的。以判空为例：

从上图可以看到，当goroutine1使用len(channel)判空后，便尝试从channel中读取数据。但在真正从Channel读数据前，另外一个goroutine2已经将数据读了出去，goroutine1后面的读取将阻塞在channel上，导致后面逻辑的失效。因此，为了不阻塞在channel上，常见的方法是将“判空与读取”放在一起做、将”判满与写入”一起做，通过select实现操作的“事务性”：

//writing-go-code-issues/3rd-issue/channel_len.go/channel_len.go.go
func readFromChan(ch <-chan int) (int, bool) {
    select {
    case i := <-ch:
        return i, true
    default:
        return 0, false // channel is empty
    }
}

func writeToChan(ch chan<- int, i int) bool {
    select {
    case ch <- i:
        return true
    default:
        return false // channel is full
    }
}

我们看到由于用到了Select-default的trick，当channel空的时候，readFromChan不会阻塞；当channel满的时候，writeToChan也不会阻塞。这种方法也许适合大多数的场合，但是这种方法有一个“问题”，那就是“改变了channel的状态”：读出了一个元素或写入了一个元素。有些时候，我们不想这么做，我们想在不改变channel状态下单纯地侦测channel状态！很遗憾，目前没有哪种方法可以适用于所有场合。但是在特定的场景下，我们可以用len(channel)实现。比如下面这个场景：

这是一个“多producer + 1 consumer”的场景。controller是一个总控协程，初始情况下，它来判断channel中是否有消息。如果有消息，它本身不消费“消息”，而是创建一个consumer来消费消息，直到consumer因某种情况退出，控制权再回到controller，controller不会立即创建new consumer，而是等待channel下一次有消息时才创建。在这样一个场景中，我们就可以使用len(channel)来判断是否有消息。

2. 时间的格式化输出

时间的格式化输出是日常编程中经常遇到的“题目”。以前使用C语言编程时，用的是strftime。我们来回忆一下c的代码：

// writing-go-code-issues/3rd-issue/time-format/strftime_in_c.c
#include <stdio.h>
#include <time.h>

int main() {
        time_t now = time(NULL);

        struct tm *localTm;
        localTm = localtime(&now);

        char strTime[100];
        strftime(strTime, sizeof(strTime),  "%Y-%m-%d %H:%M:%S", localTm);
        printf("%s\n", strTime);

        return 0;
}

这段c代码输出结果是：

2018-04-04 16:07:00

我们看到strftime采用“字符化”的占位符(诸如：%Y、%m等)“拼”出时间的目标输出格式布局（如：”%Y-%m-%d %H:%M:%S”），这种方式不仅在C中采用，很多其他主流编程语言也采用了该方案，比如:shell、python、ruby、java等，这似乎已经成为了各种编程语言在时间格式化输出的标准。这些占位符对应的字符（比如Y、M、H）是对应英文单词的头母，因此相对来说较为容易记忆。

但是如果你在Go中使用strftime的这套“标准”，看到输出结果的那一刻，你肯定要“骂娘”！

// writing-go-code-issues/3rd-issue/time-format/timeformat_in_c_way.go
package main

import (
    "fmt"
    "time"
)

func main() {
    fmt.Println(time.Now().Format("%Y-%m-%d %H:%M:%S"))
}

上述go代码输出结果如下：

%Y-%m-%d %H:%M:%S

Go居然将“时间格式占位符字符串”原封不动的输出了!

这是因为Go另辟了蹊径，采用了不同于strftime的时间格式化输出的方案。Go的设计者主要出于这样的考虑：虽然strftime的单个占位符使用了对应单词的首字母的形式，但是但真正写起代码来，不打开strftime函数的manual或查看网页版的strftime助记符说明，很难真的拼出一个复杂的时间格式。并且对于一个”%Y-%m-%d %H:%M:%S”的格式串，不对照文档，很难在大脑中准确给出格式化后的时间结果，比如%Y和%y有何不同、%M和%m又有何差别呢？

Go语言采用了更为直观的“参考时间(reference time)”替代strftime的各种标准占位符，使用“参考时间”构造出来的“时间格式串”与最终输出串是“一模一样”的，这就省去了程序员再次在大脑中对格式串进行解析的过程：

格式串："2006年01月02日 15时04分05秒"

=>

输出结果：2018年04月04日 18时13分08秒

标准的参考时间如下：

2006-01-02 15:04:05 PM -07:00 Jan Mon MST

这个绝对时间本身并没有什么实际意义，仅是出于“好记”的考虑，我们将这个参考时间换为另外一种时间输出格式：

01/02 03:04:05PM '06 -0700

我们看出Go设计者的“用心良苦”，这个时间其实恰好是将助记符从小到大排序(从01到07)的结果，可以理解为：01对应的是%M, 02对应的是%d等等。下面这幅图形象地展示了“参考时间”、“格式串”与最终格式化的输出结果之间的关系：

就我个人使用go的经历来看，我在做时间格式化输出时，尤其是构建略微复杂的时间格式输出时，也还是要go doc time包或打开time包的web手册的。从社区的反馈来看，很多Gopher也都有类似经历，尤其是那些已经用惯了strftime格式的gopher。甚至有人专门做了“Fucking Go Date Format”页面，来帮助自动将strftime使用的格式转换为go time的格式。

下面这幅cheatsheet也能提供一些帮助(由writing-go-code-issues/3rd-issue/time-format/timeformat_cheatsheet.go输出生成)：

二. 库与工具篇

1. golang.org/x/text/encoding/unicode遇坑一则

在gocmpp这个项目中，我用到了unicode字符集转换：将utf8转换为ucs2(utf16)、ucs2转换为utf8、utf8转为GB18030等。这些转换功能，我是借助golang.org/x/text这个项目下的encoding/unicode和transform实现的。x/text是golang官方维护的text处理的工具包，其中包含了对unicode字符集的相关操作。

要实现一个utf8到ucs2(utf16)的字符集转换，只需像如下这样实现即可（这也是我的最初实现）：

func Utf8ToUcs2(in string) (string, error) {
    if !utf8.ValidString(in) {
        return "", ErrInvalidUtf8Rune
    }

    r := bytes.NewReader([]byte(in))

    //UTF-16 bigendian, no-bom
    t := transform.NewReader(r, unicode.All[1].NewEncoder())
    out, err := ioutil.ReadAll(t)
    if err != nil {
        return "", err
    }
    return string(out), nil
}

这里要注意是unicode.All这个切片保存着UTF-16的所有格式：

var All = []encoding.Encoding{
    UTF16(BigEndian, UseBOM),
    UTF16(BigEndian, IgnoreBOM),
    UTF16(LittleEndian, IgnoreBOM),
}

这里我最初我用的是All[1]，即UTF16(BigEndian, IgnoreBOM)，一切都是正常的。

但就在年前，我将text项目更新到最新版本，然后发现单元测试无法通过：

--- FAIL: TestUtf8ToUcs2 (0.00s)
    utils_test.go:58: The first char is fe, not equal to expected 6c
FAIL
FAIL    github.com/bigwhite/gocmpp/utils    0.008s

经查找发现：text项目的golang.org/x/text/encoding/unicode包做了不兼容的修改，上面那个unicode.All切片变成了下面这个样子：

// All lists a configuration for each IANA-defined UTF-16 variant.
var All = []encoding.Encoding{
    UTF8,
    UTF16(BigEndian, UseBOM),
    UTF16(BigEndian, IgnoreBOM),
    UTF16(LittleEndian, IgnoreBOM),
}

All切片在最前面插入了一个UTF8元素，这样导致我的代码中原本使用的 UTF16(BigEndian, IgnoreBOM)变成了UTF16(BigEndian, UseBOM)，test不过也就情有可原了。

如何改呢？这回儿我直接使用UTF16(BigEndian, IgnoreBOM)，而不再使用All切片了：

func Utf8ToUcs2(in string) (string, error) {
    if !utf8.ValidString(in) {
        return "", ErrInvalidUtf8Rune
    }

    r := bytes.NewReader([]byte(in))
    //UTF-16 bigendian, no-bom
    t := transform.NewReader(r,
            unicode.UTF16(unicode.BigEndian, unicode.IgnoreBOM).NewEncoder())
    out, err := ioutil.ReadAll(t)
    if err != nil {
        return "", err
    }
    return string(out), nil
}

这样即便All切片再有什么变动，我的代码也不会受到什么影响了。

2. logrus的非结构化日志定制输出

在该系列的第一篇文章中，我提到过使用logrus+lumberjack来实现支持rotate的logging。

默认情况下日志的输出格式是这样的（writing-go-code-issues/3rd-issue/logrus/logrus2lumberjack_default.go）：

time="2018-04-05T06:08:53+08:00" level=info msg="logrus log to lumberjack in normal text formatter"

这样相对结构化的日志比较适合后续的集中日志分析。但是日志携带的“元信息(time、level、msg)”过多，并不是所有场合都倾向于这种日志，于是我们期望以普通的非结构化的日志输出，我们定制formatter：

// writing-go-code-issues/3rd-issue/logrus/logrus2lumberjack.go
func main() {
    customFormatter := &logrus.TextFormatter{
        FullTimestamp:   true,
        TimestampFormat: "2006-01-02 15:04:05",
    }
    logger := logrus.New()
    logger.Formatter = customFormatter

    rotateLogger := &lumberjack.Logger{
        Filename: "./foo.log",
    }
    logger.Out = rotateLogger
    logger.Info("logrus log to lumberjack in normal text formatter")
}

我们使用textformatter，并定制了时间戳的格式，输出结果如下：

time="2018-04-05 06:22:57" level=info msg="logrus log to lumberjack in normal text formatter"

日志仍然不是我们想要的那种。但同样的customFormatter如果输出到terminal，结果却是我们想要的：

//writing-go-code-issues/3rd-issue/logrus/logrus2tty.go

INFO[2018-04-05 06:26:16] logrus log to tty in normal text formatter

到底如何设置TextFormatter的属性才能让我们输出到lumberjack中的日志格式是我们想要的这种呢？无奈下只能挖logrus的源码了，我们找到了这段代码：

//github.com/sirupsen/logrus/text_formatter.go

// Format renders a single log entry
func (f *TextFormatter) Format(entry *Entry) ([]byte, error) {
    ... ...
    isColored := (f.ForceColors || f.isTerminal) && !f.DisableColors

    timestampFormat := f.TimestampFormat
    if timestampFormat == "" {
        timestampFormat = defaultTimestampFormat
    }
    if isColored {
        f.printColored(b, entry, keys, timestampFormat)
    } else {
        if !f.DisableTimestamp {
            f.appendKeyValue(b, "time", entry.Time.Format(timestampFormat))
        }
        f.appendKeyValue(b, "level", entry.Level.String())
        if entry.Message != "" {
            f.appendKeyValue(b, "msg", entry.Message)
        }
        for _, key := range keys {
            f.appendKeyValue(b, key, entry.Data[key])
        }
    }

    b.WriteByte('\n')
    return b.Bytes(), nil
}

我们看到如果isColored为false，输出的就是带有time, msg, level的结构化日志；只有isColored为true才能输出我们想要的普通日志。isColored的值与三个属性有关：ForceColors 、isTerminal和DisableColors。我们按照让isColored为true的条件组合重新设置一下这三个属性，因为输出到file，因此isTerminal自动为false。

//writing-go-code-issues/3rd-issue/logrus/logrus2lumberjack_normal.go
func main() {
    //    isColored := (f.ForceColors || f.isTerminal) && !f.DisableColors
    customFormatter := &logrus.TextFormatter{
        FullTimestamp:   true,
        TimestampFormat: "2006-01-02 15:04:05",
        ForceColors:     true,
    }
    logger := logrus.New()
    logger.Formatter = customFormatter

    rotateLogger := &lumberjack.Logger{
        Filename: "./foo.log",
    }
    logger.Out = rotateLogger
    logger.Info("logrus log to lumberjack in normal text formatter")
}

我们设置ForceColors为true后，在foo.log中得到了我们期望的输出结果：

INFO[2018-04-05 06:33:22] logrus log to lumberjack in normal text formatter

三. 实践篇

1. 说说网络数据读取timeout的处理 – 以SetReadDeadline为例

Go天生适合于网络编程，但网络编程的复杂性也是有目共睹的、要写出稳定、高效的网络端程序，需要的考虑的因素有很多。比如其中之一的：从socket读取数据超时的问题。

Go语言标准网络库并没有实现epoll实现的那样的“idle timeout”，而是提供了Deadline机制，我们用一副图来对比一下两个机制的不同：

看上图a)和b)展示了”idle timeout”机制，所谓idle timeout就是指这个timeout是真正在没有data ready的情况的timeout（如图中a)，如果有数据ready可读(如图中b)，那么timeout机制暂停，直到数据读完后，再次进入数据等待的时候，idle timeout再次启动。

而deadline(以read deadline为例)机制，则是无论是否有数据ready以及数据读取活动，都会在到达时间（deadline）后的再次read时返回timeout error，并且后续的所有network read operation也都会返回timeout（如图中d），除非重新调用SetReadDeadline(time.Time{})取消Deadline或在再次读取动作前重新重新设定deadline实现续时的目的。Go网络编程一般是“阻塞模型”，那为什么还要有SetReadDeadline呢，这是因为有时候，我们要给调用者“感知”其他“异常情况”的机会，比如是否收到了main goroutine发送过来的退出通知信息。

Deadline机制在使用起来很容易出错，这里列举两个曾经遇到的出错状况：

a) 以为SetReadDeadline后，后续每次Read都可能实现idle timeout

在上图中，我们看到这个流程是读取一个完整业务包的过程，业务包的读取使用了三次Read调用，但是只在第一次Read前调用了SetReadDeadline。这种使用方式仅仅在Read A时实现了足额的“idle timeout”，且仅当A数据始终未ready时会timeout；一旦A数据ready并已经被Read，当Read B和Read C时，如果还期望足额的“idle timeout”那就误解了SetReadDeadline的真正含义了。因此要想在每次Read时都实现“足额的idle timeout”，需要在每次Read前都重新设定deadline。

b) 一个完整“业务包”分多次读取的异常情况的处理

在这幅图中，每个Read前都重新设定了deadline，那么这样就一定ok了么？对于在一个过程中读取一个“完整业务包”的业务逻辑来说，我们还要考虑对每次读取异常情况的处理，尤其是timeout发生。在该例子中，有三个Read位置需要考虑异常处理。

如果Read A始终没有读到数据，deadline到期，返回timeout，这里是最容易处理的，因为此时前一个完整数据包已经被读完，新的完整数据包还没有到来，外层控制逻辑收到timeout后，重启再次启动该读流程即可。

如果Read B或Read C处没有读到数据，deadline到期，这时异常处理就棘手一些，因为一个完整数据包的部分数据（A）已经从流中被读出，剩余的数据并不是一个完整的业务数据包，不能简单地再在外层控制逻辑中重新启动该过程。我们要么在Read B或Read C处尝试多次重读，直到将完整数据包读取完整后返回；要么认为在B或C处出现timeout是不合理的，返回区别于A处的错误码给外层控制逻辑，让外层逻辑决定是否是连接存在异常。

注：本文所涉及的示例代码，请到这里下载。

微博：@tonybai_cn
微信公众号：iamtonybai
github.com: https://github.com/bigwhite

微信赞赏：