使用 Beego 搭建 Restful API 项目

1 环境准备

首先你需要在你的环境安装以下软件：

• go：编程语言运行环境
• git：版本控制工具
• beego：go 语言流行的开发框架
• bee：beego 配套的快速搭建工具
• 你喜欢的数据库：这里以 postgres 为例

1.1 go

官网下载地址： https://golang.org/dl/

注意：安装完 go 后，一定要手动配置好 $GOPATH。bee 可执行文件默认存放在 $GOPATH/bin 里面，所以您还需要把 $GOPATH/bin 添加到您的环境变量中。

1.2 git

官网下载地址： https://git-scm.com/downloads

1.3 beego

使用如下命令安装：

go get github.com/astaxie/beego

更多详情可参考官方文档： beego 的安装

1.4 bee

使用如下命令安装：

go get github.com/beego/bee

更多详情可参考官方文档： Bee 工具的使用

1.5 数据库

postgres官网下载地址： https://www.postgresql.org/download/

2 使用bee工具

bee 是 beego 框架自带配套的高效工具。使用之后，相信你会惊叹他的产出！在此之前，你先确保数据库已经设计完毕，数据库设计不在本篇文章的范畴之内。

2.1 生成项目目录结构

如果你只是想搭建一个 api 服务，不带前端网页开发，可以使用如下命令：

bee api YOUR_PROJECT_NAME

就这样一个简单的命令，一个项目雏形就搭好了。

可以执行如下命令，跑起来看看。默认地址是： http://localhost:8080

bee run

如果你的8080端口被占用了，可以修改 conf/app.conf 文件调整端口号。如下所示，把端口调整到9000：

httpport = 9000

2.2 连接数据库生成代码

你是不是想过生成目录结构之后，需要自己手动编写 model 和 controller。这里可以负责任的告诉你：常规的 CRUD 完全不需要你手动编写一行代码。以 postgres 为例，只需运行如下命令即可：

bee generate appcode -driver=postgres -conn="postgres://YOUR_USERNAME:YOUR_PASSWORD@127.0.0.1:5432/YOUR_DBNAME?sslmode=disable"

运行命令之后你的目录，就会生成 Controller、Model 和 Router 文件。更多细致的调控可参考官方文档： Bee 工具的使用 - generate 命令 。

还没完，你还没告诉项目你的数据库连接字符串，不然它不会知道你的数据库在哪里，代码如下所示：

package main

import (
    _ "kun/routers"

    "github.com/astaxie/beego"
    "github.com/astaxie/beego/orm" // 1.引入orm
    _ "github.com/lib/pq" // 2.引入postgres数据库驱动器
)

func main() {
    if beego.BConfig.RunMode == "dev" {
        beego.BConfig.WebConfig.DirectoryIndex = true
        beego.BConfig.WebConfig.StaticDir["/swagger"] = "swagger"
    }
    // 3.注册默认数据库连接字符串
    orm.RegisterDataBase("default", "postgres", "postgres://YOUR_USERNAME:YOUR_PASSWORD@127.0.0.1:5432/YOUR_DBNAME?sslmode=disable")
    beego.Run()
}

数据库驱动器需要你事先手动获取，以postgres为例，命令如下：

go get github.com/lib/pq

2.3 生成Swagger文档

其实文档的大部分工作不论是在示例代码还是生成代码都已经给做了（留意控制器代码上的注释），你只需要修改下相应配置即可。在 beego 1.7+ 版本，只需要在 conf/app.conf 打开如下开关：

EnableDocs = true

做完之后，使用如下的命令跑你的项目：

bee run -gendoc=true -downdoc=true

• -gendoc=true 表示每次自动化的 build 文档
• -downdoc=true 就会自动的下载 swagger 文档查看器

跑起来之后，默认文档路径是： http://localhost:8080/swagger/ 。如下图示：

swagger

关于如何在控制器中编写相应的 Swagger 文档注释，可参考 API自动化文档 。

有点美中不足的是，生成 api 地址都是单数形式，比如 /article，而 Restful API 最佳实践是复数形式。如果你介意的话，不妨手动修改下 /routers/router.go 文件，修改之后的文档图示如下：

复数形式的API - swagger

这样就感觉就好多了。到此为止，一个完整的带有文档的 Restful API 项目就搭建好了，包含了基本的 CRUD 操作。顺道一提，还有分页和 排序 功能以及强大灵活的查询方式！

3 总结

本篇文章虽然比不上官方文档的详尽，但是重在于提供了一个清晰明了的简短流程，以及具有强烈的目标性：如何使用 beego 快速搭建带文档的 Restful API 项目。如果你存在困惑，不妨直接查看官方文档，官方文档写的非常简单友好，相信你定会有收获。顺道一提，go 语言的适用场景不仅仅是替代 c 语言所能做的事情，包括 API 服务和 web 服务等，它也是得心应手。