golang restful 框架之 go-swagger

swagger 有一整套规范来定义一个接口文件，类似于 thrift 和 proto 文件，定义了服务的请求内容和返回内容，同样也有工具可以生成各种不同语言的框架代码，在 golang 里面我们使用 go-swagger 这个工具，这个工具还提供了额外的功能，可以可视化显示这个接口，方便阅读

go-swagger 使用方法

api 定义文件

首先需要写一个 api 定义文件，这里我只展示其中一个接口 countlike，请求中带有某篇文章，返回点赞的次数

paths:
  /countlike:
    get:
      tags:
        - like
      summary: 有多少赞
      description: ''
      operationId: countLike
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: title
          in: query
          description: 文章标题
          required: true
          type: string
      responses:
        '200':
          description: 成功
          schema:
            $ref: '#/definitions/CountLikeModel'
        '500':
          description: 内部错误
          schema:
            $ref: '#/definitions/ErrorModel'
definitions:
  CountLikeModel:
    type: object
    properties:
      count:
        type: integer
      title:
        type: string
        example: golang json 性能分析
  ErrorModel:
    type: object
    properties:
      message:
        type: string
        example: error message
      code:
        type: integer
        example: 400

这个是 yaml 语法，有点像去掉了括号的 json

这里完整地定义了请求方法、请求参数、正常返回接口、异常返回结果，有了这个文件只需要执行下面命令就能生成框架代码了

swagger generate server -f api/comment_like/comment_like.yaml

还可以下面这个命令可视化查看这个接口文件

swagger serve api/comment_like/comment_like.yaml

这个命令依赖 swagger 工具，可以通过下面命令获取

Mac

brew tap go-swagger/go-swagger
brew install go-swagger

Linux

go get -u 
export PATH=$GOPATH/bin:$PATH

执行完了之后，你发现多了几个文件夹，其中 cmd 目录里面包含 main 函数，是整个程序的入口，restapi 文件夹下面包含协议相关代码，其中 configure_xxx.go 是需要特别关注的，你需要在这个文件里面实现你具体的业务逻辑

现在你就其实已经可以运行程序了，go run cmd/comment-like-server/main.go，在浏览器里面访问一下你的 api，会返回一个错误信息，告诉你 api 还没有实现，下面就来实现一下吧

业务逻辑实现

api.LikeCountLikeHandler = like.CountLikeHandlerFunc(func(params like.CountLikeParams) middleware.Responder {
    count, err := comment_like.CountLike(params.Title)
    if err != nil {
        return like.NewCountLikeInternalServerError().WithPayload(&models.ErrorModel{
            Code: http.StatusInternalServerError,
            Message: err.Error(),
        })
    }
    return like.NewCountLikeOK().WithPayload(&models.CountLikeModel{
        Count: count,
        Title: params.Title,
    })
})

你只需要在这些 handler 里面实现自己的业务逻辑即可，这里对协议的封装非常好，除了业务逻辑以及打包返回，没有多余的逻辑

再次运行，现在返回已经正常了

统一处理

如果你对请求有一些操作需要统一处理，比如输出统一的日志之类的，可以重写这个函数，也在 configure_xxx.go 这个文件中

func setupGlobalMiddleware(handler http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        w.Header().Set("Access-Control-Allow-Origin", "*")
        handler.ServeHTTP(w, r)
    })
}

这里我统一设置了一下头部，解决跨域访问问题

参考链接

go-swagger 官方文档：
go-swagger github：
OpenApi 2.0：