Go Web 框架 Gin 实践8—为它加上Swagger，帅帅的文档

一个好的 API's，必然离不开一个好的API文档

要开发纯手写 API 文档，不存在的 :=)

项目地址：>

注：本文选用树莓派做测试，因为树莓派是基于ARM平台的。

1、编译工具配置

据说下个版本的golang编译工具要使用golang自己来写，但目前还是使用C编译工具的。因此，首先要配置好C编译工具：

11在Ubuntu或Debian平台上可以使用sudoapt-getinstallgcclibc6-dev命令安装，树莓派的RaspBian系统是基于Debian修改的，所以可以使用这种方法安装。

12在RedHat或CentOS6平台上可以使用sudoyuminstallgcclibc-devel命令安装。

安装完成后可以输入gcc--version命令验证是否成功安装。

2、获取golang源代码

21直接从官网下载源代码压缩包。

golang官网提供golang的源代码压缩包，可以直接下载，最新的141版本源代码链接：/golang/go141srctargz

22使用git工具获取。

golang使用git版本管理工具，也可以使用git获取golang源代码。推荐使用这个方法，因为以后可以随时获取最新的golang源代码。

221首先确认ARM平台上已经安装了git工具，可以使用git--version命令确认。一般linux平台都安装了git，没有的话可以自行安装，不同平台的安装方法可以参考：download/linux

222克隆远程golang的git仓库到本地

在终端cd到你想要安装golang的目录，确保该目录下没有名为go的目录。然后以下命令获取代码仓库：

gitclone/go

大陆地区可能会获取失败，在不**的情况下我试了几次都没成功，原因大家都懂的。好在google已经将golang也托管到github上面，所以也可以通过下面命令获取：

gitclone/golang/gogit

视网络情况，下载可能需要不少时间。我2M的带宽花了将近两个小时才下载完，虽然整个项目不过几十兆==

下载完成后，可以看到目录下多了一个go目录，里面即为golang的源代码，在终端上执行cdgo命令进入该目录。

执行下面命令检出go141版本的源代码，因为现在已经有新的代码提交上去了，最新的代码可能不是最稳定的：

gitcheckoutgo141

至此，最新141发行版的源代码获取完毕

3、设置golang的编译环境变量

主要有GOROOT、GOOS、GOARCH、GOARM四个环境变量需要设置，先解释四个环境变量的意义。

31GOROOT

主要代表golang树结构目录的路径，也就是上面git检出的go目录。一般可以不用设置这个环境变量，因为编译的时候默认会以go目录下src子目录中的allbash脚本运行时的父目录作为GOROOT的值。为了保险起见，可以直接设置为go目录的路径。

32GOOS和GOARCH

分别代表编译的目标系统和平台，可选值如下：

GOOSGOARCH

darwin386

darwinamd64

dragonfly386

dragonflyamd64

freebsd386

freebsdamd64

freebsdarm

linux386

linuxamd64

linuxarm

netbsd386

netbsdamd64

netbsdarm

openbsd386

openbsdamd64

plan9386

plan9amd64

solarisamd64

windows386

windowsamd64

需要注意的是这两个值代表的是目标系统和平台，而不是编译源代码的系统和平台。树莓派的RaspBian是linux系统，所以这些GOOS设置为linux，GOARCH设置为arm。

33GOARM

表示使用的浮点运算协处理器版本号，只对arm平台有用，可选值有5，6，7。如果是在目标平台上编译源代码，这个值可以不设置，它会自动判断需要使用哪一个版本。

总结下来，在树莓派上设置golang的编译环境变量，可编辑$HOME/bashrc文件，在末尾添加下面内容：

exportGOROOT=你的go目录路径

exportGOOS=linux

exportGOARCH=arm

编辑完后保存，执行source~/bashrc命令让修改生效。

4、编译源代码

环境变量配置完成自后就可以开始编译源代码。在go目录下的src子目录中，主要有allbash和makebash两个脚本（另外还有两个allbat和makebat脚本适用于window平台）。编译实际上就是执行其中一个脚本，两者的区别在于allbash在编译完成后还会执行一些测试套件。如果希望只编译不测试，可以运行makebash脚本。使用cd命令进入go下src目录，执行/allbash或者/makebash命令即可开始编译。由于硬件情况不同，编译耗费的时间不同。在我的B型树莓派编译过程花费了将近半个小时，编译完成后执行的测试套件又花费了差不多一个小时，总共花费了一个半小时左右。

5、配置golang运行环境变量

编译完成后，go目录下会生成bin目录，里面就是go的运行脚本。为了以后使用方法，可以将这个bin路径添加到PATH环境变量中。同样编辑~/bashrc文件，因为前面设置过GOROOT环境变量指向go目录了，所以只需要在末尾加上

exportPATH=$PATH:$GOROOT/bin

保存后同样执行source~/bashrc命令让环境变量生效。

至此，golang源代码编译安装成功。执行goversion应该就能看到当前golang的版本信息，表示编译安装成功。

• 随着 2022 年 3 月 15 日 go 118 正式发布，新版本除了对性能的提升之外，还引入了很多新功能，其中就有 go 期盼已久的功能泛型(Generics)，同时还引入的多模块工作区(Workspaces)和模糊测试(Fuzzing)。

• 关于泛型网上已经有很多介绍的教程了，这里我介绍一个实用的功能，多模块工作区的使用方法和教程。

• Go 多模块工作区能够使开发者能够更容易地同时处理多个模块的工作，如:

• 多模块工作区

• 开发流程演示

• 总结

• 参考文献

• go 使用的是多模块工作区，可以让开发者更容易同时处理多个模块的开发。在 Go 117 之前，只能使用 gomod replace 指令来实现，如果你正巧是同时进行多个模块的开发，使用它可能是很痛苦的。每次当你想要提交代码的时候，都不得不删除掉 gomod 中的 replace 才能使模块稳定的发布版本。 •在使用 go 118 多模块工作区功能的时候，就使用这项工作变得简单容易处理。下面我来介绍怎么使用这一功能。• Go 多模块工作区文档、代码示例[5]

• 首先 我们需要 go 118 或更高版本 go 安装[6]

• 通常情况下，建议不要提交 gowork 文件到 git 上，因为它主要用于本地代码开发。

• 推荐在: $GOPATH 路径下执行，生成 gowork 文件

• go work init 初始化工作区文件，用于生成 gowork 工作区文件

• go work use 添加新的模块到工作区

• go work edit 用于编辑 gowork 文件

• go work sync 将工作区的构建列表同步到工作区的模块

• go env GOWORK

• 文件结构和 gomod 文件结构类似，支持 Go 版本号、指定工作区和需要替换的仓库 •文件结构示例:

• 可以使用 go work use hello 添加模块，也可以手动修改 gowork 工作区添加新的模块 •在工作区中添加了模块路径，编译的时候会自动使用 use 中的本地代码进行代码编译，和 replaces 功能类似。

• replaces 命令与 gomod 指令相同，用于替换项目中依赖的仓库地址 •需要注意的是 replaces 和 use 不能同时指定相同的本地路径

• 错误示例

• 在同时使用 gowork 和 gomod replace 功能的的时候分别指定不同的代码仓库路径， gowork 优先级高于 gomod 中定义

• 在代码构建时候使用的是 gowork 指定的 example1 仓库的代码， gowork 优先级别更高

• 在 Go 118 go run 和 go build 都会默认使用工作区功能 • GOWORK 也可以指定配置 gowork 文件位置

• Go 全局变量 GOWORK 设置 off 则可以禁用工作区功能

• 演示如何使用多模块工作区功能。在现在微服务盛行的年代，一个人会维护多个代码仓库，很多的时候是多个仓库进行同时开发

• 假设我们现在进行 hello 仓库开发，实现的功能是，实现将输入的字符串反转并输出，字符串反转功能依赖于 githubcom/link1st/example (下文统称 example )公共仓库实现

• 新建 hello 项目

• maingo 代码

• 运行代码 go run maingo -str "hello world" 或 go run githubcom/link1st/link1st/workspaces/hello -str "hello world" 可以看到输出了 hello world 反转以后的字符串

• 到这里，最初的功能已经完成，但是后续需求变动，不仅需要输出反转以后的字符串，还需要将字符串大写

• 我们则需要去 example 仓库中添加开发 将字符串大写的功能

• vim example/stringutil/to_uppergo 代码如下

• 由于代码还在本地调试，未提交 git 仓库中，这个时候就需要用到 Go 多模块工作区的功能了。

• 进入项目根目录，初始化我们现在正在开发的模块

• 文件结构如下

• 回到 hello 项目， vim maingo 将字符串大写的功能添加上。

• 运行代码

• 到这里，演示的代码已经全部完成

• 使用 Go 多模块工作区的功能，可以让我们轻松在多个模块之间切换工作，更能适应现代微服务架构开发。

[1] Go 118 新特性多模块工作区教程: >

这个项目可以理解为针对互联网IT人打造的中文版awesome-go。已有的awesome-go项目， 汇总了很多go开源项目， 但存在的问题是收集太全了， 而且每个项目没有详细描述。

本项目作为awesome-go的一个扩展，根据go语言中文社区提供的资料，还有互联网企业架构设计中的常见组件分类， 共精心挑选了153个开源项目（项目不限于在github开源的项目）， 分成以下17个大类。

项目初衷是帮助到那些想学习和借鉴优秀golang开源项目， 和在互联网架构设计时期望快速寻找合适轮子的人。

ps: 以下项目 star数均大于100 ，且会定期检查项目的url，剔除无效链接。 每个分类下的项目会按照 star数从高到低 进行排列。

当您的代码使用外部包时，这些包（作为模块分发）成为依赖项。随着时间的推移，您可能需要升级或更换它们。Go 提供了依赖管理工具，可帮助您在合并外部依赖项时确保 Go 应用程序的安全。

本主题介绍如何执行任务以管理您在代码中承担的依赖项。您可以使用 Go 工具执行其中的大部分 *** 作。本主题还介绍了如何执行其他一些您可能会觉得有用的依赖相关任务。

您可以通过 Go 工具获取和使用有用的包。在 pkggodev 上，您可以搜索您可能觉得有用的包，然后使用go命令将这些包导入您自己的代码中以调用它们的功能。

下面列出了最常见的依赖项管理步骤。

在 Go 中，您将依赖项作为包含您导入的包的模块来管理。此过程由以下机构支持：

您可以搜索pkggodev以查找具有您可能觉得有用的功能的软件包。

找到要在代码中使用的包后，在页面顶部找到包路径，然后单击复制路径按钮将路径复制到剪贴板。在您自己的代码中，将路径粘贴到导入语句中，如下例所示：

在您的代码导入包后，启用依赖项跟踪并获取包的代码进行编译。

要跟踪和管理您添加的依赖项，您首先要将代码放入其自己的模块中。这会在源代码树的根目录创建一个 gomod 文件。您添加的依赖项将列在该文件中。

要将您的代码添加到它自己的模块中，请使用 go mod init命令。例如，从命令行切换到代码的根目录，然后按照以下示例运行命令：

该go mod init命令的参数是您的模块的模块路径。如果可能，模块路径应该是源代码的存储库位置。

如果一开始您不知道模块的最终存储库位置，请使用安全的替代品。这可能是您拥有的域的名称或您控制的另一个名称（例如您的公司名称），以及来自模块名称或源目录的路径。

当您使用 Go 工具管理依赖项时，这些工具会更新 gomod 文件，以便它维护您的依赖项的当前列表。

添加依赖项时，Go 工具还会创建一个 gosum 文件，其中包含您所依赖的模块的校验和。Go 使用它来验证下载的模块文件的完整性，特别是对于在您的项目上工作的其他开发人员。

在代码中包含存储库中的 gomod 和 gosum 文件。

当您运行go mod init创建用于跟踪依赖项的模块时，您指定一个模块路径作为模块的名称。模块路径成为模块中包的导入路径前缀。一定要指定一个不会与其他模块的模块路径冲突的模块路径。

至少，一个模块路径只需要表明它的来源，例如公司或作者或所有者名称。但是路径也可能更能描述模块是什么或做什么。

模块路径通常采用以下形式：

1、Go 工具可以在其中找到模块源代码的存储库的位置。

例如，它可能是githubcom/ /

如果您认为您可能会发布模块供其他人使用，请使用此最佳实践。

2、一个你控制的名字。

如果您不使用存储库名称，请务必选择一个您确信不会被其他人使用的前缀。一个不错的选择是您公司的名称。避免使用常用术语，例如widgets、utilities或 app。

Go 保证以下字符串不会在包名称中使用。

1、test– 您可以将test用作模块路径前缀以便代码用于在另一个模块中本地测试功能进行测试。

使用test作为模块路径前缀是测试的一部分。例如，您的测试本身可能会运行go mod init test，然后以某种特定方式设置该模块，以便使用 Go 源代码分析工具进行测试。

2、example– 在某些 Go 文档中用作模块路径前缀，例如在创建模块以跟踪依赖关系的教程中。

请注意，Go 文档还用于examplecom说明示例何时可能是已发布的模块。

以上就是关于Go Web 框架 Gin 实践8—为它加上Swagger，帅帅的文档全部的内容，包括:Go Web 框架 Gin 实践8—为它加上Swagger，帅帅的文档、如何编译armlinux的go、Go 1.18 新特性多模块工作区教程等相关内容解答，如果想了解更多相关内容，可以关注我们，你们的支持是我们更新的动力！