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. import (
  3. "github.com/gin-gonic/gin"
  4. )
  5. //获取多个文章标签
  6. func GetTags(c *gin.Context) {
  7. }
  8. //新增文章标签
  9. func AddTag(c *gin.Context) {
  10. }
  11. //修改文章标签
  12. func EditTag(c *gin.Context) {
  13. }
  14. //删除文章标签
  15. func DeleteTag(c *gin.Context) {
  16. }

注册路由

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

  1. package routers
  2. import (
  3. "github.com/gin-gonic/gin"
  4. "gin-blog/routers/api/v1"
  5. "gin-blog/pkg/setting"
  6. )
  7. func InitRouter() *gin.Engine {
  8. r := gin.New()
  9. r.Use(gin.Logger())
  10. r.Use(gin.Recovery())
  11. gin.SetMode(setting.RunMode)
  12. apiv1 := r.Group("/api/v1")
  13. {
  14. //获取标签列表
  15. apiv1.GET("/tags", v1.GetTags)
  16. //新建标签
  17. apiv1.POST("/tags", v1.AddTag)
  18. //更新指定标签
  19. apiv1.PUT("/tags/:id", v1.EditTag)
  20. //删除指定标签
  21. apiv1.DELETE("/tags/:id", v1.DeleteTag)
  22. }
  23. return r
  24. }

当前目录结构:

  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

检验路由是否注册成功

回到命令行,执行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. [GIN-debug] GET /api/v1/tags --> gin-blog/routers/api/v1.GetTags (3 handlers)
  6. [GIN-debug] POST /api/v1/tags --> gin-blog/routers/api/v1.AddTag (3 handlers)
  7. [GIN-debug] PUT /api/v1/tags/:id --> gin-blog/routers/api/v1.EditTag (3 handlers)
  8. [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. package models
  2. type Tag struct {
  3. Model
  4. Name string `json:"name"`
  5. CreatedBy string `json:"created_by"`
  6. ModifiedBy string `json:"modified_by"`
  7. State int `json:"state"`
  8. }
  9. func GetTags(pageNum int, pageSize int, maps interface {}) (tags []Tag) {
  10. db.Where(maps).Offset(pageNum).Limit(pageSize).Find(&tags)
  11. return
  12. }
  13. func GetTagTotal(maps interface {}) (count int){
  14. db.Model(&Tag{}).Where(maps).Count(&count)
  15. return
  16. }
  1. 我们创建了一个Tag struct{},用于Gorm的使用。并给予了附属属性json,这样子在c.JSON的时候就会自动转换格式,非常的便利

  2. 可能会有的初学者看到return,而后面没有跟着变量,会不理解;其实你可以看到在函数末端,我们已经显示声明了返回值,这个变量在函数体内也可以直接使用,因为他在一开始就被声明了

  3. 有人会疑惑db是哪里来的;因为在同个models包下,因此db *gorm.DB是可以直接使用的

编写标签列表的路由逻辑

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

修改文件内容:

  1. package v1
  2. import (
  3. "net/http"
  4. "github.com/gin-gonic/gin"
  5. //"github.com/astaxie/beego/validation"
  6. "github.com/Unknwon/com"
  7. "gin-blog/pkg/e"
  8. "gin-blog/models"
  9. "gin-blog/pkg/util"
  10. "gin-blog/pkg/setting"
  11. )
  12. //获取多个文章标签
  13. func GetTags(c *gin.Context) {
  14. name := c.Query("name")
  15. maps := make(map[string]interface{})
  16. data := make(map[string]interface{})
  17. if name != "" {
  18. maps["name"] = name
  19. }
  20. var state int = -1
  21. if arg := c.Query("state"); arg != "" {
  22. state = com.StrTo(arg).MustInt()
  23. maps["state"] = state
  24. }
  25. code := e.SUCCESS
  26. data["lists"] = models.GetTags(util.GetPage(c), setting.PageSize, maps)
  27. data["total"] = models.GetTagTotal(maps)
  28. c.JSON(http.StatusOK, gin.H{
  29. "code" : code,
  30. "msg" : e.GetMsg(code),
  31. "data" : data,
  32. })
  33. }
  34. //新增文章标签
  35. func AddTag(c *gin.Context) {
  36. }
  37. //修改文章标签
  38. func EditTag(c *gin.Context) {
  39. }
  40. //删除文章标签
  41. func DeleteTag(c *gin.Context) {
  42. }
  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. return false
  9. }
  10. func AddTag(name string, state int, createdBy string) bool{
  11. db.Create(&Tag {
  12. Name : name,
  13. State : state,
  14. CreatedBy : createdBy,
  15. })
  16. return true
  17. }
  18. ...

编写新增标签的路由逻辑

打开routers目录下的tag.go,修改文件(变动 AddTag 方法):

  1. package v1
  2. import (
  3. "log"
  4. "net/http"
  5. "github.com/gin-gonic/gin"
  6. "github.com/astaxie/beego/validation"
  7. "github.com/Unknwon/com"
  8. "gin-blog/pkg/e"
  9. "gin-blog/models"
  10. "gin-blog/pkg/util"
  11. "gin-blog/pkg/setting"
  12. )
  13. ...
  14. //新增文章标签
  15. func AddTag(c *gin.Context) {
  16. name := c.Query("name")
  17. state := com.StrTo(c.DefaultQuery("state", "0")).MustInt()
  18. createdBy := c.Query("created_by")
  19. valid := validation.Validation{}
  20. valid.Required(name, "name").Message("名称不能为空")
  21. valid.MaxSize(name, 100, "name").Message("名称最长为100字符")
  22. valid.Required(createdBy, "created_by").Message("创建人不能为空")
  23. valid.MaxSize(createdBy, 100, "created_by").Message("创建人最长为100字符")
  24. valid.Range(state, 0, 1, "state").Message("状态只允许0或1")
  25. code := e.INVALID_PARAMS
  26. if ! valid.HasErrors() {
  27. if ! models.ExistTagByName(name) {
  28. code = e.SUCCESS
  29. models.AddTag(name, state, createdBy)
  30. } else {
  31. code = e.ERROR_EXIST_TAG
  32. }
  33. }
  34. c.JSON(http.StatusOK, gin.H{
  35. "code" : code,
  36. "msg" : e.GetMsg(code),
  37. "data" : make(map[string]string),
  38. })
  39. }
  40. ...

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. import (
  3. "time"
  4. "github.com/jinzhu/gorm"
  5. )
  6. ...
  7. func (tag *Tag) BeforeCreate(scope *gorm.Scope) error {
  8. scope.SetColumn("CreatedOn", time.Now().Unix())
  9. return nil
  10. }
  11. func (tag *Tag) BeforeUpdate(scope *gorm.Scope) error {
  12. scope.SetColumn("ModifiedOn", time.Now().Unix())
  13. return nil
  14. }

重启服务,再在用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. valid := validation.Validation{}
  8. var state int = -1
  9. if arg := c.Query("state"); arg != "" {
  10. state = com.StrTo(arg).MustInt()
  11. valid.Range(state, 0, 1, "state").Message("状态只允许0或1")
  12. }
  13. valid.Required(id, "id").Message("ID不能为空")
  14. valid.Required(modifiedBy, "modified_by").Message("修改人不能为空")
  15. valid.MaxSize(modifiedBy, 100, "modified_by").Message("修改人最长为100字符")
  16. valid.MaxSize(name, 100, "name").Message("名称最长为100字符")
  17. code := e.INVALID_PARAMS
  18. if ! valid.HasErrors() {
  19. code = e.SUCCESS
  20. if models.ExistTagByID(id) {
  21. data := make(map[string]interface{})
  22. data["modified_by"] = modifiedBy
  23. if name != "" {
  24. data["name"] = name
  25. }
  26. if state != -1 {
  27. data["state"] = state
  28. }
  29. models.EditTag(id, data)
  30. } else {
  31. code = e.ERROR_NOT_EXIST_TAG
  32. }
  33. }
  34. c.JSON(http.StatusOK, gin.H{
  35. "code" : code,
  36. "msg" : e.GetMsg(code),
  37. "data" : make(map[string]string),
  38. })
  39. }
  40. //删除文章标签
  41. func DeleteTag(c *gin.Context) {
  42. id := com.StrTo(c.Param("id")).MustInt()
  43. valid := validation.Validation{}
  44. valid.Min(id, 1, "id").Message("ID必须大于0")
  45. code := e.INVALID_PARAMS
  46. if ! valid.HasErrors() {
  47. code = e.SUCCESS
  48. if models.ExistTagByID(id) {
  49. models.DeleteTag(id)
  50. } else {
  51. code = e.ERROR_NOT_EXIST_TAG
  52. }
  53. }
  54. c.JSON(http.StatusOK, gin.H{
  55. "code" : code,
  56. "msg" : e.GetMsg(code),
  57. "data" : make(map[string]string),
  58. })
  59. }

编写其余接口的 models 逻辑

打开models下的tag.go,修改文件内容:

  1. ...
  2. func ExistTagByID(id int) bool {
  3. var tag Tag
  4. db.Select("id").Where("id = ?", id).First(&tag)
  5. if tag.ID > 0 {
  6. return true
  7. }
  8. return false
  9. }
  10. func DeleteTag(id int) bool {
  11. db.Where("id = ?", id).Delete(&Tag{})
  12. return true
  13. }
  14. func EditTag(id int, data interface {}) bool {
  15. db.Model(&Tag{}).Where("id = ?", id).Updates(data)
  16. return true
  17. }
  18. ...

验证功能

重启服务,用 Postman

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

参考

本系列示例代码

关于

修改记录

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

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

我的公众号

image