如何用 Go 快速编写出 HTTP REST API 服务?

在本教程中,明白如何用Go语言写出一个HTTP REST API服务。

作者 |Aurelie Vache

译者 |槐序,责编 | 郭芮

出品 | CSDN(ID:CSDNnews)

以下为译文:

学习一门新语言并不容易,但是如果有具体的例子和手把手指导教程,就很容易上手了。因此,我决定编写一系列分步指导教程。

让我们使用Go语言的强大功能来编写一个HTTP REST API 服务。

Go, Go, Go

首先要做的就是安装GVM(Go版本管理器),当然还有安装GO。

要安装GO,你可以按照官方网站上的安装步骤进行操作,也可以使用GVM来安装。对于Go而言,GVM是一个非常实用的版本管理工具,它允许你通过指定所需版本来更新Go的版本。

安装

Bash:

zsh:

用法

让我们比较感兴趣的GVM 命令是gvm install命令,它的用法如下:

Go的安装:

在你的.zshrc或者.bashrc文件中,设置$GOROOT 和 $GOPATH环境变量,下面是一个例子:(原文下面的2 3 4代码行命令错误,少了空格)

以上就是利用版本管理器来安装GO。现在进入本文章的核心,来创建我们第一个CLI(命令行程序)。

初始化你的APP

现在我们在GitHub中创建一个仓库(为了共享和开源)。

首先,登录GitHub网站,单击仓库链接,创建一个名叫“http-go-server”的仓库:

然后,在你本地机器上,把这个新建的仓库克隆(git clone)到你想放的地方。

“放任何我想放的地方?你确定?”

我们会用GO模块作为依赖项,所以不要忘记在GOPATH目录外git clone。但事实上,好消息是,从GO 1.13版本开始,我们不需要再担心这个问题了。Go模块现在可以在GOPATH目录下和目录外使用。

这也是我在本文选择使用GO 1.13版本的原因。

现在,为了方便找回及同步本地代码到git仓库,我们要git clone这个仓库:

然后初始化go模块(依赖管理):

我们将创建一个简单的HTTP服务,但是为了代码组织方面具有良好实践。因此我们不会将所有的代码放到main.go文件,我们会创建一个代码目录然后管理我们的代码。

创建下面的文件目录结构:

创建一个HTTP服务

现在开始编写HTTP服务代码。

Go是一个很强大的语言。其中一个强大的功能就是有许多可用的内置包,例如net/HTTP。在internal/路径下面创建一个main.go文件,如下所示:

这个简单的例子创建了一个HTTP服务,并监听端口8080的传入请求,并在返回到根目录/。

现在构建我们的应用来测试它,然后启动应用程序二进制文件:

为了测试你的HTTP服务,你可以使用curl命令来测试下 localhost:8080,或者直接用浏览器输入这个URL来测试:

很好,我们创建了一个小型的HTTP服务,它可以正常运行。

现在我们可以在二进制可执行文件中构建它:

很好,我们在几分钟内完成了,但是我们将在下文深入了解:-)。

使用 Makefile

我不想手动执行每个命令,所以,为了持续改进我们的应用,好的方法就是创建一个Makefile 文件,这样我们就可以直接通过命令行来构建应用,生成文件,生成swagger文档,检查许可证以及执行单元测试和静态测试。

我们可以在Makefile里面定义好一系列将由make工具执行的任务。

因此,在这个项目中,我创建了一个Makefile文件,大家可以直接下载,这样就能节约大家的时间。

Makefile:https://raw.githubusercontent.com/scraly/http-go-server/master/Makefile

出于好奇,在Makefile文件中,我们创建几个指令(targets,可以是目标文件或者执行文件或者标签)用来执行一个或者多个命令。

总结下来就是,一个指令需要或者不需要依赖文件(prerequisites)都将执行方法(recipe):target: prerequisites。

recipe

在我创建的Makefile文件中,一个build指令构建和打包我们的应用为二进制文件,存放到目录bin/http-go-server下:

HTTP Endpoints 定义

现在我们将优化我们的HTTP服务,并使用Swagger,它可以处理我们的HTTP endpoints定义。

什么是Swagger?

Swagger允许你提供符合OpenAPI规范的标准化APIs文档。

因为有了Swagger应用,使用Swagger标准文件输入,你可以在最后生成代码,并且可以为用户提供HTML格式的API文档。

如果你想构建一个公共API,请不要犹豫使用Swagger。

Swagger安装:请参考go-swagger安装页面(https://github.com/go-swagger/go-swagger/blob/master/docs/install.md)。

然后,为了检查该工具在你的系统中正确安装,你可以检查Swagger的版本。

现在要做的第一件事是在我们的代码中创建swagger标准文档:

pkg/swagger/swagger.yml:

每次修改swagger文件后,一个好的做法是检查文件的有效性。

为此,我们可以使用swagger validate命令:

或者可以使用一个Makefile指令:

太棒了,我们的Swagger文件是有效的。

现在我们将在HTML文档中创建Swagger定义。为此,我们可以使用Docker镜像,该镜像考虑到了Swagger YAML定义并且返回一个漂亮的HTML页面。

如果你在浏览器中打开已经生成的doc/index.html页面,可以查看HTML endpoints定义:

很好,是具有可读性的。

归功于Swagger规范,现在我们可以生成代码。

为此,我们进入到pkg/swagger/目录,创建一个gen.go文件,如下所示:

由于有Makefile,我们可以执行生成swagger go代码的文件:

如下所示,使用一个swagger endpoint定义输入,生成了很多代码,这对于HTTP服务器的实现是节省了时间的。

下面使用Swagger编辑main.go文件:

现在启动服务:

现在我们可以做几个测试:

完美,我们的HTTP服务正在应答,甚至告知我们GetHelloUser接口尚未实现,接下来实现它吧!

编辑main.go文件如下所示:

再来一次,我们重启服务:

很好,我们有一个遵守OpenAPI规范的HTTP服务和两个路由:

GET/healthz

GET/hello/

我们可以到此为止,因为我们的HTTP服务正常工作,但是我们将继续深入。

我们将在main.go文件(在文件末尾)中,为路由实现增加新函数。

现在我们只需在主函数中调用这些新函数:

和之前一样,我们测试静态测试是否通过,以及我们应用是否构建:

测试静态代码

另外一个好的做法是使用linters 分析来做静态代码测试。为此,我们可以使用golang-ci工具(Go里的快速linter,比gometaliner好)。

还是因为有了Makefile,你只需要获取此处我列出的工具,例如golang-cli:

一个好的做法是新建一个.golangci.yml文件来定义我们想要的linter配置。下面是golang-cli配置示例:

接下来我们可以检查代码是否包含lint错误:

很好,一起都好。

如果你想编辑.golangci.yml文件,请查看golang-ci支持的linters。

检查许可证

另外一个好的实践是检查许可证。

你需要去检查许可证(你项目依赖项使用的许可证),例如,当你希望你的应用程序或者公司的代码开源时,为了避免使用被禁的许可证,就要去检查。

在Go中存在一个名为wwhrd的工具。

首先,我们创建一个名为.wwhrd.yml的文件,来定义选项:

在这个wwhrd文件特性中,你可以添加例外项,黑名单和白名单特性。

一个检查证书的指令已经写在了Makefile文件中的,因此你只需要执行它即可:

很好,没有许可证问题了。

构建应用

现在,我们可以在一个可执行的二进制文件里构建应用,并测试二进制文件:

非常棒:-)

总结

正如你在这篇文章第一部分看到的一样,使用net/http包和Gorilla/mux作为路由,可以在几分钟或几秒钟内创建一个HTTP服务,但是我想向你展示的是,在代码组织的最佳实践方面如何一步一步深入。为了符合OpenAPI标准使用了Swagger,还使用一些其他有用的工具。

最后,我们小型的HTTP服务成长了一些,如下代码目录结构所示:

所有的代码都可以在GitHub仓库找到:https://github.com/scraly/http-go-server,希望这类文章对你有所帮助。

原文:https://dzone.com/articles/how-to-write-a-http-rest-api-server-in-go-in-minut

本文为 CSDN 翻译,转载请注明来源出处。

【End】

热 文推 荐

  • 发表于:
  • 原文链接https://kuaibao.qq.com/s/20191209A0GSPY00?refer=cp_1026
  • 腾讯「云+社区」是腾讯内容开放平台帐号(企鹅号)传播渠道之一,根据《腾讯内容开放平台服务协议》转载发布内容。
  • 如有侵权,请联系 yunjia_community@tencent.com 删除。

扫码关注云+社区

领取腾讯云代金券