【原】Go 新手编译 quorum 的 API 文档

我通过自学掌握了一些 Python 编程，但不懂 Go 语言。所以采用 Go 语言实现的 quorum 底层代码仓库 开源后，我就在想：作为一个新手，我该怎么试试呢？

在首次尝试时，我花了两三天的业余时间，终于完成了 README.md 如何开始的第一步：生成 API 文档，并随手做了一些笔记。两个月过去，我再次尝试时，发现自己依然会遇到不少“麻烦”，但原来的笔记也不太能看懂了。我意识到，我需要把我之前的笔记整理一下，能够方便自己未来继续玩，公开出来也能方便其它爱尝试的新手参考。

这篇攻略分外基础，技术牛人们可直接忽略。

假设你已经把 quorum 代码仓库 clone 到本地，现在试着编译出 API 文档。

大量 .go 文件是红色的？别被迷惑

我遇到的一个困惑是，本地用 vscode 打开 quorum 代码仓库后，发现大量 .go 文件变红。按经验，这是有语法错误提醒。几乎都是导入模块失效，找不到对应的模块。

有效的应对策略：暂时不用管。

接触到任何新仓库，优先去通读 README.md，按这个说明文档来找到操作指引。

如何开始？第一步：生成 API 文档

在 README.md 文档中介绍了如何开始，而第一步，我需要做的，只有区区下列几行字。

Build API Document:

```bash
./scripts/swag_init.sh
go run cmd/docs.go

```

Open browser with http://localhost:1323/swagger/index.html

我本以为这很简单，但实际上，对于本地 go 环境不健全的我来说，困难重重。基本上就是：执行一次，遇到一个报错，尝试解决这个报错，然后再次执行，再次报错，再次解决……重复很多次后，直至毫无报错，并能访问上述网页，查看到 API 信息。

下面是我执行上上述代码后，遇到的一些报错和解决办法。可供参考。

如果你遇到的报错信息，在这篇文章没有提及，可以直接上网搜索解决。

报错：Access is denied.权限不足

遇到一个报错：Access is denied. 详情如下：

go: writing go.mod cache: mkdir C:\Program Files\Go\bin\pkg\mod\cache\download\github.com\prometheus: Access is denied.
go: writing go.mod cache: mkdir C:\Program Files\Go\bin\pkg\mod\cache\download\google.golang.org: Access is denied.
go: writing go.mod cache: mkdir C:\Program Files\Go\bin\pkg\mod\cache\download\github.com\prometheus: Access is denied.
go: writing go.mod cache: mkdir C:\Program Files\Go\bin\pkg\mod\cache\download\github.com\prometheus: Access is denied.
go: downloading github.com/swaggo/echo-swagger v1.1.0
go: downloading github.com/labstack/echo/v4 v4.3.0
cmd\docs.go:4:2: mkdir C:\Program Files\Go\bin\pkg\mod\cache\download\github.com\labstack: Access is denied.
cmd\docs.go:7:2: no required module provides package github.com/rumsystem/quorum/docs; to add it:
go get github.com/rumsystem/quorum/docs
cmd\docs.go:5:2: mkdir C:\Program Files\Go\bin\pkg\mod\cache\download\github.com\swaggo: Access is denied.


解决办法：搜索“如何获得 WIN10 下 C 盘文件夹写入权限”

报错：no required module provides ... 包不存在

再次遇到报错：no required module provides package 详情如下


cmd\docs.go:7:2: no required module provides package github.com/rumsystem/quorum/docs; to add it:
go get github.com/rumsystem/quorum/docs


这个报错信息很简单，有明确的操作提示。所以就按提示执行：


D:\Jupyter\quorum> go get github.com/rumsystem/quorum/docs


但执行后依然报错：


go get github.com/rumsystem/quorum/docs: no matching versions for query "upgrade"


我试了一个“馊主意”，去源码把 docs.go 注释掉：

//_ "github.com/rumsystem/quorum/docs" // docs is generated by Swag CLI, you have to import it.


再次执行 go run cmd/docs.go，终于成功。看来一切顺利。胜利曙光在望。


____ __
/ __/___/ / ___
/ _// __/ _ \/ _ \
/___/\__/_//_/\___/ v4.3.0
High performance, minimalist Go web framework
https://echo.labstack.com
____________________________________O/_______
O\
⇨ http server started on [::]:1323


尝试访问 http://localhost:1323/swagger/index.html 但遇到报错：


index.js:1 GET http://localhost:1323/swagger/doc.json 500 (Internal Server Error)


还记得吧？上面通过注释的方式，跳过了 docs 的报错。看来 docs 库的问题，还是需要解决，不能跳过。

怎么办？去读源码，./scripts/swag_init.sh ，然后尝试直接执行 swag init -g ./cmd/main.go --parseDependency --parseInternal --parseDepth 2 。

依然报错：


PS D:\Jupyter\quorum> swag init -g ./cmd/main.go --parseDependency --parseInternal --parseDepth 2
swag : 无法将“swag”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。请检查名称的拼写，如果包括路径，请确保路径正确，然后再试一次。


根源是：swag没有安装，只是下载了而已。

报错：无法将“swag”项识别为…… 没安装 swag 工具

怎么安装 swag 呢？

windows 下没有 bin 目录，首先我们需要找到 swag 的下载位置 *…/github.com\swaggo\swag@v1.5.1\cmd\swag*。

在该目录下执行 go install 会生成 swag.exe 到 gopath 的主目录下。这个 swag.exe 就可以用来执行 swag init 操作了。

但是我没成功？原来是目录不对，在 #gopath/bin/bin 下，主动挪一下目录就可以了。

也许你想研究下 swaggo 的介绍 https://blog.csdn.net/Kingtu_linux/article/details/106840786 其实前面很多次没能执行成功，都是因为本地环境没有 swag 。

报错：no Go files in D:\Jupyter\quorum

终于安装好了 swag，继续执行 ./scripts/swag_init.sh ，还是报错：


2021/10/13 00:15:39 Generate swagger docs....
2021/10/13 00:15:39 Generate general API Info, search dir:./
2021/10/13 00:15:40 warning: failed to get package name in dir: ./, error: execute go list command, exit status 1, stdout:, stderr:no Go files in D:\Jupyter\quorum


修改一下 swag_init.sh 里的目录参数，然后就成功了。可以访问到 API 网页了。

修改前：


#!/bin/bash
cd "$(dirname "$0")"
cd ..
swag init -g ./cmd/main.go --parseDependency --parseInternal --parseDepth 2



修改后：

#!/bin/bash
#cd "$(dirname "$0")" #此写法的作用为：切换到 脚本 所在的目录
cd D:/Jupyter/quorum/cmd
swag init -g D:/Jupyter/quorum/cmd/main.go --parseDependency --parseInternal --parseDepth 2


后来呢？

后来我发现，链端底层的代码太难懂了。对于自学编程的人来说，参与链端底层甚至想要贡献一点源代码，估计是个比较遥远的事情。

不如掌握 JavaScript 然后去研究 quorum APP 端的源码。毕竟 APP 端出成果更容易：

1) 你可以直接魔改现有的模板。然后自己编译 app 用着玩。也可以发行出去，让别人玩。

2) 你也可以自行开发更多模板，开发你的基于 quorum 底层的第三方应用。

quorum 的底层和 app 端都开源了。你如果和我一样，基于自学编程、练手好玩、想让代码贡献者的名录上有自己等等，那你将如何参与呢？欢迎留言告诉我。也欢迎分享你的笔记或经验。