「连载三」Gin搭建Blog API's (二)

涉及知识点

本文目标

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

定义接口

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

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

编写路由空壳

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
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文件,修改文件内容为:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
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
}

当前目录结构:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
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,检查路由规则是否注册成功。

1
2
3
4
5
6
7
8
9
$ 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的依赖包,在后面的接口里会使用到表单验证

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

编写标签列表的 models 逻辑

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
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,第一我们先编写获取标签列表的接口

修改文件内容:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
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.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
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
...
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 方法):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
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是否返回200blog_tag表中是否有值,有值则正确。

编写 models callbacks

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
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已经有值了!

在这几段代码中,涉及到知识点:

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

gorm所支持的回调方法:

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

编写其余接口的路由逻辑

接下来,我们一口气把剩余的两个接口(EditTag、DeleteTag)完成吧

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
...

//修改文章标签
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,修改文件内容:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
...

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

至此,Tag 的 API’s 完成,下一节我们将开始 Article 的 API’s 编写!

参考

本系列示例代码

关于

修改记录

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

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

我的公众号

image


免责声明:本页面内容均来源于站内编辑发布,部分信息来源互联网,并不意味着本站赞同其观点或者证实其内容的真实性,如涉及版权等问题,请立即联系客服进行更改或删除,保证您的合法权益。转载请注明来源,欢迎对文章中的引用来源进行考证,欢迎指出任何有错误或不够清晰的表达。也可以邮件至 [email protected]

推荐阅读:

文章标题:「连载三」Gin搭建Blog API's (二)

本文作者:知识铺

发布时间:2018-02-12, 12:00:00

最后更新:2020-04-19, 17:52:49

原始链接:https://blog.zshipu.com/2018/02/12/golang/go/gin/2018-02-12-api-02/

版权声明: "署名-非商用-相同方式共享 4.0" 转载请保留原文链接及作者。

目录
×

喜欢就点赞,疼爱就打赏