Golang API版本文档指南

NobbZ:

无论如何，在网站上浏览文档仍然要容易得多。

Godoc（不是 go doc）具有 Web 模式：

godoc -http=localhost:6060

这会有帮助吗？

在 pkg.go.dev 上还有另一个技巧可以使用。

https://pkg.go.dev/time@go1.18beta1?tab=versions

当 API 发生变化时，会有一个差异对比（默认不展开）。你可以点击“展开全部”来查看 API/数据结构的变化。

是的，无论怎样我都必须安装它，但在网站上浏览文档要容易得多，而且说实话，我的一些同事明白他们需要针对 Go 1.10 版本，却不明白他们应该在终端上使用 go doc 来阅读文档。他们更不理解可以运行一个本地文档服务器。他们为官方文档设置了书签，但那些文档缺少关键信息。

另外，在终端上使用 go doc 的问题是，你需要事先知道函数名称，无法像在网站上那样搜索 API。

我们想从官方文档中得到解答的主要问题是：在我必须使用的版本中，这个有文档记录的 API 片段是否可用？

在Go语言中，标准库的API版本控制确实不像Java/C#那样有显式的版本标注，但可以通过以下几种方式获取API引入版本信息：

1. 官方文档中的"Added in version"标注

虽然Go文档没有强制要求，但部分新API会标注版本信息。例如time.UnixMilli()的文档中实际包含了版本提示：

// UnixMilli returns the local Time corresponding to the given Unix time,
// msec milliseconds since January 1, 1970 UTC.
//
// To extract the millisecond component from a Time t, use t.UnixMilli().
//
// This function was added in Go 1.17.
func (t Time) UnixMilli() int64 {
    return t.unixSec()*1e3 + int64(t.nsec())/1e6
}

2. 使用go/doc API获取版本信息

可以通过编程方式检查API的可用性：

package main

import (
    "fmt"
    "go/doc"
    "go/parser"
    "go/token"
    "strings"
)

func checkAPIVersion(pkgPath, funcName string) {
    fset := token.NewFileSet()
    pkgs, err := parser.ParseDir(fset, pkgPath, nil, parser.ParseComments)
    if err != nil {
        fmt.Printf("Error: %v\n", err)
        return
    }
    
    for _, pkg := range pkgs {
        docPkg := doc.New(pkg, "./", doc.AllDecls)
        for _, t := range docPkg.Types {
            for _, m := range t.Methods {
                if m.Name == funcName {
                    fmt.Printf("Found %s in type %s\n", funcName, t.Name)
                    if strings.Contains(m.Doc, "Go 1.") {
                        fmt.Printf("Version hint: %s\n", m.Doc)
                    }
                }
            }
        }
    }
}

func main() {
    checkAPIVersion("/usr/local/go/src/time", "UnixMilli")
}

3. 查看Go发行说明和变更日志

最可靠的方式是查阅官方发布文档：

# 查看特定版本的发布说明
go tool dist list -json | grep -A5 -B5 "1.17"

# 或直接访问在线文档
# https://golang.org/doc/go1.17#time

4. 使用godoc的本地版本

运行本地godoc服务器查看历史版本：

# 启动godoc服务器
godoc -http=:6060

# 然后访问 http://localhost:6060/pkg/time/
# 查看特定版本的文档需要切换Go版本

5. 通过构建标签检查可用性

在实际代码中可以通过构建标签处理版本差异：

//go:build go1.17
// +build go1.17

package main

import (
    "fmt"
    "time"
)

func main() {
    t := time.Now()
    // UnixMilli只在Go 1.17+可用
    ms := t.UnixMilli()
    fmt.Printf("Unix milliseconds: %d\n", ms)
}

6. 使用api工具检查

Go工具链中的api命令可以比较API变化：

# 比较两个版本的API差异
go tool api -diff go1.16.txt go1.17.txt | grep -i unixmilli

# 输出会显示新增的API
# pkg time, method (Time) UnixMilli() int64

虽然Go没有在文档中强制要求版本标注，但通过上述方法可以有效确定API的引入版本。对于标准库，最权威的来源始终是Go官方发布说明和源码仓库的变更历史。