Sarah Adams谈Test2Doc与Women Who Go

我是莎拉·亚当斯，欢迎收听Go Time。

I'm Sarah Adams, and this is Go Time.

Go Time是一档每周播出的播客，我们在这里讨论与Go编程语言、社区以及相关的一切有趣话题。

It's Go Time, a weekly podcast where we discuss interesting topics around the Go programming language, the community, and everything in between.

如果你目前正在使用Go，或者希望学习Go，那么这档节目非常适合你。

If you currently write Go or aspire to, this is the show for you.

好了，各位。

Alright, everybody.

欢迎再次收听Go Time的另一期节目。

Welcome back for another episode of Go Time.

这是第五期节目。

This is episode number five.

今天，我们请来了布莱恩·凯特尔森。

Today, we have Brian Kettleson here.

打个招呼吧，布莱恩。

Say hello, Brian.

但我并不在这里。

I'm not here though.

我这周在旧金山。

I'm in San Francisco this week.

你好。

Hello.

确实如此，你有一部分在这里。

That's very true, you're part here.

反正你也不在，这全是虚拟演播室。

You're not here anyway, this is all virtual studio.

没错。

That's true.

我们这里还有卡莉西亚。

We also have Carlicia here.

我也不在那里，我在圣地亚哥。

I am also not there, I am in San Diego.

大家好。

Hello everybody.

今天节目中，我们有一位特别嘉宾，莎拉·亚当斯，你们大多数人认识她，她是工程师、演讲者，也是“女性去Go”组织的创始人。

And today on the show we have a special guest with us, Sarah Adams, who most of you know as engineer, speaker and also the founder of Woman Who Go.

嗨。

Hi.

你好吗，莎拉？

How are you Sarah?

我也在一个城市，旧金山。

I'm in a city too, San Francisco.

所以今天所有人都在加利福尼亚，就我不在吗？

So is everybody in California but me today?

没错。

That's correct.

听起来是这样。

Sounds like it.

我知道我被排除在外了。

I knew I was getting left out here.

埃里克，我们这儿可是严重怕错过啊。

We have some serious FOMO going on Eric.

害怕错过。

Fear of missing out.

但你看，我可比你们先吃晚饭。

But see, I'll be having dinner before you guys though.

我们结束后，我的工作就少了。

I have less work when we're done.

你知道吗，在外面的问题是，我孩子会在凌晨三点给我发短信。

You know, the problem with being out here is that my kids start sending me text messages at three in the morning.

哦，是啊。

Oh yeah.

是啊，和孩子及家人同步时间总是挺难的。

Yeah, that's always rough to get kinda like synced up with the kids and family.

整个事情是，你以为三个小时不算长，但其实像过了一辈子。

The whole thing is, you think three hours isn't that long, but it's a lifetime.

确实很多，没错。

It's a lot, it is.

当你吃晚饭时，大家都已经睡觉了；当你起床时，大家已经开始吃午饭了。

Everybody's going to bed before you're having dinner and everybody's like having lunch when you're waking up.

那是什么？

What's that?

这周我们有很多事情要谈。

We've got a lot to talk about this week.

我觉得我们应该直接开始。

I think we should dive in.

发生了很多事。

A lot happening.

是的，上周我们聊了一点关于1.7版本的内容，以及其中一些性能改进。

Yeah, so last week we talked a bit about the 1.7 stuff and some of the performance change improvements there.

在过去这一周里，Dave Cheney 制作了一些关于这些改进的可视化图表，真的让我大吃一惊，因为我虽然知道有改进，但没想到我们已经消除了百分之十四和百分之十六之间一半以上甚至更多的差距。

And over this past week, Dave Cheney put together some visualizations of that which really kind of blew my mind because I knew there was improvements but we've cut what, less than half or more than half the difference between one point four and one point six out of the way.

我的意思是，我们正在回到以前的水平。

I mean we're We're getting back to where we were.

这太棒了，因为 Go 的编译速度本来就很棒，现在又能恢复到不可思议的快速水平，真让人高兴。

Which is fabulous because Go has really great compile times and it's nice to see that coming back down to insanely great.

然后我期待看到编译速度能降到比 1.4 还要快。

And then I'm looking forward to seeing it pre or less than one four.

那将是一个了不起的成就。

That'd be a great achievement.

想象一下，速度甚至能超过 1.4 时的水平。

Imagine being even faster than one four was.

这可能吗？

Is it even possible?

有这个可能吗？

Is it on the cards

只要有SSA，一切皆有可能，你有看过负责这个的团队吗？

Anything's possible with SSA and have you seen the team working on that?

这群天才一定会让这事成真。

The brain trust will make it happen.

我有，谁在

I have Who's

负责这个？

working on it?

我正想是谁在具体负责这个功能，就是那个SSA相关的，你还记得Brian吗？具体是哪个团队在做SSA的工作？

I'm trying to think of who's specifically working on that functionality, see that one I Do you remember Brian, who the specific team was working on the SSA stuff?

我不清楚整个团队的名单，不记得了。

I don't know the whole list of team, no.

那我们查一下，然后放到节目笔记里。

So we'll look that up and then we'll put it in the show notes.

这周另一个大新闻是，context包现在将被纳入标准库。

So other big news this week, the context package is now going to be in standard live.

这太重要了，非常重要。

This is huge, huge.

我对此非常兴奋。

I'm so excited about it.

是的，我也非常兴奋。

Yeah, I'm really excited.

他们设计的方式真的很棒，如果你使用的是 1.7 版本，它会使用标准库中的那个；如果你没有使用 1.7，它将继续使用 net 包中的那个。

The way that they've engineered it is really nice too so that if you're using 1.7, it'll use the one in standard lib and if you're not using 1.7, it will continue to use the one in the net package.

这真是太棒了。

So that's really awesome.

是的，这太棒了，因为 gRPC 和所有那些东西都依赖于 context 包，我们已经用了很久了，久得我都记不清了。

Yeah, that's fantastic because gRPC and all that stuff depends on the context package and we've been using that for, I don't even know how long that's been floating around.

我很高兴看到它被正式纳入了。

I'm really glad to see it kind of pulled in.

还有，莎拉，你刚才提到过 context 包的事？

And Sarah, you were saying something about a context package?

是的，不，我只是很高兴它能进入标准库。

Yeah, no, I'm just excited for it to be in the standard library.

真是个不错的补充。

Just cool addition.

希望更多人会在他们的包中使用它，尤其是在处理网络请求之类功能时，因为它的真正强大之处在于能够将上下文一直传递下去，以便你随时可以取消所有操作。

And hopefully a lot more people will start using it as part of their packages where they expose kind of network requests and things like that, because that's really the power in it is having the context kind of forwarded along so that you can stop it anywhere All in

各位库开发者，如果你们还没有把上下文作为公共函数的第一个参数，现在是开始这样做的绝佳时机，请务必这样做。

you library developers out there, if you're not putting context as the first parameter of your public functions, now is a great time to start doing that please.

重点是

The emphasis

我想说的是，请务必这样做。

Please, is on wanted to say please.

我不想显得太专横。

I don't want to sound too bossy.

我有时候可能会给人这种感觉。

I can come across that way sometimes.

根据我有限的Go语言使用经验，我经常看到人们使用其他网络包只是为了能获取上下文，我甚至也这么做过，因为我懒得亲手做这些事情。

And from my little experience, from the little experience that I have with Go, I see a lot of times when people use other network packages just so they can get the context, and I would even do that because I don't wanna do that stuff by hand.

但现在它已经进入标准库了，我不禁想知道，这会对其他外部库的使用产生多大影响，或者人们是否还得不断添加新功能，让这些库对用户更有吸引力。

But now that it's in the standard library, I just I wonder how it's if it's going to impact the usage of other, their external libraries, or if people are just gonna have to keep ahead and keep adding more features to make it more attractive for people to use them.

但话说回来，这真的算竞争吗？

But I mean, is it really a competition though?

我认为归根结底，关键是写出高质量且可读性强的软件。

I think at the end of the day, it's about writing good quality software and that's readable.

我认为，只要有人真正喜欢某些外部库，我们就能在这些模式上达成共识。

And I think that by having external libraries that people really like, and we kind of get consensus on these patterns.

我觉得把这些东西纳入标准库是可以的，因为并非每个人都会注意到这些特性，哪怕我们认为它们已经很有曝光度了。

I think it's okay to pull that stuff in because not everybody's gonna be aware of these things despite how much visibility we think they have.

而人们通常首先会去标准库中寻找工具。

Whereas people find stuff in the standard library, that's generally where people look first.

所以我觉得这是一个很难争论的问题，对吧？

So I think it's a hard debate, right?

我们某种程度上把用户从一些标准库中拉走了，但我认为这些库的维护者看到它被纳入标准库应该会很高兴。

We're kind of pulling away users from some standard library, but I think that the library owners are probably glad to see it there.

因为我觉得它在标准库中也会得到更多的关注。

Because I think it'll get more love in the standard library too.

而且使用起来肯定更方便。

And certainly be easier to use.

是的。

Yeah.

我不知道Gorilla Toolkit会因为这个发生什么变化，因为他们自己实现了一个网络上下文，我想。

I wonder how the Gorilla Toolkit is gonna change because of this because they've implemented their own network context I think.

我已经有一段时间没用过了。

I haven't used it in a while.

是的，Gorilla有自己的上下文，世界上每个其他路由库也都有自己的上下文。

Yeah, Gorilla has its own context and every other mux on the planet has its own context.

我非常期待它们不再维护自己的上下文，希望它们都能统一使用标准库中的上下文。

I'm really excited about them not having their I own hope that they all converge to use the standard live context.

这其实真的很有趣，我之前都没想过这一点。

That's actually really interesting, I hadn't even considered that.

我的意思是，过去几年我用过 Gorilla mux，但我好像很久没用过 Gorilla 工具包里的其他东西了。

I mean I've used Gorilla mux in the past couple years, but I don't think I've used anything else from the Gorilla stuff in a while.

所以看到它如何适应这一点会非常有趣。

So that'll actually be really interesting to see how that's adapted to this.

是的，而且我觉得 Gorilla mux 甚至导入了它自己的 Gorilla 上下文。

Yeah, and I think the Gorilla mux even imports its own Gorilla context.

就在 Mux 包内部。

Like within the Mux package.

所以很有趣的是，他们是否会继续采用标准库上下文。

So it'll be interesting to see if they go forward with Ghostand library context.

我们应该给他们发邮件问问。

We should email them and ask.

是的。

Yeah.

在 GitHub 仓库中提交一个 issue。

Open a issue on the GitHub repo.

也许他们的开发者中就有一位是我们的两位听众之一。

Maybe one of their developers is one of the two listeners.

好吧，我最近一直在用的另一个项目是 Vendor Check。

All right, so one of the other projects that I've been using recently is Vendor Check.

我注意到他们更新了，现在能告诉你哪些依赖项已被弃用，这太棒了。

And I noticed that they got an update that now tells you your deprecated dependencies, which is awesome.

基本上，它会扫描你的 vendored 路径，只需加上 -U 参数，就能列出所有未使用的依赖项。

So basically it goes through your vendored path and it's just a minus U flag and it'll tell you all your unused This

这很有趣，因为我们在上一期节目中讨论过这个工具的起源文章——Cloudflare 关于创建最简 SSA 工具的博客文章。

is interesting because we talked about the blog post that this originated from in our last episode, the Cloudflare blog post about creating the simplest possible SSA tools.

所以 VendorCheck 是对该文章的延伸，很高兴它现在增加了实用的功能。

So VendorCheck was an extension of that and it's nice that it's getting some very usable features.

有必要时清理 vendor 目录会很有帮助。

It'll be good to get that vendor directory pruned as needed.

在我看来，VendorCheck 几乎应该和 thumbed 并列。

It sounds to me almost like VendorCheck should be right side by side with thumbed.

是的，还有 Go 的导入。

Yeah and Go imports.

这绝对是必备工具。

It's definitely a must have tool.

是的，我认为在供应商相关功能被 Go 团队采纳之前，这些内容可能还为时过早，对吧？

Yeah and I think that the vendor stuff is probably early for that stuff to kind of get pulled in at least adopted by the Go team, right?

因为说实话，最近才逐渐达成共识，认为 Go 工具链或许应该更好地处理供应商管理。

Because I mean it's only been recently that there's been kind of this agreement that maybe the Go tooling should handle vendoring more.

所以很有趣的是，看看他们认为应该整合多少内容。

So it'll be interesting to see how much they think should be pulled in.

但我预计我们会开始看到像 Vim Go 这样的工具，以及各种元工具，逐步集成这些功能。

But I imagine we'll start seeing tools like Vim Go and all that jazz incorporating in this and some of like the meta tooling.

但还有 Go Metal Linter 这样的工具，它们会运行一整套不同的工具。

But there's a Go Metal Linter and stuff like that that runs all the suite of different tooling.

我也完全能看到这种情况发生。

I totally see that happening too.

说到这里，关于将供应商工具内置到 Go 本身的想法，我知道安德鲁·杜兰德曾提到，计划在 7 月 13 日的 GopherCon 黑客日上赞助一场约一小时的演讲或小组讨论，主题是打包和供应商管理。

So on that note, on the idea of having vendor tooling being built into Go itself, I know that Andrew Durand was talking about sponsoring a talk or a panel discussion on the Hack Day at GopherCon on the July 13 for an hour or so talking about packaging and vendoring.

所以，如果你对这个问题有强烈看法，不妨在七月前往丹佛，与 Go 团队直接交流关于包管理和供应商管理的问题。

So if you've got strong opinions on that, might want to come to Denver in July and get together and talk to the GO team directly about package management and vendoring.

这将是一个绝佳的机会，让你的声音被听到。

That would be a great opportunity to have your voice heard.

总的来说，强烈的观点也很重要，我知道他们正打算组织一场非正式的小组讨论或协作会议，邀请主要的 Go 用户参与，了解大家的痛点，以及人们认为 Go 团队如何能缓解这些痛点，让采用和使用 Go 更加容易。

And strong opinions in general, I know that they're wanting to do kind of a panel discussion or not panel, but a collaborative session with big Go users and kind of seeing what pain points are there and how people feel that the Go team can ease those pains and make it easier to adopt and use Go or easier, I should say.

关于这个话题，Go 仓库中已经开启了一个议题，把大家的意见都集中到一个地方，至少会链接到相关资料，如果你打算参加这个活动并参与讨论，这很值得阅读。

And on that topic, there is an issue opened on the Go repo where they just pull in everybody's opinion into one place, at least they put links to things and it's probably something good to read through if you are going to go to this event and discuss.

所以我们掌握了所有信息。

So we have all the information.

这是一个非常长的议题。

It's a really long issue.

是的，这很长，但并不是Go团队在支持某种方式，而是汇集了大家的意见，原原本本地呈现出来。

Yeah, it's huge, but it's just, it's not the gold team endorsing any way or another, but any opinion or other, it's just gathering everybody's opinion in one place and giving it as it is.

好吧，这就是人们在说的，我们就把它们放在这里，避免到处重复。

Okay, this is what people are saying, let's just have it here, so we're not replicating this all over the place.

所以我们有了一个起点。

So we have a starting point.

我们不必再回头讨论已经谈过的事情。

We don't have to go back and talk about things that we already talked about.

所有内容都在这里了。

So it's all in there.

这非常、非常有趣。

It's very, very interesting.

我得在周末的时候找出来看看，或者有更长的空闲时间时再看，是的。

I'll have to pull that up when I have a weekend It's or however longer a than it weekend, yeah.

我只能想象。

I can only imagine.

嗯。

Yeah.

这简直就是时间旅行。

It's plain time traveling.

这就像轻松阅读，充满了对技术实现方式的深思熟虑的表达。

It's like light reading, it's very thoughtful expressions of how things could be done technically.

我会找到它。

I'll find it.

我会找一个链接。

I'll find a link.

太棒了。

Awesome.

说到令人难过的消息，有人看到罗布·米勒发给Hecca邮件列表的那封邮件了吗？

So on a sad news side of things, did anybody see the email that Rob Miller sent out to the Hecca mailing list?

我看到了。

I did.

现在怎么办？

Now what?

太悲伤了。

Very sad.

是的，罗布·米勒在Mozilla工作，负责一个叫Hecca的工具。

Yeah, so Rob Miller works for Mozilla on a tool called Hecca.

布莱恩，你如何最好地描述Hecca？

How would you best describe Hecca, Brian?

Hecca是一个流处理工具，你可以用它来接收输入，进行处理、分析、做各种奇怪的操作，然后将结果发送到其他地方。

Hecca's a stream processing tool that you can use to take inputs and process them and munch them and do strange things with them and send them back out to other places.

它是最

It's one

的

of

Hecca最常见的用途之一是日志聚合与管理，但它远比这复杂得多，不过最合适的用途还是将日志从一处传输到另一处。

the most common use cases for Hecca would be log aggregating and management but it's significantly more complicated than that but that's probably the best use case for it is moving logs from here to there.

是的，它基本上就像一个管道，你可以替换不同的输入组件。

Yeah it's basically like a pipeline and there's different inputs you can swap out.

比如收集器和发射器之类的。

So collectors and emitters and things like that.

因此，你可以从各种不同的系统中获取输入，并输出到多种类型的系统中。

So you can take inputs from various different types of systems and you can output to various types of systems.

曾经有一个非常有趣的项目，他在2014年的GopherCon上展示了它。

There was a really interesting project and he presented it at GopherCon twenty fourteen.

而且据各方面反馈来看，似乎有人在使用它。

And I mean, by all accounts, it seems like people are using it.

但我认为他一直是该项目的主要维护者，而Mozilla内部已经在使用其他工具，他没有时间，未来也会越来越没时间。

But I think he's been primarily the core maintainer of it and they're using something else internally at Mozilla and he hasn't had the time and is going to continue to have less time.

所以我认为这很可能将会——我不确定‘弃用’这个词是否准确。

So I think that that's probably going to be I don't know whether deprecated is the right word for it.

也许是Mozilla停止支持或取消赞助。

Discontinued Mozilla support perhaps or Mozilla sponsorship.

我认为他们愿意让其他人接手这个项目，但他们自己也没有时间来协助完成这个交接。

And I think that they're open to somebody else taking over the project but they don't have the time to help facilitate that takeover either.

我认为他表达了一些担忧，关于该项目所采用的设计模式，特别是他们使用通道的方式并没有达到他们期望的性能水平，类似这样的问题，他认为可能需要进行大量的重构。

And I think he expressed some concerns about even the patterns that was designed under that the the way they were using channels wasn't quite hitting the performance levels that they were wanting and things like that, and he kind of believed that there'd be some heavy refactoring.

也许我们可以请他来节目中，更深入地谈谈他的想法。

And maybe we can get him on the show and talk about it a little bit more in-depth, what his thoughts are.

这是个绝佳的主意。

That'd be a great idea.

我们会在节目笔记中链接到他的邮件公告，虽然内容太长，无法在这里详谈，但他在邮件中传达的主要观点是：要让 Hecca 的性能显著优于当前水平——而当前的性能其实已经相当扎实——但要达到下一个层次，就需要减少对通道的使用。这或许会是我们未来一个很好的节目主题，即讨论在高负载下通道的性能表现，以及通道在什么情况下表现优异、在什么情况下并不合适。

We'll link to the mail list announcement in our show notes and it's way too long to discuss here but the main takeaway from the email that he sent out was that the refactoring required to make Hecca perform significantly better than it does now which is actually really solid performance but to get to that next level, it would require less use of channels and that's probably a good show topic for us at some point is talking about the performance of channels under significant load and when channels are great and when they aren't.

这将是一个极棒的话题。

That would be an amazing topic.

我相信很多人能从中受益。

I'm sure a lot of people can benefit.

我本人也能从中受益。

I can benefit from it.

在我们深入讨论莎拉最近在做的各种事情之前，我们通常会浏览一些有趣的 Go 项目，因为布莱恩简直就是个项目百科全书。

So before we get into some discussions about all the things that Sarah is doing these days, We typically go through some like interesting go projects because Brian just is like full of just this encyclopedia of projects.

但在我们开始之前，我们不再需要布莱恩了。

But before we go into that, we don't need Brian anymore.

你们有没有看到最近流传的 LibHunt 这个东西？

Have you guys seen the LibHunt thing that was going around?

没有。

No.

现在有了 GoLibHunt。

There's now the GoLibHunt.

网址是 go.libhunt.com。

It's go.libhunt.com.

你可以浏览并分类 Go 语言的项目和库，它们

And you can basically browse around, categorize projects and libraries in Go they

只是简单地排名而已，有人列出一堆 Go 库并不能取代我的精选，埃里克。

kind Just of rank because somebody lists a bunch of libraries in Go does not replace my curation, Eric.

我每周为精选项目所做的整理工作所带来的附加价值才是关键。

The added value that I bring every week to the curation of cool projects is what's important here.

你无法用一个 Bash 脚本来取代我。

You cannot replace me with a Bash script.

我们可以试试，真的可以试试。

We can try, we can try.

瑞安，你的流程是怎样的？

Ryan, what's your process?

你怎么找到这些 Go 项目？

How find do the Go projects?

每天晚上睡觉前，我都会去看看 Golang 的 Reddit 页面，看看有没有什么有趣的内容。

Before I go to bed every night, I look at the Golang Reddit thing just to see if there's anything interesting there.

我现在从 Reddit 上收获不多，但我有一个专门的 GitHub 查询，用来查看最近更新或新创建的 Go 项目，然后我会浏览一遍，寻找那些听起来令人兴奋且我之前没见过的东西。

I don't get a lot out of Reddit these days but I have a special query on GitHub that I use to see recently updated or recently created Go projects and I just scan through them looking for things that sound exciting that I haven't seen before.

这个查询只需三笔轻松付款，每笔 59.9 美元。

And that query can be for just three easy payments of $59.9

没错，实际上我很乐意把那个查询语句放在节目笔记里，因为这没什么神奇的，只是一个非常长的 GitHub 查询。

Exactly And actually I'd be happy to post that query in the show notes too because there's nothing magic to it, it's just a really long GitHub query.

我以前用过一个应用，不叫 StumbleUpon，但功能类似，可以浏览并设置过滤器，比如 Go 项目之类的，它会扫描 GitHub，帮你发现相对热门的 Go 项目。

I used to use, I had an app, it wasn't called StumbleUpon but it was something like that where it acts like StumbleUpon where you can look through, and you can have filters like a Go project or whatever, it looks through GitHub and helps you stumble upon Go projects that are relatively popular.

这挺酷的。

That's pretty cool.

这不错。

That's nice.

所有这些查询都容易出错，因为如果 GitHub 对项目类型的识别不准确——比如你没有在根目录下放任何 Go 文件，或者他们用来识别项目的依据有问题——项目就可能被排除在外，而这

All of those queries are prone to error because if GitHub's detection of the project type isn't accurate because maybe you don't have any Go files in the root or whatever they use to detect the projects, they might be excluded and that's

这常见吗？

Is that common?

很常见。

It is.

我见过一些项目，明明是某种语言写的，却没有被标记为该主要语言，这是因为 GitHub 用来识别的机制被它们的目录结构之类的因素干扰了。

I've seen projects that don't list themselves as the primary language that they are just because whatever GitHub uses to detect that was thwarted by maybe their directory layout whatever.

我不确定这个检测机制是如何工作的。

I'm not sure how that detection works.

我的意思是，它是根据代码库的什么比例来判断的，比如你有Grafana，对吧？

I mean, whether it's like what percentage of the code base is and what, because I mean, you had like say Grafana, right?

那里面有很多Go代码，但也有大量的网页内容，比如HTML、CSS和JavaScript。

That's a bunch of Go, but it's a whole lot of web stuff to HTML and CSS and JavaScript too.

所以是哪种语言的代码更多一些呢？还是说这取决于

So is there more than More of one than the other, and does that

我一直都想了解一下。

cost I have always wanted to.

如果有人知道的话，请告诉我。

If somebody knows, please.

你创建仓库时也可以手动指定语言吗？真的吗？

You can also specify when you're creating a repo Really?

项目的语言。

Language the project is.

嗯，我认为它能帮助你生成.gitignore文件。

Well, I think it just helps you then generate the gitignore.

我从来没看过这个。

I've never seen that.

有意思。

Interesting.

但我不确定他们是否会保存这些数据。

But I'm not sure if they keep that data.

是啊，不知道他们是否把这作为元数据存储。

Yeah, wonder if they store that as metadata.

我从来没专门这么做过，所以我不清楚。

Never done that specifically, so I don't know.

就像莎拉说的，我觉得我只用过一次，只是为了生成.gitignore文件。

Like Sarah said, I think I've only used it once just to generate the gitignore.

所以现在埃里克试图用一个网站取代我，是时候了。

So now that Eric has tried to replace me with a website, it's The time is on.

我们节目的下一个环节是每个人谈谈过去一周偶然发现的有趣Go项目，我先来吧，毕竟我带来的最有价值。

The next segment of our show is where we each talk about interesting GO projects that we've perhaps stumbled upon in the past week and I'll start since I'm bringing the most value here.

埃里克，我现在真的对你很生气。

Really angry with you Eric now.

这行不通。

This isn't gonna fly.

我这周发现的一个特别酷的东西，是之前提到过的Minio和Kubernetes的结合。Minio是一个S3对象存储的克隆，你可以部署在自己的硬件或云上，提供一个兼容S3的对象存储池；而另一个很棒的项目就是Kubernetes。

So the thing I found this week that I thought was really cool was a combination of one that I talked about previously which is Minio, S3 object storage clone that you can deploy on your own hardware or on the cloud somewhere that gives you an S3 compatible object storage pool and another project that is awesome which is Kubernetes.

Dais团队——一个基于Kubernetes的平台即服务——为Kubernetes开发了一个Minio存储插件，让你可以用Minio的S3存储来为Kubernetes集群提供存储，它与Kubernetes的集成非常紧密，看起来非常棒。

So the Dais team, Dais is a platform as a service on top of Kubernetes, they created a Minio storage plugin for Kubernetes so you can use Minio S3 storage for your Kubernetes cluster and it's got some really tight integration with Kubernetes, looks really awesome.

所以，两种绝佳的口味组合在一起，再次变得无比美味——那就是Minio和Kubernetes。

So two great tastes that taste together, that taste great together again, which is Mineo and Kubernetes.

项目地址是：github.com/deis/mineo。

That's at github.com/deis/mineo.

接下来我来说。

So I will go next.

我很久以前就看到过这个，当时它还处于非常早期的阶段，那就是 Lime Text，一个用 Go 编写的 Sublime Text 克隆。

I saw this a while back and I think it was really in its infancy, which is Lime Text, which is like a Sublime Text clone, but written in Go.

而且它现在进展得相当不错。

And it's actually been coming along quite well.

我其实很好奇 Carlicia 是否试过，因为我知道你是个

And I was actually curious whether Carlicia had tried it because I know you're a

Sublime 用户，

sublime user,

对吧，Carlicia？

right Carlicia?

不，我不是。

No, I'm not.

我以为你是 Sublime 用户呢。

I thought you were a sublime user.

我以前是盲目的。

I used to blind.

我用过，但很久以前就停止用了

I've used it but Have I stopped using it a long

你试过吗，莎拉？

you checked it out, Sarah?

没有，我没用过。

No, haven't.

我正在看它。

I'm looking at it right now.

是的，这其实挺有意思的，因为我是离不开Vim的，但我觉得如果你能离开Vim，可能就会选Sublime，而这个工具让人有点心动，因为如果我想修改编辑器，我真的可以做到，而且还能继续用。

Yeah, so this is actually pretty interesting because I mean, you can't get me away from Vim but I feel like if you could, it might be sublime and this makes it kind of enticing because if I wanted to modify the editor, I could actually do it and go.

从另一个角度来看，它几乎模仿了Emacs和NeoVim的服务器-客户端架构。

Well it's interesting from another perspective in that it's almost modeled on the Emacs and NeoVim server and client model.

所以Lime Text应用有一个后端，然后可以有多个前端，你可以用命令行工具来使用Lime Text，或者他们也提供了一个基于QT的图形界面编辑器，但后端保持不变。

So the Lime Text app has a backend and then it can have multiple frontends so you could actually use a command line app to use Lime Text or they've got a QT based editor for a graphical environment but the backend stays the same.

因此，我认为在Go语言编写的文本编辑器中，这一点让它显得独一无二，也让我觉得它更有趣了。

So that makes it unique I think in terms of Go based text editors that certainly made it more interesting to me.

不过我还是想试试看。

I do wanna check it out though.

是啊，我是Atom用户，用它搭配Vim插件，但这个看起来很酷。

Yeah, I'm an Atom user, I use it with the VIM plugin but this looks cool.

我不知道我为什么以为你用Sublime，但现在我想起来了，Adam，因为你确实提到过为Adam新增了一组插件。

I don't know why I thought you used Sublime, but now I remember Adam because you did bring up a new set of plugins for Adam.

那不是上一期，是上上期。

That wasn't last episode, it was the episode before.

所有

All

这些编辑器在很多方面看起来都差不多。

these editors look a lot the same in a lot of ways, so.

我跟不上所有新编辑器的步伐。

I can't keep up with all the new editors.

莎拉，你有想提到的Go项目吗？

Sarah, do you have a Go project you wanted to mention?

随时可以说不。

Feel free to say no.

没有，我没有。

No, I didn't.

我没有。

I didn't

所以我会接着来。

prepare So I'll go next.

我发现了这个HDR直方图，虽然我没用过，但我感觉我会用它。

I found this HDR histogram and it's not something I have used, but I can see myself using it.

它会跟踪传入请求的样本数量，也就是你收到的请求数量。

It keeps track of a sample count of basically incoming requests, how many simple counts of incoming requests that you have.

然后你可以指定想要观察随时间变化的内容。

And then you can specify what it is that you wanna look at over time.

所以这个是显示每秒请求数随时间的变化吗？

So this is showing like a request per second over time or?

我认为这是每秒请求数。

I think it's request per seconds.

我以前用过这个包，我觉得它比单纯的每秒请求数更通用，实际上它是一个直方图包，可以用来收集任何特定事件的指标并以直方图形式展示。

I've used this package before, I think it's more generic than just request per second, I think it's actually just a histogram package that you can use to collect metrics about any particular event and then present them in a histogram.

每秒请求数是当你在网站上收集指标时使用它的绝佳例子。

Request per second is a great example of how you would use it if you were collecting metrics on a website.

没错，看起来就是这样。

Exactly, it looks like that.

它是可配置的，我之所以发现这个工具，是因为他们有一个这个工具的 Go 版本。

It's configurable the interesting, the way that I found about this was because, they have a package, they have a Go version of this.

我之所以发现它并觉得它相关，是因为我去年看了 Juteen 在 Strange Loop 上的一场演讲，我不确定这个名字发音是否正确，他谈到了网络图通常只展示 95 百分位的响应时间，也就是最差的响应时间。

And the way I found about this and why it's relevant is because I saw a talk by Juteen, I don't know if that's how it's pronounced, on Strange Loop from last year and he was talking about how network graphs usually show us the 95 percentile of, you know, the worst response times that you get.

他进一步详细说明了这种做法有多无意义，以及它如何掩盖了你真正想看到的信息——即实际的计数和实际的最大值。

And he goes on to talk about, in detail about how meaningless that is and how much it hides the information that you really want to see, which is the actual count, the actual max.

他还进一步讨论了服务时间与响应时间之间的区别，这非常有趣，因为你虽然知道，但通常不会从这些角度去思考，不过确实很有道理。

And he also goes on to talk about the difference between service time and response time and it's fascinating because you kinda know, you don't, I don't know, I don't usually think about in those terms but yeah, it makes total sense.

这是一场非常精彩的演讲，如果你想要监控你的系统，而你正在使用的是一些常见的商业工具，也许你应该看看这个。

It's a fascinating talk and if you want to monitor your stuff and what you are using is the usual commercial tools that are out there, maybe you should check this out.

就这样。

That's it.

我们可以提供链接。

You can, we will have links.

你会把链接放到节目笔记里吗？

Will you put that link in the show notes?

会的，我已经加好了。

Yes, I already did.

就在这里。

There it is.

完美。

Perfect.

所以，Sarah，我们非常想听你谈谈你的那个从测试生成文档的项目。

So Sarah, one project that we would love to hear you talk about is your test to doc.

哦，当然，好的。

Oh sure, yeah.

这太酷了。

That's really cool.

谢谢。

Thanks.

所以大约一年半前，我有了这个想法，当时我在一家叫Sproutling的公司工作，我们正在开发一款可穿戴婴儿监护仪，我负责构建一个拥有多个客户端的REST API。

So I got this idea like a year and a half ago, I was maintaining a REST API for, while I was working for a company called Sproutling, we were building a wearable baby monitor And so I was building a REST API that had multiple clients.

我们有定制的硬件，这是一种基站，用于监测婴儿房间的室温等数据。

We had custom hardware, which was sort of a base station that was monitoring room temperature and stuff in the baby's room.

我们还有一个iOS应用，作为第二个客户端，以及一个网页应用，作为第三个客户端。

We had an iOS app, which was a second client and we had a web app, which was a third client.

因此，每个客户端都有独立的开发团队在负责。

And so we had multiple developer teams working on each of these.

由于我是唯一负责REST API的人，当然，我需要有API文档。

And so since I was the only person responsible for the REST API, well, not because of that, but I needed to have API documentation of course.

所以我开始使用 Apiary，因为我喜欢它的格式，可以用 Markdown 编写，而且他们的 API 蓝图规范是开源的，这很好。

So I started using Apiary because I like the format, was, it's, you can write it in markdown and their specification, the API blueprint specification is open source, which is nice.

但对于较大的更改，比如添加或删除端点，我还能记得更新文档。

And but I kept it like so for larger changes like adding an endpoint or, know, deleting an endpoint, those were easy to remember to update the documentation.

但像删除某个属性，甚至到删除数据库表中的某一列这样的小改动，会间接影响到端点，导致 JSON 响应中字段缺失。

But for smaller things like deleting an attribute on a or all the way down to like deleting a column on a database table would trickle up to the endpoint change, which mean the which would mean the field was missing on the JSON response.

这些小改动积累得越来越多，导致我的文档经常与实际 API 不一致。

Those smaller changes started to add up a lot and so my documentation was often really inconsistent with the actual API.

于是我开始 fork 了一个叫 Dread 的工具，它用于将文档与实际 API 进行比对测试。

And so I started just, I forked a tool called Dread, which is meant for testing your documentation against your actual API.

这个工具效果不错，但我必须定期手动运行它并更新所有文档。

And it was pretty good but I had to sort of periodically just run this and update all of the documentation.

于是我变得非常沮丧，因为我的单元测试都已经写好了。

And so I started to get really frustrated because my unit tests were all there.

我的单元测试都摆在那儿，如果我的同事们能读我的 Go 单元测试并用它们当文档，那该多好啊。

They were all like I mean, if only my fellow engineers could read my Go unit tests and use that as documentation, like that would have worked great.

于是我意识到，API文档所需的所有信息都包含在端点处理程序的测试中。

And so I realized that all of the information that you need for API documentation is in the endpoint handler test.

于是我决定，就在测试运行时记录请求和响应，将它们以适当的格式存入Markdown文件，从而自动生成并托管所有的API文档，实现完全自动化。

And so I decided I was just gonna record the requests and responses as the test ran and put them in a markdown file in the appropriate format and then be able to generate all of my API documentation and host it and have everything be automated.

这样我就再也不用担心文档过时、开发人员生气，或者有人不断问我问题了。

So I would never have to worry about out of date documentation and angry developers and people asking me questions and things like that.

所以，这就是这个想法的由来。

So that's sort of where that came from.

那么，当你编写测试时，你会如何不同地编写测试，以便让文档看起来更合适呢？

So when you're writing your tests, how much differently do you write your tests to make the documents look appropriate?

你必须

Do you have to

完全不用。

Not at all.

完全不用？

Not at all?

是的，这非常简单。

Yeah, it's super simple.

你只需要添加大约六行代码，但本质上，如果你有非常良好、非常全面的单元测试，比如测试用户传入 nil 或传入没有请求数据的帖子，所有这些测试都会被记录下来。

There's like maybe six lines of code that you have to add But essentially, if you have really good, really thorough unit tests, like testing for user passes nil and user passes a post with no request data, and all of that, all of those tests are captured.

因此，在文档中，你可以看到当传入 nil 时会发生什么。

And so you can see in the documentation, when you pass nil, this happens.

所以，是的，这些测试其实就是：如果用户发送这样的请求，应有的正确响应是什么？

So, yeah, so the tests are really just, like, if this is the request that the user sends, what should the appropriate response be?

而这正是文档所要表达的内容。

And that's exactly what documentation is also.

这真的很有趣。

That's really interesting.

那么你是如何实现这一点的？

So how do you have that implemented?

你是静态分析测试吗？

You're statically analyzing the tests?

不。

No.

实际上，我很久以前写了这一部分，但我想我用了 HTTP 测试。

Have a Actually, is I wrote this bit a while ago, but I think I used the HTTP test.

我觉得它们就像是响应。

I feel like they're like response

报告器之类的东西。

reporters and stuff like that.

是的。

Yeah.

所以，实际上，在测试过程中，我会在测试实际执行前暂停，从请求对象本身复制请求体，放到某个缓冲区中，然后执行测试，再在返回前复制响应数据并也放入缓冲区。

So, actually, during the test, I paused the test right before like the actual test executes and copy the request body from just the from the request object itself and put that into a buffer somewhere, then execute the test and then copy the response data before we actually return and put that into the buffer as well.

当整个测试套件完成后，将缓冲区的内容以适当的格式输出到文件中。

And then when the full test suite is finished, flush that buffer to a file in the appropriate format.

还有一些其他细节，比如提取请求的 URL 参数，这样在文档中，例如，如果你测试的是获取 ID 为 1 的商品，以及获取 ID 为 2 的商品，它们自然会对应两个不同的 URL。

And there are some other intricacies like pulling out requests URL variables, so that we don't so that in the documentation, for example, if you're testing get widgets with ID one, and then get widgets with ID two, those would naturally be two separate URLs.

他们正试图弄清楚如何将这两者匹配起来。

They're trying to figure out how to match those two together.

注意，一和二实际上是变量。

Notice that the one and two are actually variables.

所以这方面有一些复杂之处。

So there's some intricacies with that.

URL也是如此，抱歉，是查询参数。

Same with URL sorry, query parameters.

这个也支持头部逻辑吗？

Is this does this support header logic too?

是的。

Yep.

是的。

Yep.

所有的头部信息也会被记录到同一个缓冲区中。

All your headers are logged also to the same buffer.

它们是以API蓝图的适当格式编写的。

They're written in the appropriate format for the API blueprint.

这真是太棒了。

That's really awesome.

我有点想试试这个。

I kinda wanna play with this.

是的，真的很棒。

Yeah, it is awesome.

我非常喜欢。

I love it.

我在工作中使用它。

I use it at work.

那么，有没有办法来增强文档呢？

And then, is there a way kind of to augment the documentation?

比如那些通过监控请求和响应无法捕捉到的内容，你可能想记录下来的备注之类的。

So things that aren't necessarily captured by monitoring the requests and responses, things that you might want to take notes on like Yeah.

什么样的值才是合适的，或者类似的东西？

What appropriate values are or things like that?

嗯。

Yeah.

对于每个包，都会生成一个 API B 文件，你实际上需要做的是有一个——我称之为模板，但其实只是对你的 API 的描述以及一些高层次的内容。

So for each package, a API B file is spit out and so what you actually need to do is have sort of a, I call it like a template but it's really just the description of your API and sort of high level things like that.

这些内容放在 API B 文件的顶部。

Those go at the top of the API B file.

所以，当所有测试运行完毕后，你会为每个包得到一个 API B 文件，你需要将它们合并，在这个步骤中，你可以插入一些内容——比如在我现在的公司，我们在文档顶部有一份所有错误和错误代码的列表，这些内容是在我们追加所有 APIB 文件之前生成的。

So once all of your tests have run, you'll get back one API B file per package and so you need to combine them and so during that step you could actually insert, so for my current company we have a list of all of our errors and our error codes at the top of our documentation file and so that's generated right before we append all of the APIB files.

所以，是的，这完全灵活。

So yeah, it's totally flexible.

这很酷。

That's cool.

这个流程是怎样的？

And what's the process for this?