关于

golang.com.cn 是中文版本的 Go 包网站。 golang.org 是 Go 开源项目的主站, 而 golang.com.cn 集中为 Go 用户提供了丰富的资源和文档,是 Go 生态重要的一环。

该站提供了:

  1. 在 index.golang.org 上发布的 Go 软件包和模块的集中信息。
  2. 在 goproxy.io 上首次获取的 Go 软件包和模块。

golang.com.cn 现在处于公开测试阶段。 我们很自豪创建了这个服务,并且很高兴能与社区分享它。希望在使用 golang.com.cn 的时候它能给你带来价值和方便。 golang.com.cn 还有很多需要改进的地方,如果你有新的想法和建议欢迎给我们反馈。

新增 Go 包

该服务的数据下载于 goproxy.io. 我们监控了 Go Module Index 和 goproxy.io,对于新发布的包会及时添加到 golang.com.cn 服务中。 如果你在 golang.com.cn 上没有看到你想找的包, 你可以通过下面几种方式进行添加:

  • 在 golang.com.cn 访问你要访问的包地址, 接着点击 “Request” 按钮. 比如:
    https://golang.com.cn/example.com/my/module

  • 对于响应的版本在 goproxy.io 上发起一个请求, 可以参考 proxy 文档 Module proxy protocol. 比如:
    https://goproxy.io/example.com/my/module/@v/v1.0.0.info

  • 通过 go command 进行响应包的下载。 比如
    GOPROXY=https://goproxy.io GO111MODULE=on go get example.com/my/module@v1.0.0

删除 Go 包

如果你是一个包的作者,并且想在 golang.com.cn 上删除它, 请 提交 issue 来删除你的包.

注意我们只能删除整个包的所有版本. 而不能只清理包的某一个版本.

文档

文档是基于 Go 包的源码生成的,这些源码包是从 goproxy.io/<module>/@v/<version>.zip 上进行下载的。 新的包版本是从 index.golang.org 和 goproxy.io 上进行获取,每几分钟 golang.com.cn 就会进行一次新增。

文档写作指南 适用于 godoc tool,在 golang.com.cn 上也会有具体的展示。

在包的第一行注释中添加一个包的介绍和摘要是非常重要的。golang.com.cn 服务会索引第一行介绍并且展示在搜索结果中。>

golang.com.cn 服务会在文档页面的最底端显示 GOOS 和 GOARCH。

最佳实践

golang.com.cn 服务展示了有关Go软件包和模块的详细信息,以帮助提供有关Go最佳实践的指南。

下面是我们推荐的几条实践:

  • 创建 go.mod 文件

    • Go module 机制在 Go 1.11 中被引入并且它是一个官方的 Go 依赖管理解决方案。一个完整的包模块由源文件构成,并且在根目录中存在 go.mod 文件。了解更多关于 go.mod 文件
  • 许可开源协议

    • 开源协议对如何使用,修改和重新分发软件设置了最小的限制。 有关 golang.com.cn 如何确定许可是否许可的更多信息,请参考的开源协议政策.
  • 版本标签

    • 当 go get 命令解析模块时会默认先获取打标的版本号。当没有打标版本时,go get 会获取最近的 commit 版本。打标的模块在被其他模块使用时更加稳定和精准。请参考semver.org and 保持你的版本向下兼容
  • 稳定版本

    • 处于 v0 版本的项目被认为是试验性版本。当项目版本达到稳定版本 — 主版本号为 v1 或者 更高 — 不兼容的变更需要在新的主版本中进行实施。 由于在小版本(minor version) 更新升级中不会存在不兼容变更,所以稳定版本的发布给了开发者使用稳定版本的信心。请参考Go Moudule: v2 and Beyond

创建徽章

golang.com.cn 徽章为 Go 用户提供了一种学习与给定 Go 软件包或模块关联的 golang.com.cn 页面的方式。 你可以通过徽章生成工具 创建属于你的徽章。 该工具会生成 html 和 markdown 代码,你可以将它添加到你的项目网站和 README 中。

golangcncom

你可以这 Go 包的 README 中添加链接,文档系统会在右侧展示出这些链接。具体可以查看这里.

页面快捷键

为了方便浏览整个文档页面,我们引入了一些快捷键, 在文档页面中输入 ‘?’ 可以查看到相关帮助。

Bookmarklet

The golang.com.cn bookmarklet navigates from pages on source code hosts, such as GitHub, Bitbucket, Launchpad etc., to the package documentation. To install the bookmarklet, click and drag the following link to your bookmark bar: golang.com.cn Doc

License policy

Information for a given package or module may be limited if we are not able to detect a suitable license. See our license policy for more information.

Feedback

Share your ideas, feature requests, and bugs on the Go Issue Tracker For questions, please post on the #tools slack channel on the Gophers Slack, or email the golang-dev mailing list.