Beego应用开发01

环境搭建

所有内容建立在已经搭建好GoLang环境的继承上。

安装Beego和Bee

​ Beego是GoLang的一个Web框架，由国人开发，文档和资料比较全面，各方面性能也很优秀。我们这里使用它作为学习的目标。Bee是Beego对应的项目管理工具，通过它我们可以很方便地管理我们的Beego项目。

​ 在控制台里输入go get -u github.com/astaxie/beego go自身的包管理工具会将最新的beego框架下载到 GOPATH/src目录下。然后输入go get -u github.com/beego/bee 下载Bee工具，默认安装在GOBIN目录下。

创建Beego项目

​ 使用Bee工具，我们可以非常方便创建Beego Web/API项目，我们以API项目为例：(Windows平台)

cd /d %GOPATH%/srcbee api myApicd /d myApibee run myApi

最后的bee run myApi是bee工具提供的热编译功能，当检测到代码变化时，自动重新变异项目，非常方便。

bee run -gendoc=true -downdoc=true

myApi 应用跑起来，-gendoc=true 表示每次自动化的 build 文档，-downdoc=true 就会自动的下载 swagger 文档查看器。在地址栏输入http://127.0.0.1:8080/swagger就可以看到效果了。

项目概览

myApi目录：│  main.go│  myApi.exe|├─conf│      app.conf│├─controllers│      object.go│      user.go│├─models│      object.go│      user.go│├─routers│      commentsRouter_controllers.go│      router.go│├─swagger│      favicon-16x16.png│      favicon-32x32.png│      index.html│      oauth2-redirect.html│      swagger-ui-bundle.js│      swagger-ui-bundle.js.map│      swagger-ui-standalone-preset.js│      swagger-ui-standalone-preset.js.map│      swagger-ui.css│      swagger-ui.css.map│      swagger-ui.js│      swagger-ui.js.map│      swagger.json│      swagger.yml│└─tests        default_test.go

整个项目的入口为main.go，配置文件为conf/app.conf。

每一个函数上面的注释，这里列出来支持的各种注释：

• @Title

  这个 API 所表达的含义，是一个文本，空格之后的内容全部解析为 title

• @Description

  这个 API 详细的描述，是一个文本，空格之后的内容全部解析为 Description

• @Param

  参数，表示需要传递到服务器端的参数，有五列参数，使用空格或者 tab 分割，五个分别表示的含义如下

  1. 参数名
  2. 参数类型，可以有的值是 formData、query、path、body、header，formData 表示是 post 请求的数据，query 表示带在 url 之后的参数，path 表示请求路径上得参数，例如上面例子里面的 key，body 表示是一个 raw 数据请求，header 表示带在 header 信息中得参数。
  3. 参数类型
  4. 是否必须
  5. 注释

• @Success

  成功返回给客户端的信息，三个参数，第一个是 status code。第二个参数是返回的类型，必须使用 {} 包含，第三个是返回的对象或者字符串信息，如果是 {object} 类型，那么 bee 工具在生成 docs 的时候会扫描对应的对象，这里填写的是想对你项目的目录名和对象，例如models.ZDTProduct.ProductList 就表示 /models/ZDTProduct 目录下的 ProductList 对象。

  三个参数必须通过空格分隔

• @Failure

  失败返回的信息，包含两个参数，使用空格分隔，第一个表示 status code，第二个表示错误信息

• @router

  路由信息，包含两个参数，使用空格分隔，第一个是请求的路由地址，支持正则和自定义路由，和之前的路由规则一样，第二个参数是支持的请求方法,放在 [] 之中，如果有多个方法，那么使用 , 分隔。

主要代码解析

1. 项目入口(main.go)

package mainimport (    _ "myApi/routers" // 这里导入了router模块，调用init    "github.com/astaxie/beego")func main() {    if beego.BConfig.RunMode == "dev" {        beego.BConfig.WebConfig.DirectoryIndex = true        beego.BConfig.WebConfig.StaticDir["/swagger"] = "swagger"    }    beego.Run()}

1. Router的初始化

// @APIVersion 1.0.0// @Title beego Test API// @Description beego has a very cool tools to autogenerate documents for your API// @Contact [e-mail]// @TermsOfServiceUrl http://beego.me/// @License Apache 2.0// @LicenseUrl http://www.apache.org/licenses/LICENSE-2.0.htmlpackage routersimport (    "myApi/controllers" // 调用controllers模块    "github.com/astaxie/beego")func init() {    // 这里使用命名空间，将各个不同功能的模块区分开来    ns := beego.NewNamespace("/v1",        beego.NSNamespace("/object",            beego.NSInclude(                &controllers.ObjectController{},            ),        ),        beego.NSNamespace("/user",            beego.NSInclude(                &controllers.UserController{},            ),        ),    )    beego.AddNamespace(ns) // 根据命名空间生成路由}

1. Controllers模块
   controllers模块中，有object和user两个models对应的控制接口，支持Get/Post/Put/Delete方法，并且为每个接口编写了文档注释，例子如下：

import (    "myApi/models"    "encoding/json"    "github.com/astaxie/beego")// Operations about objecttype ObjectController struct {    beego.Controller}// @Title Get// @Description find object by objectid// @Param   objectId        path    string  true        "the objectid you want to get"// @Success 200 {object} models.Object// @Failure 403 :objectId is empty// @router /:objectId [get]func (o *ObjectController) Get() {    objectId := o.Ctx.Input.Param(":objectId")    if objectId != "" {        ob, err := models.GetOne(objectId)        if err != nil {            o.Data["json"] = err.Error()        } else {            o.Data["json"] = ob        }    }    o.ServeJSON()}

1. models模块：
   models模块中定义了与数据库或者模型对应的结构体，用于ORM操作。Demo中的init函数虚拟了一个类似数据库的操作和对象，直接在内存中进行存储。虽然与实际使用不一定一致，但是原理是一样的。

package modelsimport (    "errors"    "strconv"    "time")var (    Objects map[string]*Object)type Object struct {    ObjectId   string    Score      int64    PlayerName string}func init() {    Objects = make(map[string]*Object)    Objects["hjkhsbnmn123"] = &Object{"hjkhsbnmn123", 100, "astaxie"}    Objects["mjjkxsxsaa23"] = &Object{"mjjkxsxsaa23", 101, "someone"}}func AddOne(object Object) (ObjectId string) {    object.ObjectId = "astaxie" + strconv.FormatInt(time.Now().UnixNano(), 10)    Objects[object.ObjectId] = &object    return object.ObjectId}

配置文件

beego中很多功能都可以在配置文件中开启，用户也可以自己在配置文件中编写自己的信息。并且由于beego借鉴了很多其他配置方案的优点，支持节点、环境变量、配置切换….功能，非常强大！

强烈建议参看官方文档： URL

其他目录介绍

1. tests 为用户编写了一个简单的测试用例
2. swagger 通过命令bee run -gendoc=true -downdoc=true会生成 swagger.json和swagger.yml文件，里面包含了所有API的结构化文档。同时，downdoc参数指定了在线下载swagger模版，解压在这个文件夹下，当访问http://127.0.0.1/swagger时，会使用这个模版渲染swagger.json文件，形成好看的api文档。