Go标准库flag包的“小陷阱”

本文永久链接 – https://tonybai.com/2021/04/12/pitfall-in-std-flag-pkg

Go语言号称“自带电池(battery-included)”,这意味着Go标准库可开箱即用,为Gopher提供了功能丰富的常用工具包,足以应付多数日常开发所需。尤其在Go语言擅长的领域,Go标准库工具包更是有着广泛的应用。下图是Go官方2020年用户调查的结果:

我们看到cli(command-line interface)领域开发占据了Go语言应用的Top2位置,仅次于开发API/RPC服务。而普通cli应用的开发总是离不开标准库的flag包。

flag包估计是很多gopher入门go语言的必经之路。flag使用起来十分简单,功能也不差,常规的命令行程序的flag形式它都支持,比如下面这个示例程序:

// flag_demo1.go
package main

import (
    "flag"
    "fmt"
)

var (
    n = flag.Int("n", 1234, "help message for flag n")
)

func main() {
    flag.Parse()
    fmt.Printf("n=%d\n", *n)
}

flag_demo1仅支持一个cmd flag: -n。我们可以像下面这样使用flag_demo1这个cli程序,为变量n传值:

$go build flag_demo1.go

$./flag_demo1
n=1234 //默认值

$./flag_demo1 -n 1111
n=1111

$./flag_demo1 --n 1111
n=1111 // --n和-n是等价的

$./flag_demo1 -n=2222
n=2222

$./flag_demo1 --n=2222
n=2222

我们看到,我们可以使用下面四种形式为一个整型flag变量传参数:

  • -n value
  • –n value
  • -n=value
  • –n=value

无论使用哪种形式,它们起到的效果是等价的。

但是当我们将flag放置在cli应用的最后面时,我们要小心了:

$./flag_demo1 show -n=2222
n=1234

我们看到虽然我们在命令行因公flag_demo1的参数列表中进行了-n=2222的参数传递,但flag_demo1的flag包直接无视了这次参数传递,而将变量n置为默认值1234了。

这是因为flag包的命令行参数的解析逻辑是:当碰到第一个非flag参数时,便停止解析。上面命令行执行时传入的“show”并非flag_demo1的flag参数,因此flag包就会在解析完show后停止后面命令行参数(-n=2222)的解析,于是上述命令行就等价于:

$./flag_demo1 show
n=1234

那么n=1234就不足为奇了!这被我称为flag包的第一个“小陷阱”。不仅像“show”这样的非flag参数可以阻断flag包对命令行参数列表的继续解析,单独存在的“-”和“–”也具有同样的“阻断功能”:

$./flag_demo1 -- -n=2222
n=1234
$./flag_demo1 - -n=2222
n=1234

我们也常在命令行flag参数中使用bool类的参数值,比如下面示例:

// flag_demo2.go

package main

import (
    "flag"
    "fmt"
)

var (
    n  = flag.Int("n", 1234, "int value for flag n")
    b1 = flag.Bool("b1", false, "bool value for flag b1")
    b2 = flag.Bool("b2", false, "bool value for flag b2")
)

func main() {
    flag.Parse()
    fmt.Printf("n=%d\n", *n)
    fmt.Printf("b1=%t\n", *b1)
    fmt.Printf("b2=%t\n", *b2)
}

这个示例中有两个bool型flag参数和一个int型flag参数,我们来运行一下该cli应用:

$go build flag_demo2.go
$./flag_demo2 -b1 true -b2 true -n 2222
n=1234
b1=true
b2=false

运行的输出似乎与预期结果不符啊!为什么b2变量的值依旧为false,变量n的值为啥不是2222?难道在多个flag参数下,flag包有bug?其实不是的!

问题就在于bool类型flag参数的特殊性。由于一些原因,bool类型flag参数不支持“-arg value”形式,只支持下面两种形式:

-arg
-arg=value

我们按bool类型flag参数的正确传递方法再运行一下上面的flag_demo2:

$./flag_demo2 -b1=true -b2=true -n 2222
n=2222
b1=true
b2=true

这回的输出与预期吻合。

但细心的朋友可能会发现,之前的错误用法:

$./flag_demo2 -b1 true -b2 true -n 2222

十分有迷惑性!因为变量b1的输出值是符合预期的,这让人误以为flag参数的传递方法是正确无误的。这种“错觉”让gopher不知不觉地掉入了flag包的第二个“陷阱”中。而上面的错误flag参数值传递实质上等价于:

$./flag_demo2 -b1

这就是为什么b1=true,而b2和n均为默认值的原因了!

flag包是我们日常最广泛使用的标准库包之一,因此务必了解flag包可能被误用的情况,别掉入flag包的“小陷阱”中!陷阱虽小,出事是大,希望这里的分享能帮助大家在日常绕过这些“陷阱”!


“Gopher部落”知识星球正式转正(从试运营星球变成了正式星球)!“gopher部落”旨在打造一个精品Go学习和进阶社群!高品质首发Go技术文章,“三天”首发阅读权,每年两期Go语言发展现状分析,每天提前1小时阅读到新鲜的Gopher日报,网课、技术专栏、图书内容前瞻,六小时内必答保证等满足你关于Go语言生态的所有需求!部落目前虽小,但持续力很强。在2021年上半年,部落将策划两个专题系列分享,并且是部落独享哦:

  • Go技术书籍的书摘和读书体会系列
  • Go与eBPF系列

欢迎大家加入!

Go技术专栏“改善Go语⾔编程质量的50个有效实践”正在慕课网火热热销中!本专栏主要满足广大gopher关于Go语言进阶的需求,围绕如何写出地道且高质量Go代码给出50条有效实践建议,上线后收到一致好评!欢迎大家订
阅!

img{512x368}

我的网课“Kubernetes实战:高可用集群搭建、配置、运维与应用”在慕课网热卖>中,欢迎小伙伴们订阅学习!

img{512x368}

我爱发短信:企业级短信平台定制开发专家 https://tonybai.com/。smspush : 可部署在企业内部的定制化短信平台,三网覆盖,不惧大并发接入,可定制扩展; 短信内容你来定,不再受约束, 接口丰富,支持长短信,签名可选。2020年4月8日,中国三大电信运营商联合发布《5G消息白皮书》,51短信平台也会全新升级到“51商用消息平台”,全面支持5G RCS消息。

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

Gopher Daily(Gopher每日新闻)归档仓库 – https://github.com/bigwhite/gopherdaily

我的联系方式:

  • 微博:https://weibo.com/bigwhite20xx
  • 微信公众号:iamtonybai
  • 博客:tonybai.com
  • github: https://github.com/bigwhite
  • “Gopher部落”知识星球:https://public.zsxq.com/groups/51284458844544

微信赞赏:
img{512x368}

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

Go语言“十诫”[译]

本文永久链接 – https://tonybai.com/2021/04/09/ten-commandments-of-go

本文翻译自John Arundel的《Ten commandments of Go》。全文如下:

作为一名全职的Go语言作家老师,我花了很多时间和学生们一起,帮助他们写出更清晰、更好、更有用的Go程序。我发现,我给他们的建议可以归纳总结为一套通用原则,在这里我将这些原则分享给大家。

1. 你应该是无聊的

Go社区喜欢共识(consensus)。比如:Go源代码有一个由gofmt强制执行的统一的代码格式规范。同样,无论你要解决什么问题,通常都有一个标准的、类似于Go行事风格的方法来解决。有时它是标准的方式,因为它是最好的方式,但通常它只是最好的方式,因为它是标准的方式

要抵制住创意、时尚或(最糟糕的是)聪明的诱惑,这些不是Go的行事风格。Go行事风格的代码简单、无聊,通常相当啰嗦,而且最重要的是显式的风格(由于这个原因,有些人把Go称为面向显式(obviousness-oriented)风格的编程语言)。

当有疑问时,请遵循最小惊喜原则。争取做到一目了然。要直截了当,要简单,要显式,要无聊。

这并不是说在软件工程层面没有展示令人叹为观止的优雅和风格的空间了;当然有。但那是在设计层面上,而不是单个代码行。代码并不重要,它应该以被随时替换。重要的是程序。

2. 你应该以测试为先

在Go中,一个常见的错误是先写了一些函数(比如:GetDataFromAPI),然后在考虑如何测试它时不知所措。函数通过网络进行了真正的API调用,它向终端打印东西,它写磁盘文件了,这是一个可怕的的不可测试性的坑。

不要先写那个函数,而是先写一个测试(比如:TestGetDataFromAPI)。如何写这样一个测试呢?它必须为函数的调用提供一个本地的TLS测试服务器,所以你需要一种方法来注入这种依赖。它要写数据到io.Writer,你同样需要为此注入一个模拟外部世界的本地依赖,比如:bytes.Buffer。

现在,当你开始编写GetDataFromAPI函数时,一切都将变得很容易了。它的所有依赖关系都被注入,所以它的业务逻辑与它与外部世界的交互和监听方式完全脱钩。

HTTP handler也是如此。一个HTTP handler的唯一工作是解析请求中的数据,将其传递给某个业务逻辑函数来计算结果,并将结果格式化到ResponseWriter。这几乎不需要测试,所以你的大部分测试将在业务逻辑函数本身,而不是handler。我们知道HTTP的工作原理。

3. 你应该测试行为,而不是函数

如果你想知道如何在不实际调用API的情况下测试这个函数,那么答案很简单:”不要测试这个函数”。

你需要测试的不是一些函数,而是一些行为。例如,一个可能是”给定一些用户输入,我可以正确地组合URL并以正确的参数调用API。” 另一个可能是”给定API返回的一些JSON数据,我可以正确地将其解包到某个Go结构体中。”

当你沿着这样的思路考量问题的解决方法的时候,写测试就容易多了:你可以想象一些这类函数,它们每个函数都会接受一些输入,并产生一些输出,并且很容易给它们编写单元测试。有些事情它们是不会做的,例如进行任何HTTP调用。

同样,当你试图实现”数据可以持久地存储在数据库中并从数据库中检索”这样的行为时,你可以将其分解成更小的、更可测试的行为。例如,”给定一个Go结构体,我可以正确地生成SQL查询,并将其内容存储到Postgres表中”,或者 “给定一个对象,我可以正确地将结果解析到Go结构体切片中”。不需要mock数据库,不需要真正的数据库!

4. 你不应制造文书工作

所有的程序都会在某一点上涉及到一些繁琐的、不可避免的数据倒换重组活动;我们可以把所有这类活动归入文书工作的范畴。对程序员来说,唯一的问题是,这些文书工作在API边界的哪一边?

如果是放在用户侧,那就意味着用户必须编写大量的代码来为你的库准备文书工作,然后再编写大量的代码来将结果解压成有用的格式。

相反(将文书工作放在API实现侧),写零文书工作的库,可以在一行中调用:

game.Run()

不要让用户调用一个构造函数来获取某个对象,然后再基于这个对象进行方法调用。那就是文书工作。只要让一切在他们直接调用时发生就可以了。如果有可配置的设置,请设置合理的默认值,这样用户根本不用考虑,除非他们因为某些原因需要覆盖默认值。功能选项(functional option)是一个很好的模式。

这是另一个先写测试的好理由,如果你写的API中创造了文书工作,那么在测试时你将不得不自己做所有的文书工作,以便使用你自己的库。如果这被证明是笨拙、啰嗦和耗时的,可以考虑将这些文书工作移到API边界内。

5. 你不应该杀死程序

你的库没有权利终止用户的程序。不要在你的包中调用像os.Exit、log.Fatal、panic这样的函数,这不是你能决定的。相反,如果你遇到了不可恢复(recover)的错误,将它们返回给调用者。

为什么不呢?因为它迫使任何想使用你的库的人去写代码,不管panic是否真的被触发。出于同样的原因,你永远不应该使用会引起panic的第三方库,因为一旦你用了,你就需要recover它们。

所以你千万不要显式调用(这些可以杀死程序的函数),但是隐式调用呢?你所做的任何操作,在某些情况下可能会panic(比如:索引一个空的片断,写入一个空map,类型断言失败)都应该先检查一下是否正常,如果不正常就返回一个错误。

6. 你不要泄露资源

对于一个打算永远运行而不崩溃或出错的程序来说,对其的要求要比对单次命令行工具要严格一些。例如,想想太空探测器:在关键时刻意外重启制导系统,可能会让价值数十亿美元的飞行器驶向星系间的虚空。对于负责的软件工程师来说,这很可能会导致一场没有咖啡的面谈,让人有些不舒服。

我们不是都在为太空器写软件,但我们应该像太空工程师一样思考。自然,我们的程序应该永远不会崩溃(最坏的情况下,它们应该优雅地退化,并提出退出过程的详实信息),但它们也需要是可持续的。这意味着不能泄露内存、goroutines、文件句柄或任何其他稀缺资源。

每当你有一些可泄漏的资源时,当你知道你已经成功获得它的那一刻,你应该想着释放它。无论函数如何退出或何时退出,保证将其清理掉,我们可以用Go带给我们的礼物:defer

任何时候启动一个goroutine,你都应该知道它是如何结束的。启动它的同一个函数应该负责停止它。使用waitgroups或者errgroups,并且总是向一个可能被取消的函数传递一个context.Context。

7. 你不应该限制用户的选择

我们如何编写友好、灵活、强大、易用的库呢?一种方法是避免不必要地限制用户对库的操作。一个常见的Gopherism(Go主义)是 “接受接口,返回结构”。但为什么这是个好建议呢?

假设你有一个函数,接受类似于一个*os.File的参数 ,并向其写入数据。也许被写入的东西是一个文件并不重要,具体来说,它只需要是一个 “你可以写入的东西”(这个想法由标准库接口,如io.Writer表达)。有很多这样的东西:网络连接、HTTP response writer、bytes.Buffer等等。

通过强迫用户传递给你一个文件,你限制了他们对你的库的使用。通过接受一个接口(如 io.Writer)来代替,你将打开新的可能性,包括尚未被创造的类型,后续它们仍然可以满足(接口) ,可以与你的代码io.Writer一起工作。

为什么要 “返回结构体”?好吧,假设你返回一些接口类型。这极大地限制了用户对该值的操作(他们能做的就是调用其上的方法)。即使他们事实上可以用底层的具体类型做他们需要做的事情,他们也必须先用类型断言来解包它。换句话说,这就是额外的文书工作(应该避免)。

另一种避免限制用户选择的方法是不要使用只有当前Go版本才有的功能。相反,考虑至少支持最近两个主要的Go版本:有些人不能立即升级。

8. 你应该设定边界

让每一个软件组件在自己的内部是完整的、有能力的;不要让它的内部关注点暴露出来,越过它的边界渗入到其他组件中。这一点对于与其他人的代码的边界来说,是双倍的。

例如,假设你的库调用了某个API。这个API会有自己的模式和自己的词汇,反映自己的关注点和自己的领域语言。

边界是那些与你的代码接触的点:例如,调用API并解析其响应的函数。我把它称为 “airlock “函数,因为它的工作部分是确保你的内部类型和关注点不会泄露出去,并防止外来数据泄露进来。

一旦你让一点外来数据在你的程序内部自由运行,它很快就会到处乱跑。你的其他包都需要导入这些外来类型,这很烦人,而且代码将会有一股糟糕的味道。

相反,你的airlock函数应该做两件事:它应该将外来数据转化为你自己的内部格式,而且应该确保数据是有效的。现在,你的所有其他代码只需要处理你的内部类型,它不需要担心数据是否会出错、丢失或不完整。

另一种执行良好边界的方法是始终检查错误。如果你不这样做,无效的数据可能会泄露进来。

9. 你不应该在内部使用接口

一个接口值说:”我不知道这个东西到底是什么,但也许我知道有些事情我可以用它来做。” 这在Go程序中是一种超级不方便的值,因为我们不能做任何没有被接口指定的事情。

对于空接口(interface{})来说,这也是双倍的,因为我们对它一无所知。因此,根据定义,如果你有一个空的接口值,你需要把它类型化为具体的东西才能使用它。

在处理任意数据(也就是在运行时类型或模式未知的数据)时,不得不使用它们是很常见的,比如无处不在的map[string]interface{}。但是,我们应该尽快使用airlock将这一团无知转化为某种具体类型的有用的Go值。

特别是,不要用interface{}类型值来模拟泛型(Go有泛型)。不要写一个函数,接受一些可以是七种具体类型之一的值,然后对其进行类型转换,为该类型找到合适的操作。相反,写七个函数,每个具体类型一个。

不要仅因为你可以在测试中注入mock,就创建一个公共的接口,这是一个错误。创建一个真正的用户在调用你的函数之前必须实现的接口,这违反了“无文书工作原则”。不要在一般情况下写mock;Go不适合这种风格的测试。(当Go中的某些东西很困难时,这通常是你做错事的标志。)

10. 你不要盲目地遵从诫命,而要自己思考

人们说:”告诉我们什么是最佳做法”,仿佛有一本小秘籍,里面有任何技术或组织问题的正确答案。(是有的,但不要说出去。我们不希望每个人都成为顾问)。

小心任何看似清楚、明确、简单地告诉你在某种情况下该怎么做的建议。它不会适用于每一种情况,在适用的地方,它都需要告诫,需要细微的差别,需要澄清。

每个人都希望得到的是不需要真正理解就能应用的建议。但这样的建议比它能带来的帮助更危险:它能让你走到桥的一半,然后你会发现桥是纸做的,而且刚开始下雨。


非常感谢比尔-肯尼迪(Bill Kennedy)伊南克-古姆斯(Inanc Gumus)对这篇文章的有益评论。


“Gopher部落”知识星球正式转正(从试运营星球变成了正式星球)!“gopher部落”旨在打造一个精品Go学习和进阶社群!高品质首发Go技术文章,“三天”首发阅读权,每年两期Go语言发展现状分析,>每天提前1小时阅读到新鲜的Gopher日报,网课、技术专栏、图书内容前瞻,六小时内必答保证等满足你关于Go语言生态的所有需>求!部落目前虽小,但持续力很强。在2021年上半年,部落将策划两个专题系列分享,并且是部落独享哦:

  • Go技术书籍的书摘和读书体会系列
  • Go与eBPF系列

欢迎大家加入!

Go技术专栏“改善Go语⾔编程质量的50个有效实践”正在慕课网火热热销中!本专栏主要满足广大gopher关于Go语言进阶的需求,围绕如何写出地道且高质量Go代码给出50条有效实践建议,上线后收到一致好评!欢迎大家订
阅!

img{512x368}

我的网课“Kubernetes实战:高可用集群搭建、配置、运维与应用”在慕课网热卖中,欢迎小伙伴们订阅学习!

img{512x368}

我爱发短信:企业级短信平台定制开发专家 https://tonybai.com/。smspush : 可部署在企业内部的定制化短信平台,三网覆盖,不惧大并发接入,可定制扩展; 短信内容你来定,不再受约束, 接口丰富,支持长短信,签名可选。2020年4月8日,中国三大电信运营商联合发布《5G消息白皮书》,51短信平台也会全新升级到“51商用消息平台”,全面支持5G RCS消息。

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

Gopher Daily(Gopher每日新闻)归档仓库 – https://github.com/bigwhite/gopherdaily

我的联系方式:

  • 微博:https://weibo.com/bigwhite20xx
  • 微信公众号:iamtonybai
  • 博客:tonybai.com
  • github: https://github.com/bigwhite
  • “Gopher部落”知识星球:https://public.zsxq.com/groups/51284458844544

微信赞赏:
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