体验 Beego API 开发和自动化文档

学习 Go 的基础语法时候,我就看到一些相关博客,说用 Go 来开发 API 非常简单友好。随手 Google 了一下,当时就看到可以用 Beego 框架来开发 API 并且还能结合 Swagger 自动化生成文档。当时也没有时间或者没有响应基础知识体验一下,近来时间宽裕了不少。话不多说,跟随官方文档来体验一番。不过官方文档对于基础的数据库知识介绍的一笔带过啦。

数据导入

肯定要在本地安装、配置好数据库,写入数据信息。我们选择 MySql 数据库,毕竟这个用的还是挺多的 。具体的 Mac 平台下的安装配置自己 Goolge 一下就好了。还要推荐一个 Mac 平台下的数据库可视化工具—Sequel Pro。我个人也是刚接触这个可视化工具,还有许多不熟悉,边用边摸索吧。具体关于这个数据管理软件的使用可以参见这里

接下来数据库的建表(建表名称为 app)语句如下所示:

CREATE TABLE `app` (
  `id` int(11) NOT NULL AUTO_INCREMENT,
  `create_date` datetime NOT NULL,
  `app_code` varchar(255) COLLATE utf8_unicode_ci NOT NULL,
  `app_name` varchar(255) COLLATE utf8_unicode_ci NOT NULL,
  `publish_date` date DEFAULT NULL,
  PRIMARY KEY (`id`),
  UNIQUE KEY `app_code` (`app_code`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_unicode_ci;

向 app 表插入两条数据:

INSERT INTO `app` VALUES ('1', NOW(), '100000', '神庙逃亡', '2015-08-06');
INSERT INTO `app` VALUES ('2', NOW(), '100001', '愤怒的小鸟', '2015-08-06');

对应的终端截图如下所示:

创建 API 项目

通过上述创建好的数据库表,继续结合 Beego 框架,我们执行如下命名生成 API 项目:

bee api go-api -conn="root:123456@tcp(127.0.0.1:3306)/api"

其中项目名称叫做 go-api,数据库名称叫做 api。Mysql 用户名为 root,密码为 123456。命令行的截图如下所示:

我们打开指定目录,查看是否自动生成 API 项目,指定目录下生成如下所示项目,成功生成:

集成Swagger UI

首先我们开启本地调试:

bee run -downdoc=true

swagger ui 是一个 API 在线生成文档的生成和测试的最好的工具,评价也是非常好的。API 设计人员完成项目之后,就可以远离痛苦的写文档的活了。

我们到这里下载 swagger 压缩包,解压。赋值其中的内容到我们刚才生成的项目中的 swagger 文件夹中。最后访问http://127.0.0.1:8080/swagger. 即可进入如下界面,怎么样,第一感觉是不是很炫酷?接下来,我们在来体验一下功能上的全面吧。

小试牛刀,试一下 Get 操作,获取全部的内容。如下所示显示了数据库表中的两条数据:

接着试一下,每次请求取限量数据的操作,也就是 Limit 操作。如下图所示限制每次请求只取一条数据:

哈哈,是不是很简单。测试和开发人员都很方便。还有其他的一些常见的网络请求操作,就不做过多说明了,自己体验一下就能感觉得到方便啦。

代码解读

找到自动生成的项目路径,在 Main 文件中代码如下所示,跟一般的 Beego 项目没有什么区别,引入了 Swagger 文件。

package main

import (
	_ "beego-api/routers"

	"github.com/astaxie/beego"
	"github.com/astaxie/beego/orm"
	_ "github.com/go-sql-driver/mysql"
)

func init() {
	orm.RegisterDataBase("default", "mysql", "root:123456@tcp(127.0.0.1:3306)/api")
}

func main() {
	if beego.BConfig.RunMode == "dev" {
		beego.BConfig.WebConfig.DirectoryIndex = true
		beego.BConfig.WebConfig.StaticDir["/swagger"] = "swagger"
	}
	beego.Run()
}

在 router.go 中代码如下所示:

// @APIVersion 1.0.0
// @Title beego Test API
// @Description beego has a very cool tools to autogenerate documents for your API
// @Contact astaxie@gmail.com
// @TermsOfServiceUrl http://beego.me/
// @License Apache 2.0
// @LicenseUrl http://www.apache.org/licenses/LICENSE-2.0.html
package routers

import (
	"beego-api/controllers"

	"github.com/astaxie/beego"
)

func init() {
  	// 注释一处
	ns := beego.NewNamespace("/v1",
		// 注释二处
		beego.NSNamespace("/app",
			beego.NSInclude(
				&controllers.AppController{},
			),
		),
	)
	beego.AddNamespace(ns)
}

对于上面注释的两处代码,引入官方文档的一些说明:

我们看一下路由代码,这是一个层级嵌套的函数,第一个参数是/v1,即为/v1开头的路由树,第二个参数是beego.NSNamespace,第三个参数也是beego.NSNamespace,也就是路由树嵌套了路由树,而我们的beego.NSNamespace里面也是和NewNamespace一样的参数,第一个参数是路由前缀,第二个参数是slice参数。这里我们调用了beego.NSInclude来进行注解路由的引入,这个函数是专门为注解路由设计的,我们可以看到这个设计里面我们没有任何的路由信息,只是设置了前缀,那么这个的路由是在哪里设置的呢?我们接下来分析什么是注解路由。

接下来看一下 controllers 中的 app.go 文件。

// GetOne ...
// @Title Get One
// @Description get App by id
// @Param	id		path 	string	true		"The key for staticblock"
// @Success 200 {object} models.App
// @Failure 403 :id is empty
// @router /:id [get]
func (c *AppController) GetOne() {
	idStr := c.Ctx.Input.Param(":id")
	id, _ := strconv.Atoi(idStr)
	v, err := models.GetAppById(id)
	if err != nil {
		c.Data["json"] = err.Error()
	} else {
		c.Data["json"] = v
	}
	c.ServeJSON()
}

官方的解释依然是最好的。注意为了精简代码篇幅,将其中的 post操作换成了 Get操作:

我们看到我们的每一个函数上面有大段的注释,注解路由其实主要关注最后一行// @router / [post],这一行的注释就是表示这个函数是注册到路由/,支持方法是post

和我们平常的时候使用beego.Router("/", &ObjectController{},"post:Post")的效果是一模一样的,只是这一次框架帮你自动注册了这样的路由,框架是如何来自动注册的呢?在应用启动的时候,会判断是否有调用NSInclude,在调用的时候,判断RunMode是否是dev模式,是的话就会判断是否之前有分析过,并且分析对象目录有更新,就使用Go的AST进行源码分析(当然只分析NSInclude调用的controller),然后生成文件routers/commentsRouter.go,在该文件中会自动注册我们需要的路由信息。这样就完成了整个的注解路由注册。

注解路由是使用// @router 开头来申明的,而且必须放在你要注册的函数的上方,和其他注释@Title @Description的顺序无关,你可以放在第一行,也可以最后一行。有两个参数,第一个是需要注册的路由,第二个是支持的方法。

路由可以支持beego支持的任意规则,例如/object/:key这样的参数路由,也可以固定路由/object,也可以是正则路由/cms_:id([0-9]+).html

其他的比较重要的就是 model 文件夹中的文件了,就是实体内容,其实也是根据数据库中的 app 这张表生成的。

好了,以上就是关于利用 Beego 框架生成 API 项目并且自动化构建文档的实例内容。要探索的还有许多,继续加油。

以上,谢谢阅读。

Back

评论或交流:wuchangfeng2015@gmail.com