Gin实践连载三搭建Blog API's（二）

编写Tag的API's、Models

本大节将会涉及到以下知识点：

gin：Golang的一个微框架，性能极佳
beego-validation：本节采用的beego的表单验证库，中文文档
gorm，对开发人员友好的ORM框架，英文文档
com，工具包
业务逻辑的编写

我们开始编写业务代码，博客文章会有标签的概念，

定义接口

本节正是编写标签的逻辑，我们想一想，一般接口为增删改查是基础的，那么我们定义一下接口吧！

获取标签列表：GET("/tags")
新建标签：POST("/tags")
更新指定标签：PUT("/tags/:id")
删除指定标签：DELETE("/tags/:id")

编写路由空壳

开始编写路由文件逻辑，在routers下新建api目录，我们当前是第一个API大版本，因此在api下新建v1目录，再新建tag.go文件，写入内容：

package v1

import (
    "github.com/gin-gonic/gin"
)

//获取多个文章标签
func GetTags(c *gin.Context) {
}

//新增文章标签
func AddTag(c *gin.Context) {
}

//修改文章标签
func EditTag(c *gin.Context) {
}

//删除文章标签
func DeleteTag(c *gin.Context) {
}

注册路由

我们打开routers下的router.go文件，修改文件内容为：

package routers

import (
    "github.com/gin-gonic/gin"
    
    "gin-blog/routers/api/v1"
    "gin-blog/pkg/setting"
)

func InitRouter() *gin.Engine {
    r := gin.New()

    r.Use(gin.Logger())

    r.Use(gin.Recovery())

    gin.SetMode(setting.RunMode)

    apiv1 := r.Group("/api/v1")
    {
        //获取标签列表
        apiv1.GET("/tags", v1.GetTags)
        //新建标签
        apiv1.POST("/tags", v1.AddTag)
        //更新指定标签
        apiv1.PUT("/tags/:id", v1.EditTag)
        //删除指定标签
        apiv1.DELETE("/tags/:id", v1.DeleteTag)
    }

    return r
}

当前目录结构：

gin-blog/
├── conf
│   └── app.ini
├── main.go
├── middleware
├── models
│   └── models.go
├── pkg
│   ├── e
│   │   ├── code.go
│   │   └── msg.go
│   ├── setting
│   │   └── setting.go
│   └── util
│       └── pagination.go
├── routers
│   ├── api
│   │   └── v1
│   │       └── tag.go
│   └── router.go
├── runtime

检验路由是否注册成功

回到命令行，执行go run main.go，检查路由规则是否注册成功。

$ go run main.go 
[GIN-debug] [WARNING] Running in "debug" mode. Switch to "release" mode in production.
 - using env:    export GIN_MODE=release
 - using code:    gin.SetMode(gin.ReleaseMode)

[GIN-debug] GET    /api/v1/tags              --> gin-blog/routers/api/v1.GetTags (3 handlers)
[GIN-debug] POST   /api/v1/tags              --> gin-blog/routers/api/v1.AddTag (3 handlers)
[GIN-debug] PUT    /api/v1/tags/:id          --> gin-blog/routers/api/v1.EditTag (3 handlers)
[GIN-debug] DELETE /api/v1/tags/:id          --> gin-blog/routers/api/v1.DeleteTag (3 handlers)

运行成功，那么我们愉快的开始编写我们的接口吧！

下载依赖包

首先我们要拉取validation的依赖包，在后面的接口里会使用到表单验证

go get -u github.com/astaxie/beego/validation

编写标签列表的models逻辑

创建models目录下的tag.go，写入文件内容：

package models

type Tag struct {
    Model

    Name string `json:"name"`
    CreatedBy string `json:"created_by"`
    ModifiedBy string `json:"modified_by"`
    State int `json:"state"`
}

func GetTags(pageNum int, pageSize int, maps interface {}) (tags []Tag) {
    db.Where(maps).Offset(pageNum).Limit(pageSize).Find(&tags)
    
    return
}

func GetTagTotal(maps interface {}) (count int){
    db.Model(&Tag{}).Where(maps).Count(&count)

    return
}

我们创建了一个Tag struct{}，用于Gorm的使用。并给予了附属属性json，这样子在c.JSON的时候就会自动转换格式，非常的便利
可能会有的初学者看到return，而后面没有跟着变量，会不理解；其实你可以看到在函数末端，我们已经显示声明了返回值，这个变量在函数体内也可以直接使用，因为他在一开始就被声明了
有人会疑惑db是哪里来的；因为在同个models包下，因此db *gorm.DB是可以直接使用的

编写标签列表的路由逻辑

打开routers目录下v1版本的tag.go，第一我们先编写获取标签列表的接口

修改文件内容：

package v1

import (
    "net/http"

    "github.com/gin-gonic/gin"
    //"github.com/astaxie/beego/validation"
    "github.com/Unknwon/com"

    "gin-blog/pkg/e"
    "gin-blog/models"
    "gin-blog/pkg/util"
    "gin-blog/pkg/setting"
)

//获取多个文章标签
func GetTags(c *gin.Context) {
    name := c.Query("name")

    maps := make(map[string]interface{})
    data := make(map[string]interface{})

    if name != "" {
        maps["name"] = name
    }

    var state int = -1
    if arg := c.Query("state"); arg != "" {
        state, _ = com.StrTo(arg).Int()
        maps["state"] = state
    }

    code := e.SUCCESS

    data["lists"] = models.GetTags(util.GetPage(c), setting.PageSize, maps)
    data["total"] = models.GetTagTotal(maps)

    c.JSON(http.StatusOK, gin.H{
        "code" : code,
        "msg" : e.GetMsg(code),
        "data" : data,
    })
}

//新增文章标签
func AddTag(c *gin.Context) {
}

//修改文章标签
func EditTag(c *gin.Context) {
}

//删除文章标签
func DeleteTag(c *gin.Context) {
}

c.Query可用于获取?name=test&state=1这类URL参数，而c.DefaultQuery则支持设置一个默认值
code变量使用了e模块的错误编码，这正是先前规划好的错误码，方便排错和识别记录
util.GetPage保证了各接口的page处理是一致的
c *gin.Context是Gin很重要的组成部分，可以理解为上下文，它允许我们在中间件之间传递变量、管理流、验证请求的JSON和呈现JSON响应

在本机执行curl 127.0.0.1:8000/api/v1/tags，正确的返回值为{"code":200,"data":{"lists":[],"total":0},"msg":"ok"}，若存在问题请结合gin结果进行拍错。

在获取标签列表接口中，我们可以根据name、state、page来筛选查询条件，分页的步长可通过app.ini进行配置，以lists、total的组合返回达到分页效果。

编写新增标签的models逻辑

接下来我们编写新增标签的接口

打开models目录下v1版本的tag.go，修改文件（增加2个方法）：

...
func ExistTagByName(name string) bool {
    var tag Tag
    db.Select("id").Where("name = ?", name).First(&tag)
    if tag.ID > 0 {
        return true
    }

    return false
}

func AddTag(name string, state int, createdBy string) bool{
    db.Create(&Tag {
        Name : name,
        State : state,
        CreatedBy : createdBy,
    })

    return true
}
...

编写新增标签的路由逻辑

打开routers目录下的tag.go，修改文件（变动AddTag方法）：

package v1

import (
    "log"
    "net/http"

    "github.com/gin-gonic/gin"
    "github.com/astaxie/beego/validation"
    "github.com/Unknwon/com"

    "gin-blog/pkg/e"
    "gin-blog/models"
    "gin-blog/pkg/util"
    "gin-blog/pkg/setting"
)
...
//新增文章标签
func AddTag(c *gin.Context) {
    name := c.Query("name")
    state, _ := com.StrTo(c.DefaultQuery("state", "0")).Int()
    createdBy := c.Query("created_by")

    valid := validation.Validation{}
    valid.Required(name, "name").Message("名称不能为空")
    valid.Required(name, "created_by").Message("创建人不能为空")
    valid.MaxSize(name, 100, "created_by").Message("创建人最长为100字符")
    valid.MaxSize(name, 100, "name").Message("名称最长为100字符")
    valid.Range(state, 0, 1, "state").Message("状态只允许0或1")

    code := e.INVALID_PARAMS
    if ! valid.HasErrors() {
        if ! models.ExistTagByName(name) {
            code = e.SUCCESS
            models.AddTag(name, state, createdBy)
        } else {
            code = e.ERROR_EXIST_TAG
        }
    } else {
        for _, err := range valid.Errors {
            log.Println(err.Key, err.Message)
        }
    }

    c.JSON(http.StatusOK, gin.H{
        "code" : code,
        "msg" : e.GetMsg(code),
        "data" : make(map[string]string),
    })
}
...

用Postman用POST访问http://127.0.0.1:8000/api/v1/tags?name=1&state=1&created_by=test，查看code是否返回200及blog_tag表中是否有值，有值则正确。

编写models callbacks

但是这个时候大家会发现，我明明新增了标签，但created_on居然没有值，那做修改标签的时候modified_on会不会也存在这个问题？

为了解决这个问题，我们需要打开models目录下的tag.go文件，修改文件内容（修改包引用和增加2个方法）：

package models

import (
    "time"

    "github.com/jinzhu/gorm"
)

...

func (tag *Tag) BeforeCreate(scope *gorm.Scope) error {
    scope.SetColumn("CreatedOn", time.Now().Unix())

    return nil
}

func (tag *Tag) BeforeUpdate(scope *gorm.Scope) error {
    scope.SetColumn("ModifiedOn", time.Now().Unix())

    return nil
}

重启服务，再在用Postman用POST访问http://127.0.0.1:8000/api/v1/tags?name=2&state=1&created_by=test，发现created_on已经有值了！

在这几段代码中，涉及到知识点：

这属于gorm的Callbacks，可以将回调方法定义为模型结构的指针，在创建、更新、查询、删除时将被调用，如果任何回调返回错误，gorm将停止未来操作并回滚所有更改。

gorm所支持的回调方法：

创建：BeforeSave、BeforeCreate、AfterCreate、AfterSave
更新：BeforeSave、BeforeUpdate、AfterUpdate、AfterSave
删除：BeforeDelete、AfterDelete
查询：AfterFind

编写其余接口的路由逻辑

接下来，我们一口气把剩余的两个接口（EditTag、DeleteTag）完成吧

打开routers目录下v1版本的tag.go文件，修改内容：

...
//修改文章标签
func EditTag(c *gin.Context) {
    id, _ := com.StrTo(c.Param("id")).Int()
    name := c.Query("name")
    modifiedBy := c.Query("modified_by")

    valid := validation.Validation{}

    var state int = -1
    if arg := c.Query("state"); arg != "" {
        state, _ = com.StrTo(arg).Int()
        valid.Range(state, 0, 1, "state").Message("状态只允许0或1")
    }

    valid.Required(id, "id").Message("ID不能为空")
    valid.Required(modifiedBy, "modified_by").Message("修改人不能为空")
    valid.MaxSize(modifiedBy, 100, "modified_by").Message("修改人最长为100字符")
    valid.MaxSize(name, 100, "name").Message("名称最长为100字符")

    code := e.INVALID_PARAMS
    if ! valid.HasErrors() {
        code = e.SUCCESS
        if models.ExistTagByID(id) {
            data := make(map[string]interface{})
            data["modified_by"] = modifiedBy
            if name != "" {
                data["name"] = name
            }
            if state != -1 {
                data["state"] = state
            }

            models.EditTag(id, data)
        } else {
            code = e.ERROR_NOT_EXIST_TAG
        }
    } else {
        for _, err := range valid.Errors {
            log.Println(err.Key, err.Message)
        }
    }

    c.JSON(http.StatusOK, gin.H{
        "code" : code,
        "msg" : e.GetMsg(code),
        "data" : make(map[string]string),
    })
}  

//删除文章标签
func DeleteTag(c *gin.Context) {
    id, _ := com.StrTo(c.Param("id")).Int()

    valid := validation.Validation{}
    valid.Min(id, 1, "id").Message("ID必须大于0")

    code := e.INVALID_PARAMS
    if ! valid.HasErrors() {
        code = e.SUCCESS
        if models.ExistTagByID(id) {
            models.DeleteTag(id)
        } else {
            code = e.ERROR_NOT_EXIST_TAG
        }
    } else {
        for _, err := range valid.Errors {
            log.Println(err.Key, err.Message)
        }
    }

    c.JSON(http.StatusOK, gin.H{
        "code" : code,
        "msg" : e.GetMsg(code),
        "data" : make(map[string]string),
    })
}

编写其余接口的models逻辑

打开models下的tag.go，修改文件内容：

...

func ExistTagByID(id int) bool {
    var tag Tag
    db.Select("id").Where("id = ?", id).First(&tag)
    if tag.ID > 0 {
        return true
    }

    return false
}

func DeleteTag(id int) bool {
    db.Where("id = ?", id).Delete(&Tag{})

    return true
}

func EditTag(id int, data interface {}) bool {
    db.Model(&Tag{}).Where("id = ?", id).Updates(data)

    return true
}
...

验证功能

重启服务，用Postman

PUT访问http://127.0.0.1:8000/api/v1/tags/1?name=edit1&state=0&modified_by=edit1，查看code是否返回200
DELETE访问http://127.0.0.1:8000/api/v1/tags/1，查看code是否返回200

至此，Tag的API's完成，下一节我们将开始Article的API's编写！

参考

本系列示例代码

go-gin-example

本文来自：Segmentfault

感谢作者：EDDYCJY

查看原文：Gin实践连载三搭建Blog API's（二）

编写Tag的API's、Models

定义接口

编写路由空壳

注册路由

检验路由是否注册成功

下载依赖包

编写标签列表的models逻辑

编写标签列表的路由逻辑

编写新增标签的models逻辑

编写新增标签的路由逻辑

编写models callbacks

编写其余接口的路由逻辑

编写其余接口的models逻辑

验证功能

参考

本系列示例代码

用户登录

今日阅读排行

一周阅读排行

编写Tag的API's、Models

定义接口

编写路由空壳

注册路由

检验路由是否注册成功

下载依赖包

编写标签列表的models逻辑

编写标签列表的路由逻辑

编写新增标签的models逻辑

编写新增标签的路由逻辑

编写models callbacks

编写其余接口的路由逻辑

编写其余接口的models逻辑

验证功能

参考

本系列示例代码

Gin实践 连载三 搭建Blog API's（二）

编写Tag的API's、Models

定义接口

编写路由空壳

注册路由

检验路由是否注册成功

下载依赖包

编写标签列表的models逻辑

编写标签列表的路由逻辑

编写新增标签的models逻辑

编写新增标签的路由逻辑

编写models callbacks

编写其余接口的路由逻辑

编写其余接口的models逻辑

验证功能

参考

本系列示例代码

用户登录

今日阅读排行

一周阅读排行

编写Tag的API's、Models

定义接口

编写路由空壳

注册路由

检验路由是否注册成功

下载依赖包

编写标签列表的models逻辑

编写标签列表的路由逻辑

编写新增标签的models逻辑

编写新增标签的路由逻辑

编写models callbacks

编写其余接口的路由逻辑

编写其余接口的models逻辑

验证功能

参考

本系列示例代码

Gin实践连载三搭建Blog API's（二）