【译文】原文地址
本教程是关于如何在Go中使用自动生成Swagger文档和热加载构建一个REST-API。热加载不仅仅意味着热加载我们的Go应用程序，包括重新构建和重新启动，还需要在前台重新创建所有的Swagger文档。
我假设你已经对用Go构建REST API很熟悉了，所以我就不重复关于这方面的很多内容了。
值得一提的是，我们当前的设置，特别是Swagger部分，是建立在https://github.com/swaggo/swag这个神奇的库上的。这个库可以使我们能够从模型和控制器当中自动生成Swagger文档。
通常我和我的团队在处理这方面的工作时，默认流程是：
- 写代码
- 为Swagger写注解
- 生成Swagger文档
- 编译
- 执行
- 观察和测试
如果我们添加了更多代码，或者只是修改了一个拼写错误，我们就必须重新执行上面的步骤。起初，我们确实这么做的。后来我们开始使用Makefile尽可能的自动化上面的步骤。
但不管怎么说，这总觉得“不对”。因为我们都在web开发上钻研了好几年，无论是用PHP、NodeJs或Python，还是用React Native或Flutter进行跨平台应用开发，与Go相关的开发让人感觉笨拙和低效。
因为我不想重复造轮子，所以就寻找其他人使用的合适方法。偶然间，我发现了这篇文件，它为我指明了方向。
1. 我们的方法：构建一个“自动加载的容器”
根据前面提到的文章，我使用CompileDaemon创建了一个Dockerfile，这使我们能够对源代码文件的任何更改都会重新构建和重新启动应用程序：
FROM golang:latest
WORKDIR /app
COPY ./ /app
RUN go mod download -x
RUN go get github.com/githubnemo/CompileDaemon
ENTRYPOINT CompileDaemon -exclude-dir=.git -exclude-dir=docs --build="go build main.go" --command=./main
这个Dockerfile将创建一个Docker容器，为Golang编写的应用程序的编译和运行准备好一切。此外，CompileDeamon可以复制我们的工程和负责热加载。在任何时候我们更改一个文件，这个容器都将重新编译应用程序并重启它。这意味着，当我们在web浏览器中按F5和Cmd-R时，我们将在“http://localhost”处看到应用程序的新编译状态。
需要注意的是我们必须将存放Swagger文档的“docs”目录的修改排除在外，因为重新生成这些文件会导致应用程序的重复构建。
自动生成Swagger文件
使用https://github.com/swaggo/swag作为我们的Swagger自动生成器，在每次代码变更后，我们习惯在命令行上执行“swag init”，该命令会根据代码文件中的注解强制重新创建所有的swagger文档。
使用Docker运行我们的应用程序，如果我们现在在终端中输入“swag init”，它就会执行这些任务，也会导致Docker容器重新构建我们的应用程序。2秒后——取决于你的机器和CPU的功率——我们就能看到我们API的新生成的Swagger文档。
如果更改一个文件比如重新编译也会导致这种自动生成过程的发生，这不好吗？再比如，任何代码或者注解的更新都会导致Swagger文档的重新创建以及应用程序的重新构建和重启，这不更好吗？
这是我们接下来要讨论的问题。
把所有的都放在一起
到目前为止，我们已经有一个Docker容器，它能够在每次修改代码文件后重新构建我们的应用程序，并将web服务器服务到本地主机。
现在还缺少的是Swagger文档的自动生成功能。因此我们在终端输入“swag init”。但是这个命令是哪来的呢？最初我们搭建这个工程时，我们浏览了https://github.com/swaggo/swag的说明，并且很可能使用了一个预发布版本来将二进制文件安装到我们的系统上。我自己使用的是Macbook Pro，我的大多数同事都在使用Linux机器。但是，这个代码库的发布页面为我们提供了所有版本。否则，每个人都可以自由地从头开始，自己编译它。
为了让“swag”作为一个工具安装在Docker容器中，我们需要从源代码中从头开始构建该命令行工具。每次我们的容器需要被重新构建（在这种大量开发和特定的设置中会频繁发生）。
但是我拒绝在我们自己的Dockerfile中这样做，因为我认为这样的工具应该可以直接获取并“安装”，而不需要在我们的Docker容器每次构建时克隆和编译。
由于 https://github.com/swaggo/swag仓库并没有提供任何Dockerfile来解决这个问题，我自己fork一个分支并写了一个Dockerfile，它将编译命令行工具“swag”并提供执行的二进制文件。
有了这个Dockerfile，就能够构建一个Docker镜像并将其推送到Dockerhub上，供其他Dockerfile复用。
重建Dockerfile
由于CompileDaemon在文件系统发生更改后只能使用一个命令重新构建应用程序，所以我们必须融合重新生成Swagger文件和编译我们的Go应用程序。
首先，我在Makefile中创建了一个部分来处理这些任务:
build-dev:
swag init
go build -v main.go
这个任务将首先创建Swagger文件，然后编译我们的应用程序。
此外，我们必须提供编译的“swag”可执行文件。为了实现这一点，我们只需要从上面几段构建的swag容器中复制它:
FROM golang:latest
RUN apt-get update && apt-get install make bash
WORKDIR /app
COPY ./ /app
RUN go mod download -x
COPY --from=itinance/swag /root/swag /usr/local/bin
RUN go get github.com/githubnemo/CompileDaemon
ENTRYPOINT CompileDaemon -exclude-dir=.git -exclude-dir=docs --build="make build-dev" --command=./main
这个Dockerfile将在容器中安装make和bash，拷贝我们的应用程序代码，下载所有的依赖，拷贝“swag”命令行工具到/usr/local/bin中，以便在环境变量$PATH中能找到，如果发生任何更改源代码,下面的步骤将执行:
- 生成Swagger文档
- 重新构建整个应用
- 重启服务并监听80端口
从现在起，我们可以自由地在代码仓库中删除Swagger文件，使提交更易于阅读，因为我们只需要关注最终的代码变更即可，不需要查看Swagger文档。
总结
为了让事情变得更简单，结合docker-compose，其他的容器将启动像Postgres SQL, ElasticSearch, Kafka和ZooKeepers，我们尝试用Makefile来简化这些不同的任务。
# (C) 2020 Hagen Huebel, ITinance GmbH https://itinance.com, dedified GmbH https://dedified.io
# All rights reserved.
VersionFile=VERSION
VERSION=`cat $(VersionFile)`
start:
docker-compose up -d
stop:
docker-compose stop
build:
docker-compose build
show-version:
echo ${VERSION}
inc-version:
go run cmd/release/inc-version.go
rebuild:
go build && swag init && make fix-swagger-models
run-with-swagger:
go build && swag init && make fix-swagger-models && go run main.go
build-prod:
docker build -t itinance/emoney-payment-api-gateway:latest -t itinance/emoney-payment-api-gateway:v${VERSION} .
push-prod:
docker push itinance/emoney-payment-api-gateway:latest
docker push itinance/emoney-payment-api-gateway:v${VERSION}
# fix-swagger-models
# swaggo/swag has a bug that will prevent renaming of Models from "model.Account" ino "Account"
# we are going to fix this generation with this command
fix-swagger-models:
./fix-swagger-files.sh
build-dev:
swag init
./fix-swagger-files.sh
go build -v main.go
我们的应用程序的docker-compose文件如下所示:
# (C) 2020 Hagen Huebel, ITinance GmbH https://itinance.com, dedified GmbH https://dedified.io
# All rights reserved.
version: "3"
services:
api-gateway:
build:
dockerfile: Dockerfile
context: .
ports:
- '80:80'
volumes:
- ./:/app
- 使用“make start”命令开始工作
- 使用“make build”重建所有的容器
- 使用“make stop”停止工作
