Gin搭建Blog API’s (三)

涉及知识点

本文目标

  • 完成博客的文章类接口定义和编写

定义接口

本节编写文章的逻辑,我们定义一下接口吧!

  • 获取文章列表:GET(“/articles”)
  • 获取指定文章:POST(“/articles/:id”)
  • 新建文章:POST(“/articles”)
  • 更新指定文章:PUT(“/articles/:id”)
  • 删除指定文章:DELETE(“/articles/:id”)

编写路由逻辑

routers的 v1 版本下,新建article.go文件,写入内容:

  1. package v1
  2. import (
  3. "github.com/gin-gonic/gin"
  4. )
  5. //获取单个文章
  6. func GetArticle(c *gin.Context) {
  7. }
  8. //获取多个文章
  9. func GetArticles(c *gin.Context) {
  10. }
  11. //新增文章
  12. func AddArticle(c *gin.Context) {
  13. }
  14. //修改文章
  15. func EditArticle(c *gin.Context) {
  16. }
  17. //删除文章
  18. func DeleteArticle(c *gin.Context) {
  19. }

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

  1. package routers
  2. import (
  3. "github.com/gin-gonic/gin"
  4. "github.com/EDDYCJY/go-gin-example/routers/api/v1"
  5. "github.com/EDDYCJY/go-gin-example/pkg/setting"
  6. )
  7. func InitRouter() *gin.Engine {
  8. ...
  9. apiv1 := r.Group("/api/v1")
  10. {
  11. ...
  12. //获取文章列表
  13. apiv1.GET("/articles", v1.GetArticles)
  14. //获取指定文章
  15. apiv1.GET("/articles/:id", v1.GetArticle)
  16. //新建文章
  17. apiv1.POST("/articles", v1.AddArticle)
  18. //更新指定文章
  19. apiv1.PUT("/articles/:id", v1.EditArticle)
  20. //删除指定文章
  21. apiv1.DELETE("/articles/:id", v1.DeleteArticle)
  22. }
  23. return r
  24. }

当前目录结构:

  1. go-gin-example/
  2. ├── conf
  3. └── app.ini
  4. ├── main.go
  5. ├── middleware
  6. ├── models
  7. ├── models.go
  8. └── tag.go
  9. ├── pkg
  10. ├── e
  11. ├── code.go
  12. └── msg.go
  13. ├── setting
  14. └── setting.go
  15. └── util
  16. └── pagination.go
  17. ├── routers
  18. ├── api
  19. └── v1
  20. ├── article.go
  21. └── tag.go
  22. └── router.go
  23. ├── runtime

在基础的路由规则配置结束后,我们开始编写我们的接口吧!


编写 models 逻辑

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

  1. package models
  2. import (
  3. "github.com/jinzhu/gorm"
  4. "time"
  5. )
  6. type Article struct {
  7. Model
  8. TagID int `json:"tag_id" gorm:"index"`
  9. Tag Tag `json:"tag"`
  10. Title string `json:"title"`
  11. Desc string `json:"desc"`
  12. Content string `json:"content"`
  13. CreatedBy string `json:"created_by"`
  14. ModifiedBy string `json:"modified_by"`
  15. State int `json:"state"`
  16. }
  17. func (article *Article) BeforeCreate(scope *gorm.Scope) error {
  18. scope.SetColumn("CreatedOn", time.Now().Unix())
  19. return nil
  20. }
  21. func (article *Article) BeforeUpdate(scope *gorm.Scope) error {
  22. scope.SetColumn("ModifiedOn", time.Now().Unix())
  23. return nil
  24. }

我们创建了一个Article struct {},与Tag不同的是,Article多了几项,如下:

  1. gorm:index,用于声明这个字段为索引,如果你使用了自动迁移功能则会有所影响,在不使用则无影响
  2. Tag字段,实际是一个嵌套的struct,它利用TagIDTag模型相互关联,在执行查询的时候,能够达到ArticleTag关联查询的功能
  3. time.Now().Unix() 返回当前的时间戳

接下来,请确保已对上一章节的内容通读且了解,由于逻辑偏差不会太远,我们本节直接编写这五个接口


打开models目录下的article.go,修改文件内容:

  1. package models
  2. import (
  3. "time"
  4. "github.com/jinzhu/gorm"
  5. )
  6. type Article struct {
  7. Model
  8. TagID int `json:"tag_id" gorm:"index"`
  9. Tag Tag `json:"tag"`
  10. Title string `json:"title"`
  11. Desc string `json:"desc"`
  12. Content string `json:"content"`
  13. CreatedBy string `json:"created_by"`
  14. ModifiedBy string `json:"modified_by"`
  15. State int `json:"state"`
  16. }
  17. func ExistArticleByID(id int) bool {
  18. var article Article
  19. db.Select("id").Where("id = ?", id).First(&article)
  20. if article.ID > 0 {
  21. return true
  22. }
  23. return false
  24. }
  25. func GetArticleTotal(maps interface {}) (count int){
  26. db.Model(&Article{}).Where(maps).Count(&count)
  27. return
  28. }
  29. func GetArticles(pageNum int, pageSize int, maps interface {}) (articles []Article) {
  30. db.Preload("Tag").Where(maps).Offset(pageNum).Limit(pageSize).Find(&articles)
  31. return
  32. }
  33. func GetArticle(id int) (article Article) {
  34. db.Where("id = ?", id).First(&article)
  35. db.Model(&article).Related(&article.Tag)
  36. return
  37. }
  38. func EditArticle(id int, data interface {}) bool {
  39. db.Model(&Article{}).Where("id = ?", id).Updates(data)
  40. return true
  41. }
  42. func AddArticle(data map[string]interface {}) bool {
  43. db.Create(&Article {
  44. TagID : data["tag_id"].(int),
  45. Title : data["title"].(string),
  46. Desc : data["desc"].(string),
  47. Content : data["content"].(string),
  48. CreatedBy : data["created_by"].(string),
  49. State : data["state"].(int),
  50. })
  51. return true
  52. }
  53. func DeleteArticle(id int) bool {
  54. db.Where("id = ?", id).Delete(Article{})
  55. return true
  56. }
  57. func (article *Article) BeforeCreate(scope *gorm.Scope) error {
  58. scope.SetColumn("CreatedOn", time.Now().Unix())
  59. return nil
  60. }
  61. func (article *Article) BeforeUpdate(scope *gorm.Scope) error {
  62. scope.SetColumn("ModifiedOn", time.Now().Unix())
  63. return nil
  64. }

在这里,我们拿出三点不同来讲,如下:

1、 我们的Article是如何关联到Tag

  1. func GetArticle(id int) (article Article) {
  2. db.Where("id = ?", id).First(&article)
  3. db.Model(&article).Related(&article.Tag)
  4. return
  5. }

能够达到关联,首先是gorm本身做了大量的约定俗成

  • Article有一个结构体成员是TagID,就是外键。gorm会通过类名+ID 的方式去找到这两个类之间的关联关系
  • Article有一个结构体成员是Tag,就是我们嵌套在Article里的Tag结构体,我们可以通过Related进行关联查询

2、 Preload是什么东西,为什么查询可以得出每一项的关联Tag

  1. func GetArticles(pageNum int, pageSize int, maps interface {}) (articles []Article) {
  2. db.Preload("Tag").Where(maps).Offset(pageNum).Limit(pageSize).Find(&articles)
  3. return
  4. }

Preload就是一个预加载器,它会执行两条 SQL,分别是SELECT * FROM blog_articles;SELECT * FROM blog_tag WHERE id IN (1,2,3,4);,那么在查询出结构后,gorm内部处理对应的映射逻辑,将其填充到ArticleTag中,会特别方便,并且避免了循环查询

那么有没有别的办法呢,大致是两种

  • gormJoin
  • 循环Related

综合之下,还是Preload更好,如果你有更优的方案,欢迎说一下 :)

3、 v.(I) 是什么?

v表示一个接口值,I表示接口类型。这个实际就是 Golang 中的类型断言,用于判断一个接口值的实际类型是否为某个类型,或一个非接口值的类型是否实现了某个接口类型


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

  1. package v1
  2. import (
  3. "net/http"
  4. "log"
  5. "github.com/gin-gonic/gin"
  6. "github.com/astaxie/beego/validation"
  7. "github.com/unknwon/com"
  8. "github.com/EDDYCJY/go-gin-example/models"
  9. "github.com/EDDYCJY/go-gin-example/pkg/e"
  10. "github.com/EDDYCJY/go-gin-example/pkg/setting"
  11. "github.com/EDDYCJY/go-gin-example/pkg/util"
  12. )
  13. //获取单个文章
  14. func GetArticle(c *gin.Context) {
  15. id := com.StrTo(c.Param("id")).MustInt()
  16. valid := validation.Validation{}
  17. valid.Min(id, 1, "id").Message("ID必须大于0")
  18. code := e.INVALID_PARAMS
  19. var data interface {}
  20. if ! valid.HasErrors() {
  21. if models.ExistArticleByID(id) {
  22. data = models.GetArticle(id)
  23. code = e.SUCCESS
  24. } else {
  25. code = e.ERROR_NOT_EXIST_ARTICLE
  26. }
  27. } else {
  28. for _, err := range valid.Errors {
  29. log.Printf("err.key: %s, err.message: %s", err.Key, err.Message)
  30. }
  31. }
  32. c.JSON(http.StatusOK, gin.H{
  33. "code" : code,
  34. "msg" : e.GetMsg(code),
  35. "data" : data,
  36. })
  37. }
  38. //获取多个文章
  39. func GetArticles(c *gin.Context) {
  40. data := make(map[string]interface{})
  41. maps := make(map[string]interface{})
  42. valid := validation.Validation{}
  43. var state int = -1
  44. if arg := c.Query("state"); arg != "" {
  45. state = com.StrTo(arg).MustInt()
  46. maps["state"] = state
  47. valid.Range(state, 0, 1, "state").Message("状态只允许0或1")
  48. }
  49. var tagId int = -1
  50. if arg := c.Query("tag_id"); arg != "" {
  51. tagId = com.StrTo(arg).MustInt()
  52. maps["tag_id"] = tagId
  53. valid.Min(tagId, 1, "tag_id").Message("标签ID必须大于0")
  54. }
  55. code := e.INVALID_PARAMS
  56. if ! valid.HasErrors() {
  57. code = e.SUCCESS
  58. data["lists"] = models.GetArticles(util.GetPage(c), setting.PageSize, maps)
  59. data["total"] = models.GetArticleTotal(maps)
  60. } else {
  61. for _, err := range valid.Errors {
  62. log.Printf("err.key: %s, err.message: %s", err.Key, err.Message)
  63. }
  64. }
  65. c.JSON(http.StatusOK, gin.H{
  66. "code" : code,
  67. "msg" : e.GetMsg(code),
  68. "data" : data,
  69. })
  70. }
  71. //新增文章
  72. func AddArticle(c *gin.Context) {
  73. tagId := com.StrTo(c.Query("tag_id")).MustInt()
  74. title := c.Query("title")
  75. desc := c.Query("desc")
  76. content := c.Query("content")
  77. createdBy := c.Query("created_by")
  78. state := com.StrTo(c.DefaultQuery("state", "0")).MustInt()
  79. valid := validation.Validation{}
  80. valid.Min(tagId, 1, "tag_id").Message("标签ID必须大于0")
  81. valid.Required(title, "title").Message("标题不能为空")
  82. valid.Required(desc, "desc").Message("简述不能为空")
  83. valid.Required(content, "content").Message("内容不能为空")
  84. valid.Required(createdBy, "created_by").Message("创建人不能为空")
  85. valid.Range(state, 0, 1, "state").Message("状态只允许0或1")
  86. code := e.INVALID_PARAMS
  87. if ! valid.HasErrors() {
  88. if models.ExistTagByID(tagId) {
  89. data := make(map[string]interface {})
  90. data["tag_id"] = tagId
  91. data["title"] = title
  92. data["desc"] = desc
  93. data["content"] = content
  94. data["created_by"] = createdBy
  95. data["state"] = state
  96. models.AddArticle(data)
  97. code = e.SUCCESS
  98. } else {
  99. code = e.ERROR_NOT_EXIST_TAG
  100. }
  101. } else {
  102. for _, err := range valid.Errors {
  103. log.Printf("err.key: %s, err.message: %s", err.Key, err.Message)
  104. }
  105. }
  106. c.JSON(http.StatusOK, gin.H{
  107. "code" : code,
  108. "msg" : e.GetMsg(code),
  109. "data" : make(map[string]interface{}),
  110. })
  111. }
  112. //修改文章
  113. func EditArticle(c *gin.Context) {
  114. valid := validation.Validation{}
  115. id := com.StrTo(c.Param("id")).MustInt()
  116. tagId := com.StrTo(c.Query("tag_id")).MustInt()
  117. title := c.Query("title")
  118. desc := c.Query("desc")
  119. content := c.Query("content")
  120. modifiedBy := c.Query("modified_by")
  121. var state int = -1
  122. if arg := c.Query("state"); arg != "" {
  123. state = com.StrTo(arg).MustInt()
  124. valid.Range(state, 0, 1, "state").Message("状态只允许0或1")
  125. }
  126. valid.Min(id, 1, "id").Message("ID必须大于0")
  127. valid.MaxSize(title, 100, "title").Message("标题最长为100字符")
  128. valid.MaxSize(desc, 255, "desc").Message("简述最长为255字符")
  129. valid.MaxSize(content, 65535, "content").Message("内容最长为65535字符")
  130. valid.Required(modifiedBy, "modified_by").Message("修改人不能为空")
  131. valid.MaxSize(modifiedBy, 100, "modified_by").Message("修改人最长为100字符")
  132. code := e.INVALID_PARAMS
  133. if ! valid.HasErrors() {
  134. if models.ExistArticleByID(id) {
  135. if models.ExistTagByID(tagId) {
  136. data := make(map[string]interface {})
  137. if tagId > 0 {
  138. data["tag_id"] = tagId
  139. }
  140. if title != "" {
  141. data["title"] = title
  142. }
  143. if desc != "" {
  144. data["desc"] = desc
  145. }
  146. if content != "" {
  147. data["content"] = content
  148. }
  149. data["modified_by"] = modifiedBy
  150. models.EditArticle(id, data)
  151. code = e.SUCCESS
  152. } else {
  153. code = e.ERROR_NOT_EXIST_TAG
  154. }
  155. } else {
  156. code = e.ERROR_NOT_EXIST_ARTICLE
  157. }
  158. } else {
  159. for _, err := range valid.Errors {
  160. log.Printf("err.key: %s, err.message: %s", err.Key, err.Message)
  161. }
  162. }
  163. c.JSON(http.StatusOK, gin.H{
  164. "code" : code,
  165. "msg" : e.GetMsg(code),
  166. "data" : make(map[string]string),
  167. })
  168. }
  169. //删除文章
  170. func DeleteArticle(c *gin.Context) {
  171. id := com.StrTo(c.Param("id")).MustInt()
  172. valid := validation.Validation{}
  173. valid.Min(id, 1, "id").Message("ID必须大于0")
  174. code := e.INVALID_PARAMS
  175. if ! valid.HasErrors() {
  176. if models.ExistArticleByID(id) {
  177. models.DeleteArticle(id)
  178. code = e.SUCCESS
  179. } else {
  180. code = e.ERROR_NOT_EXIST_ARTICLE
  181. }
  182. } else {
  183. for _, err := range valid.Errors {
  184. log.Printf("err.key: %s, err.message: %s", err.Key, err.Message)
  185. }
  186. }
  187. c.JSON(http.StatusOK, gin.H{
  188. "code" : code,
  189. "msg" : e.GetMsg(code),
  190. "data" : make(map[string]string),
  191. })
  192. }

当前目录结构:

  1. go-gin-example/
  2. ├── conf
  3. └── app.ini
  4. ├── main.go
  5. ├── middleware
  6. ├── models
  7. ├── article.go
  8. ├── models.go
  9. └── tag.go
  10. ├── pkg
  11. ├── e
  12. ├── code.go
  13. └── msg.go
  14. ├── setting
  15. └── setting.go
  16. └── util
  17. └── pagination.go
  18. ├── routers
  19. ├── api
  20. └── v1
  21. ├── article.go
  22. └── tag.go
  23. └── router.go
  24. ├── 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)
  9. [GIN-debug] GET /api/v1/articles --> gin-blog/routers/api/v1.GetArticles (3 handlers)
  10. [GIN-debug] GET /api/v1/articles/:id --> gin-blog/routers/api/v1.GetArticle (3 handlers)
  11. [GIN-debug] POST /api/v1/articles --> gin-blog/routers/api/v1.AddArticle (3 handlers)
  12. [GIN-debug] PUT /api/v1/articles/:id --> gin-blog/routers/api/v1.EditArticle (3 handlers)
  13. [GIN-debug] DELETE /api/v1/articles/:id --> gin-blog/routers/api/v1.DeleteArticle (3 handlers)

使用Postman检验接口是否正常,在这里大家可以选用合适的参数传递方式,此处为了方便展示我选用了 GET/Param 传参的方式,而后期会改为 POST。

至此,我们的 API’s 编写就到这里,下一节我们将介绍另外的一些技巧!

参考

本系列示例代码

关于

修改记录

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

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

我的公众号

image