3.3 Gin搭建Blog API's (二)

涉及知识点

本文目标

    完成博客的标签类接口定义和编写

定义接口

本节正是编写标签的逻辑,我们想一想,一般接口为增删改查是基础的,那么我们定义一下接口吧!
    获取标签列表:GET("/tags")
    新建标签:POST("/tags")
    更新指定标签:PUT("/tags/:id")
    删除指定标签:DELETE("/tags/:id")

编写路由空壳

开始编写路由文件逻辑,在routers下新建api目录,我们当前是第一个API大版本,因此在api下新建v1目录,再新建tag.go文件,写入内容:
1
package v1
2
3
import (
4
"github.com/gin-gonic/gin"
5
)
6
7
//获取多个文章标签
8
func GetTags(c *gin.Context) {
9
}
10
11
//新增文章标签
12
func AddTag(c *gin.Context) {
13
}
14
15
//修改文章标签
16
func EditTag(c *gin.Context) {
17
}
18
19
//删除文章标签
20
func DeleteTag(c *gin.Context) {
21
}
Copied!

注册路由

我们打开routers下的router.go文件,修改文件内容为:
1
package routers
2
3
import (
4
"github.com/gin-gonic/gin"
5
6
"gin-blog/routers/api/v1"
7
"gin-blog/pkg/setting"
8
)
9
10
func InitRouter() *gin.Engine {
11
r := gin.New()
12
13
r.Use(gin.Logger())
14
15
r.Use(gin.Recovery())
16
17
gin.SetMode(setting.RunMode)
18
19
apiv1 := r.Group("/api/v1")
20
{
21
//获取标签列表
22
apiv1.GET("/tags", v1.GetTags)
23
//新建标签
24
apiv1.POST("/tags", v1.AddTag)
25
//更新指定标签
26
apiv1.PUT("/tags/:id", v1.EditTag)
27
//删除指定标签
28
apiv1.DELETE("/tags/:id", v1.DeleteTag)
29
}
30
31
return r
32
}
Copied!
当前目录结构:
1
gin-blog/
2
├── conf
3
│ └── app.ini
4
├── main.go
5
├── middleware
6
├── models
7
│ └── models.go
8
├── pkg
9
│ ├── e
10
│ │ ├── code.go
11
│ │ └── msg.go
12
│ ├── setting
13
│ │ └── setting.go
14
│ └── util
15
│ └── pagination.go
16
├── routers
17
│ ├── api
18
│ │ └── v1
19
│ │ └── tag.go
20
│ └── router.go
21
├── runtime
Copied!

检验路由是否注册成功

回到命令行,执行go run main.go,检查路由规则是否注册成功。
1
$ go run main.go
2
[GIN-debug] [WARNING] Running in "debug" mode. Switch to "release" mode in production.
3
- using env: export GIN_MODE=release
4
- using code: gin.SetMode(gin.ReleaseMode)
5
6
[GIN-debug] GET /api/v1/tags --> gin-blog/routers/api/v1.GetTags (3 handlers)
7
[GIN-debug] POST /api/v1/tags --> gin-blog/routers/api/v1.AddTag (3 handlers)
8
[GIN-debug] PUT /api/v1/tags/:id --> gin-blog/routers/api/v1.EditTag (3 handlers)
9
[GIN-debug] DELETE /api/v1/tags/:id --> gin-blog/routers/api/v1.DeleteTag (3 handlers)
Copied!
运行成功,那么我们愉快的开始编写我们的接口吧!

下载依赖包

首先我们要拉取validation的依赖包,在后面的接口里会使用到表单验证
1
go get -u github.com/astaxie/beego/validation
Copied!

编写标签列表的models逻辑

创建models目录下的tag.go,写入文件内容:
1
package models
2
3
type Tag struct {
4
Model
5
6
Name string `json:"name"`
7
CreatedBy string `json:"created_by"`
8
ModifiedBy string `json:"modified_by"`
9
State int `json:"state"`
10
}
11
12
func GetTags(pageNum int, pageSize int, maps interface {}) (tags []Tag) {
13
db.Where(maps).Offset(pageNum).Limit(pageSize).Find(&tags)
14
15
return
16
}
17
18
func GetTagTotal(maps interface {}) (count int){
19
db.Model(&Tag{}).Where(maps).Count(&count)
20
21
return
22
}
Copied!
    1.
    我们创建了一个Tag struct{},用于Gorm的使用。并给予了附属属性json,这样子在c.JSON的时候就会自动转换格式,非常的便利
    2.
    可能会有的初学者看到return,而后面没有跟着变量,会不理解;其实你可以看到在函数末端,我们已经显示声明了返回值,这个变量在函数体内也可以直接使用,因为他在一开始就被声明了
    3.
    有人会疑惑db是哪里来的;因为在同个models包下,因此db *gorm.DB是可以直接使用的

编写标签列表的路由逻辑

打开routers目录下v1版本的tag.go,第一我们先编写获取标签列表的接口
修改文件内容:
1
package v1
2
3
import (
4
"net/http"
5
6
"github.com/gin-gonic/gin"
7
//"github.com/astaxie/beego/validation"
8
"github.com/Unknwon/com"
9
10
"gin-blog/pkg/e"
11
"gin-blog/models"
12
"gin-blog/pkg/util"
13
"gin-blog/pkg/setting"
14
)
15
16
//获取多个文章标签
17
func GetTags(c *gin.Context) {
18
name := c.Query("name")
19
20
maps := make(map[string]interface{})
21
data := make(map[string]interface{})
22
23
if name != "" {
24
maps["name"] = name
25
}
26
27
var state int = -1
28
if arg := c.Query("state"); arg != "" {
29
state = com.StrTo(arg).MustInt()
30
maps["state"] = state
31
}
32
33
code := e.SUCCESS
34
35
data["lists"] = models.GetTags(util.GetPage(c), setting.PageSize, maps)
36
data["total"] = models.GetTagTotal(maps)
37
38
c.JSON(http.StatusOK, gin.H{
39
"code" : code,
40
"msg" : e.GetMsg(code),
41
"data" : data,
42
})
43
}
44
45
//新增文章标签
46
func AddTag(c *gin.Context) {
47
}
48
49
//修改文章标签
50
func EditTag(c *gin.Context) {
51
}
52
53
//删除文章标签
54
func DeleteTag(c *gin.Context) {
55
}
Copied!
    1.
    c.Query可用于获取?name=test&state=1这类URL参数,而c.DefaultQuery则支持设置一个默认值
    2.
    code变量使用了e模块的错误编码,这正是先前规划好的错误码,方便排错和识别记录
    3.
    util.GetPage保证了各接口的page处理是一致的
    4.
    c *gin.ContextGin很重要的组成部分,可以理解为上下文,它允许我们在中间件之间传递变量、管理流、验证请求的JSON和呈现JSON响应
在本机执行curl 127.0.0.1:8000/api/v1/tags,正确的返回值为{"code":200,"data":{"lists":[],"total":0},"msg":"ok"},若存在问题请结合gin结果进行拍错。
在获取标签列表接口中,我们可以根据namestatepage来筛选查询条件,分页的步长可通过app.ini进行配置,以liststotal的组合返回达到分页效果。

编写新增标签的models逻辑

接下来我们编写新增标签的接口
打开models目录下的tag.go,修改文件(增加2个方法):
1
...
2
func ExistTagByName(name string) bool {
3
var tag Tag
4
db.Select("id").Where("name = ?", name).First(&tag)
5
if tag.ID > 0 {
6
return true
7
}
8
9
return false
10
}
11
12
func AddTag(name string, state int, createdBy string) bool{
13
db.Create(&Tag {
14
Name : name,
15
State : state,
16
CreatedBy : createdBy,
17
})
18
19
return true
20
}
21
...
Copied!

编写新增标签的路由逻辑

打开routers目录下的tag.go,修改文件(变动AddTag方法):
1
package v1
2
3
import (
4
"log"
5
"net/http"
6
7
"github.com/gin-gonic/gin"
8
"github.com/astaxie/beego/validation"
9
"github.com/Unknwon/com"
10
11
"gin-blog/pkg/e"
12
"gin-blog/models"
13
"gin-blog/pkg/util"
14
"gin-blog/pkg/setting"
15
)
16
...
17
//新增文章标签
18
func AddTag(c *gin.Context) {
19
name := c.Query("name")
20
state := com.StrTo(c.DefaultQuery("state", "0")).MustInt()
21
createdBy := c.Query("created_by")
22
23
valid := validation.Validation{}
24
valid.Required(name, "name").Message("名称不能为空")
25
valid.MaxSize(name, 100, "name").Message("名称最长为100字符")
26
valid.Required(createdBy, "created_by").Message("创建人不能为空")
27
valid.MaxSize(createdBy, 100, "created_by").Message("创建人最长为100字符")
28
valid.Range(state, 0, 1, "state").Message("状态只允许0或1")
29
30
code := e.INVALID_PARAMS
31
if ! valid.HasErrors() {
32
if ! models.ExistTagByName(name) {
33
code = e.SUCCESS
34
models.AddTag(name, state, createdBy)
35
} else {
36
code = e.ERROR_EXIST_TAG
37
}
38
}
39
40
c.JSON(http.StatusOK, gin.H{
41
"code" : code,
42
"msg" : e.GetMsg(code),
43
"data" : make(map[string]string),
44
})
45
}
46
...
Copied!
Postman用POST访问http://127.0.0.1:8000/api/v1/tags?name=1&state=1&created_by=test,查看code是否返回200blog_tag表中是否有值,有值则正确。

编写models callbacks

但是这个时候大家会发现,我明明新增了标签,但created_on居然没有值,那做修改标签的时候modified_on会不会也存在这个问题?
为了解决这个问题,我们需要打开models目录下的tag.go文件,修改文件内容(修改包引用和增加2个方法):
1
package models
2
3
import (
4
"time"
5
6
"github.com/jinzhu/gorm"
7
)
8
9
...
10
11
func (tag *Tag) BeforeCreate(scope *gorm.Scope) error {
12
scope.SetColumn("CreatedOn", time.Now().Unix())
13
14
return nil
15
}
16
17
func (tag *Tag) BeforeUpdate(scope *gorm.Scope) error {
18
scope.SetColumn("ModifiedOn", time.Now().Unix())
19
20
return nil
21
}
Copied!
重启服务,再在用Postman用POST访问http://127.0.0.1:8000/api/v1/tags?name=2&state=1&created_by=test,发现created_on已经有值了!
在这几段代码中,涉及到知识点:
这属于gormCallbacks,可以将回调方法定义为模型结构的指针,在创建、更新、查询、删除时将被调用,如果任何回调返回错误,gorm将停止未来操作并回滚所有更改。
gorm所支持的回调方法:
    创建:BeforeSave、BeforeCreate、AfterCreate、AfterSave
    更新:BeforeSave、BeforeUpdate、AfterUpdate、AfterSave
    删除:BeforeDelete、AfterDelete
    查询:AfterFind

编写其余接口的路由逻辑

接下来,我们一口气把剩余的两个接口(EditTag、DeleteTag)完成吧
打开routers目录下v1版本的tag.go文件,修改内容:
1
...
2
//修改文章标签
3
func EditTag(c *gin.Context) {
4
id := com.StrTo(c.Param("id")).MustInt()
5
name := c.Query("name")
6
modifiedBy := c.Query("modified_by")
7
8
valid := validation.Validation{}
9
10
var state int = -1
11
if arg := c.Query("state"); arg != "" {
12
state = com.StrTo(arg).MustInt()
13
valid.Range(state, 0, 1, "state").Message("状态只允许0或1")
14
}
15
16
valid.Required(id, "id").Message("ID不能为空")
17
valid.Required(modifiedBy, "modified_by").Message("修改人不能为空")
18
valid.MaxSize(modifiedBy, 100, "modified_by").Message("修改人最长为100字符")
19
valid.MaxSize(name, 100, "name").Message("名称最长为100字符")
20
21
code := e.INVALID_PARAMS
22
if ! valid.HasErrors() {
23
code = e.SUCCESS
24
if models.ExistTagByID(id) {
25
data := make(map[string]interface{})
26
data["modified_by"] = modifiedBy
27
if name != "" {
28
data["name"] = name
29
}
30
if state != -1 {
31
data["state"] = state
32
}
33
34
models.EditTag(id, data)
35
} else {
36
code = e.ERROR_NOT_EXIST_TAG
37
}
38
}
39
40
c.JSON(http.StatusOK, gin.H{
41
"code" : code,
42
"msg" : e.GetMsg(code),
43
"data" : make(map[string]string),
44
})
45
}
46
47
//删除文章标签
48
func DeleteTag(c *gin.Context) {
49
id := com.StrTo(c.Param("id")).MustInt()
50
51
valid := validation.Validation{}
52
valid.Min(id, 1, "id").Message("ID必须大于0")
53
54
code := e.INVALID_PARAMS
55
if ! valid.HasErrors() {
56
code = e.SUCCESS
57
if models.ExistTagByID(id) {
58
models.DeleteTag(id)
59
} else {
60
code = e.ERROR_NOT_EXIST_TAG
61
}
62
}
63
64
c.JSON(http.StatusOK, gin.H{
65
"code" : code,
66
"msg" : e.GetMsg(code),
67
"data" : make(map[string]string),
68
})
69
}
Copied!

编写其余接口的models逻辑

打开models下的tag.go,修改文件内容:
1
...
2
3
func ExistTagByID(id int) bool {
4
var tag Tag
5
db.Select("id").Where("id = ?", id).First(&tag)
6
if tag.ID > 0 {
7
return true
8
}
9
10
return false
11
}
12
13
func DeleteTag(id int) bool {
14
db.Where("id = ?", id).Delete(&Tag{})
15
16
return true
17
}
18
19
func EditTag(id int, data interface {}) bool {
20
db.Model(&Tag{}).Where("id = ?", id).Updates(data)
21
22
return true
23
}
24
...
Copied!

验证功能

重启服务,用Postman
至此,Tag的API's完成,下一节我们将开始Article的API's编写!

参考

本系列示例代码

关于

修改记录

    第一版:2018年02月16日发布文章
    第二版:2019年10月01日修改文章

如果有任何疑问或错误,欢迎在 issues 进行提问或给予修正意见,如果喜欢或对你有所帮助,欢迎 Star,对作者是一种鼓励和推进。

我的公众号

image
Last modified 2yr ago