本文永久链接 – 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的快乐! 欢迎大家踊跃加入！

著名云主机服务厂商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

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

本文永久链接 – https://tonybai.com/2024/04/09/choose-the-right-go-module-path

最近我在查看项目代码时，注意到有人在go.mod文件中将module path写为com.example.foo了。根据这个写法，相信屏幕前的读者也可以推断出这位开发人员可能是从Java阵营转到Go的。实际开发中可能有很多开发者会使用类似的内容作为module path，但这显然不是Go的推荐写法或惯用法。

在这篇简短的文章中，我就来介绍一下module path对Go源码构建、包导入路径以及开发协作的影响，以及符合惯例的module path应该是什么样子的。

我们先来复习一下什么是Go module path。

1. 什么是module path

在Go语言中，module path（模块路径）是指在Go开发中用来标识和定位模块的唯一字符串，用于指定在远程仓库或本地文件系统中存储模块代码的位置。

module path在go.mod文件中定义，比如下面这个示例：

// go.mod
module github.com/user/module

go 1.21.1

我们看到：一个典型的模块路径是一个URL格式字符串，可能是类似于github.com/user/module的形式，其中github.com/user/module就是module path。

在Go语言中，模块（module）是一种组织和管理代码的方式，也是Go代码版本管理的基本单元，我们可以在模块路径中包含主版本信息，比如：

// go.mod
module github.com/user/module/v2

go 1.21.1

这表明该模块为v2版本，与前面的github.com/user/module是不向后兼容的两个模块。模块的使用者可以同时导入这两个不兼容的模块下的包，比如：

import (
    "github.com/user/module/foo"
    foov2 "github.com/user/module/v2/foo"
)

那么module path的选取和使用，对Go开发有何影响呢？我们继续向下看。

2. module path的影响

2.1 指示Go module网络位置

前面提到过，在Go语言中，我们通常使用模块的存储库地址作为模块路径的基础。这样做的好处是，Go编译器可以直接通过模块路径确定模块在网络上的位置，并从指定的位置下载需要的代码。这使得在使用第三方模块时非常方便，开发者只需要指定模块的路径，Go工具链就能够自动处理依赖关系，下载并编译所需的模块代码。

例如，如果一个模块的路径是github.com/user/module，那么Go工具链（尤其是Go编译器)就会认为该模块的代码存储在GitHub上的user用户下的module仓库中。当Go工具链需要引入该模块时，它会根据这个路径通过goproxy或直接去GitHub上下载相应的代码。

这种基于存储库地址的模块路径设计简化了模块的管理和依赖关系的处理，使得在Go项目中使用第三方模块变得更加方便和可靠。

2.2 对Go包路径的影响

Go module下的包的导入路径为module path+到包所在目录的相对路径，以module path为github.com/user/module的module下的pkg/foo目录下的包为例，foo包的导入路径为github.com/user/module/pkg/foo。

而如果像本文开头那样，使用com.example.foo作为module path，那么foo包的导入路径就变为了com.example.foo/pkg/foo，这显然难以理解，同时，com.example.foo这样的Java模式的字符串也无法指示go module的网络位置。

2.3 对编译的影响

module path对编译的影响体现在两方面：

首先，Go编译时通过module path来查找依赖的模块。如果Go module path不正确或不完整，那么编译可能会失败。非idiomatic的Go module path可能导致编译错误或难以诊断的问题。

其次，module path会影响采用go build默认构建出的二进制文件的名字，比如如果一个module path为github.com/user/mymodule，那么在该module下执行go build（不使用-o命令行标志），默认得到的二进制文件名为mymodule。

但如果module path为com.example.foo，那么得到的二进制文件名就为com.example.foo，这显然不是我们想要的。

2.4 对开发者协作的影响

Go模块路径的命名对开发者之间的协作也有着重要的影响，主要体现在两方面：

• 唯一性和命名空间

模块路径应当保持唯一，以避免与其他模块产生冲突。通常情况下，使用域名作为模块路径的一部分可以确保全球唯一性。在团队内部，也可以基于公司或组织的名称来命名模块路径，以确保模块的唯一性。

• 依赖管理

使用清晰、有意义、可以指示位置和版本的模块路径可以帮助开发者更好地管理依赖关系。当其他开发者在引入你的模块时，他们可以通过模块路径来确定正确的依赖版本，以及如何与你的模块进行集成。

3. 如何选择一个好的module path

通过上面的秒数，其实我们已经可以勾勒出一个好的module path的画像了。当然这也是Go社区的最佳实践。

通常情况下，module path应该基于模块的存储库地址，并使用简短、易于理解的路径。

就像前面提到的那样，如果你的module存储在GitHub上并可公开，那么module path一般是github.com/user/module。

如果你的module公司内部，不能公开的，那么可以使用一个私有的存储库地址，例如：company.com/dept/go/module。

无论公开的，还是私有的，你都可以定制module path，这方面的方案可以参考我之前编写的有关定制Go module的拉取方案。

如果是仅在本地使用的日常练习项目，那么Go module path的使用可以宽松一些，可以无需在乎其对go module网络位置、开发者协作的影响，可使用像demo这样的单个词的module path，仅注意下其对包路径和编译结果的影响即可。

4. 小结

综上，我们看到：Go module path对Go module网络位置、包路径、编译和开发者协作都有重要影响。遵循Go社区的最佳实践，选择一个好的Go module path可以提高代码可读性和可维护性，并简化多人协作，帮助Go开发者更好地使用Go模块系统。

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

著名云主机服务厂商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://gopherdaily.tonybai.com

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