Gin實踐 連載三 搭建Blog API's（二）

編寫Tag的API's、Models

項目地址：https://github.com/EDDYCJY/go...

本大節將會涉及到如下知識點：

1. gin：Golang的一個微框架，性能極佳
2. beego-validation：本節採用的beego的表單驗證庫，中文文檔
3. gorm，對開發人員友好的ORM框架，英文文檔
4. com，工具包
5. 業務邏輯的編寫

咱們開始編寫業務代碼，博客文章會有標籤的概念，

定義接口

本節正是編寫標籤的邏輯，咱們想想，通常接口爲增刪改查是基礎的，那麼咱們定義一下接口吧！

• 獲取標籤列表：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
}

1. 咱們建立了一個Tag struct{}，用於Gorm的使用。並給予了附屬屬性json，這樣子在c.JSON的時候就會自動轉換格式，很是的便利
2. 可能會有的初學者看到return，然後面沒有跟着變量，會不理解；其實你能夠看到在函數末端，咱們已經顯示聲明瞭返回值，這個變量在函數體內也能夠直接使用，由於他在一開始就被聲明瞭
3. 有人會疑惑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).MustInt()
        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) {
}

1. c.Query可用於獲取?name=test&state=1這類URL參數，而c.DefaultQuery則支持設置一個默認值
2. code變量使用了e模塊的錯誤編碼，這正是先前規劃好的錯誤碼，方便排錯和識別記錄
3. util.GetPage保證了各接口的page處理是一致的
4. 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")).MustInt()
    createdBy := c.Query("created_by")

    valid := validation.Validation{}
    valid.Required(name, "name").Message("名稱不能爲空")
    valid.MaxSize(name, 100, "name").Message("名稱最長爲100字符")
    valid.Required(createdBy, "created_by").Message("建立人不能爲空")
    valid.MaxSize(createdBy, 100, "created_by").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
        }
    }

    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")).MustInt()
    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).MustInt()
        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
        }
    }

    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")).MustInt()

    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
        }
    }

    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

本系列目錄

• 連載一 Golang介紹與環境安裝
• 連載二 搭建Blog API's（一）
• 連載三 搭建Blog API's（二）
• 連載四 搭建Blog API's（三）
• 連載五 使用JWT進行身份校驗
• 連載六 編寫一個簡單的文件日誌
• 連載七 Golang優雅重啓HTTP服務
• 連載八 爲它加上Swagger
• 連載九 將Golang應用部署到Docker
• 連載十 定製 GORM Callbacks
• 連載十一 Cron定時任務
• 連載十二 優化配置結構及實現圖片上傳
• 連載十三 優化你的應用結構和實現Redis緩存
• 連載十四 實現導出、導入 Excel
• 連載十五 生成二維碼、合併海報
• 連載十六 在圖片上繪製文字
• 連載十七 用 Nginx 部署 Go 應用
• 番外 Golang交叉編譯
• 番外 請入門 Makefile