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

這是一個建立於 的文章，其中的資訊可能已經有所發展或是發生改變。

編寫Tag的API's、Models

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

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 v1import (    "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 routersimport (    "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 modelstype 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 v1import (    "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) {}

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 v1import (    "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 modelsimport (    "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