Http | Tony Bai

本文永久链接 – https://tonybai.com/2024/09/06/go-doc-add-http-support

Go语言团队近期接受了Go团队成员、Go圣经《The Go Programming Language》合著者Alan Donovan的新提案，旨在进一步提升开发者体验。这个提案为go doc命令新增了一个强大的功能：通过go doc -http，开发者可以快速启动一个本地的文档服务器，并自动在浏览器中打开Go包的参考文档。该功能为开发者提供了类似pkg.go.dev的离线文档展示形式，同时增强了查看本地文档的交叉引用功能。看到这个提案功能，屏幕前的资深Gopher是不是感觉似曾相识呢:)。

早在去年，我就写过一篇有关go包文档查看方式对比的文章《聊聊godoc、go doc与pkgsite》，在那篇文章中，我就对当前Go包文档查看的几种方式做了详细说明，如果你是Go初学者，不妨点击链接移步过去仔细阅读一番。当然，这里也会简单地再介绍一下Go包文档离线查看工具的演进。

Go语言的包文档查看工具经历了三个重要阶段的演进，分别是godoc、go doc和pkgsite。以下是这些工具的发展历程：

godoc是Go语言最早用于查看包文档的工具。它支持通过命令行查看文档，也可以通过-http参数启动一个本地文档服务器，用户在浏览器中以网页形式查看文档。这个工具提供了较为完整的Go包文档浏览体验，支持交叉引用和导航。但随着Go的发展，逐渐不再是官方推荐的工具，并且不再随Go安装包一并发布了！

随着Go的升级与演进，go doc逐渐取代了godoc成为查看包文档的主要工具。go doc主要提供了通过命令行输出包详细文档的能力，对应简单的包查询，这种方式更为高效：

$go doc -h
Usage of [go] doc:
    go doc
    go doc <pkg>
    go doc <sym>[.<methodOrField>]
    go doc [<pkg>.]<sym>[.<methodOrField>]
    go doc [<pkg>.][<sym>.]<methodOrField>
    go doc <pkg> <sym>[.<methodOrField>]
For more information run
    go help doc

Flags:
  -C dir
        change to dir before running command
  -all
        show all documentation for package
  -c    symbol matching honors case (paths not affected)
  -cmd
        show symbols with package docs even if package is a command
  -short
        one-line representation for each symbol
  -src
        show source code for symbol
  -u    show unexported symbols as well as exported

然而从上面的usage输出来看，go doc版本去除了godoc堪称精髓能力的-http支持，开发者无法像godoc那样启动本地文档服务器，这在某种程度上减少了它的可视化文档浏览功能。

pkgsite是目前官方推荐的在线Go包文档浏览工具，提供了一个全面、易于导航的网站（pkg.go.dev），用户可以在浏览器中查看各个Go包的文档、函数、类型等信息。它大大提升了开发者的体验，提供了丰富的交叉引用和包依赖信息。

但pkgsite也是go官方站，主要用于在线查看，虽然也支持离线查看功能。但就像Alan Donovan在issue提到的那样：pkgsite程序目前相当大且启动缓慢，并且pkgsite最初被设计为一个可以在Google Cloud上运行的长生命周期的服务器，有很多外部依赖和耦合。

为了满足诸多Gopher通过浏览器web方式离线浏览Go包参考手册的需求，弥补pkgsite过于缓慢和庞大的不足，Alan Donovan提出了让离线文档服务能力回归的issue。没错！这个提案其实就是godoc -http这个经典的、精髓功能的“重生”。

这一新增功能有望在Go 1.24或之后的版本中正式推出，届时，新增的go doc -http功能会让离线文档服务的能力回归，为开发者提供了更多选择与灵活性。但目前go doc -http的具体命令接口形式尚未确定，但可以确定的是，通过该命令，用户无需再依赖第三方工具或访问外部网站，即可在本地查看项目的完整文档。这不仅提升了效率，也让开发者更方便地查找包文档以及包间的交叉引用，实现更直观的包依赖管理。Go开发者们可以尽情享受这一强大的本地文档浏览工具。

Gopher部落知识星球在2024年将继续致力于打造一个高品质的Go语言学习和交流平台。我们将继续提供优质的Go技术文章首发和阅读体验。同时，我们也会加强代码质量和最佳实践的分享，包括如何编写简洁、可读、可测试的Go代码。此外，我们还会加强星友之间的交流和互动。欢迎大家踊跃提问，分享心得，讨论技术。我会在第一时间进行解答和交流。我衷心希望Gopher部落可以成为大家学习、进步、交流的港湾。让我相聚在Gopher部落，享受coding的快乐! 欢迎大家踊跃加入！

img{512x368}

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

Gopher Daily(Gopher每日新闻) – https://gopherdaily.tonybai.com

我的联系方式：

微博(暂不可用)：https://weibo.com/bigwhite20xx
微博2：https://weibo.com/u/6484441286
博客：tonybai.com
github: https://github.com/bigwhite
Gopher Daily归档 – https://github.com/bigwhite/gopherdaily
Gopher Daily Feed订阅 – https://gopherdaily.tonybai.com/feed

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

Gopher Daily支持Feed订阅

本文永久链接 – https://tonybai.com/2024/08/04/gopherdaily-add-feed-support

在《Russ Cox“退位”，Go语言将迎来新领袖，未来将如何发展》一文的评论区，有Gopher问及gopher-daily.com的HTTPS证书过期的问题，这里再正式声明一下：gopher-daily.com并非Gopher Daily的官方邮件列表，而是由一位名为Bastengao的热心Gopher维护的第三方邮件列表。Gopher Daily以前没有官方邮件订阅功能，该邮件列表弥补了广大Gopher通过邮件订阅Gopher Daily的需求，这里再次表示感谢。

不过，一年前，我为Gopher Daily增加了官方邮件列表，大家可以在Gopher Daily主页实现邮件订阅。

接下来，还是那位提问的Gopher又询问Gopher Daily是否支持RSS订阅，我当时如实相告：暂不支持。

不过，这个周末针对邮件列表支持RSS订阅的功能需求，我也简单调研了一下，似乎很多技术类Newsletter都不支持。不过，我询问了一下Claude 3.5 Sonnet邮件列表和RSS订阅的优缺点，下面是它的回答摘录：

邮件列表和RSS订阅都是传播信息的有效方式，但各有优缺点。

邮件列表的优点：

1. 直接送达：信息直接发送到订阅者的收件箱，更容易引起注意。
2. 个性化：可以根据订阅者的兴趣定制内容。
3. 互动性：读者可以直接回复邮件与发送者交流。
4. 数据分析：可以追踪打开率、点击率等数据。
5. 无需额外软件：用户只需要邮箱就可以接收。

邮件列表的缺点：

1. 可能被当作垃圾邮件：有时会被误分类或过滤。
2. 信息过载：频繁的邮件可能让订阅者感到烦扰。
3. 隐私问题：需要收集用户的邮箱地址。
4. 送达率：不能保证100%送达。

RSS订阅的优点：

1. 实时更新：内容一发布就可以被获取。
2. 集中阅读：可以在一个RSS阅读器中浏览多个来源的内容。
3. 无垃圾邮件风险：不会被误认为是垃圾邮件。
4. 匿名性：不需要提供个人信息。

RSS订阅的缺点：

1. 需要额外软件：用户需要使用RSS阅读器。
2. 缺乏个性化：难以针对个别用户定制内容。
3. 互动性较差：不易与内容创作者直接交流。
4. 数据分析有限：难以获得详细的用户行为数据。

总的来说，邮件列表更适合需要个性化、互动性强的内容传播，而RSS则更适合频繁更新、希望读者自主选择阅读时间的内容。选择哪种方式取决于你的目标受众和内容类型。

我觉得邮件列表最大的问题就是到达率问题，现在各大电邮服务对于垃圾邮件的过滤还是很严格的，甚至“宁可错杀三千，不可放走一人”，我个人订阅的很多Newsletter也总是被误杀，导致偶尔收不到。出于让更多人能看到Gopher Daily的考虑，我决定给Gopher Daily Newsletter增加RSS订阅功能。

给一个站点或邮件列表增加RSS订阅功能至少有两种方案，一种是利用一些RSSHub之类的信息聚合服务站点直接将站点转换为一个RSS源，这种方案就需要依赖这样的RSS源转换服务。另外一种就是自己实现RSS源服务。

RSS（Really Simple Syndication）实际上是在Web 1.0时代发展起来的，但它在Web 2.0的环境中得到了广泛应用。Web 2.0强调用户生成内容和互动，而RSS允许用户方便地订阅和获取来自不同网站的内容更新，促进了信息的分发和共享。

信息订阅技术目前演进到RSS 2.0和Atom订阅阶段。RSS 2.0是最广泛使用的RSS版本，但它并不是一个正式的IETF（Internet Engineering Task Force）标准，因此没有官方的RFC。然而，它有一个详细的规范文档，在RSS Advisory Board上可以看到。

鉴于RSS缺乏标准化，Atom格式被开发出来作为一个标准化的替代品。Atom是有正式的RFC规范的：RFC 4287: The Atom Syndication Format。不过，无论是RSS 2.0还是Atom规范，都不复杂。

Atom规范中举的一个最简单的single entry的Feed源的响应数据示例如下：

 <?xml version="1.0" encoding="utf-8"?>
   <feed xmlns="http://www.w3.org/2005/Atom">

     <title>Example Feed</title>
     <link href="http://example.org/"/>
     <updated>2003-12-13T18:30:02Z</updated>
     <author>
       <name>John Doe</name>
     </author>
     <id>urn:uuid:60a76c80-d399-11d9-b93C-0003939e0af6</id>

     <entry>
       <title>Atom-Powered Robots Run Amok</title>
       <link href="http://example.org/2003/12/13/atom03"/>
       <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
       <updated>2003-12-13T18:30:02Z</updated>
       <summary>Some text.</summary>
     </entry>

   </feed>

于是，我决定自己来基于Go http handler和标准库的xml包为Gopher Daily服务加上Atom版的订阅支持，无需使用任何第三方包。增加订阅源后，还可以使用W3C的免费的Feed Validation Service来验证Feed是否是符合规范的：