golang restful 架構之 go-swagger

這是一個建立於 的文章，其中的資訊可能已經有所發展或是發生改變。

restful 是這些年的高頻詞彙了，各大互連網公司也都紛紛推出了自己的 restful api，其實 restful 和 thrift，grpc 類似，就是一種協議，但是這種協議有點特殊的就是使用 http 介面，返回的對象一般是 json 格式，這樣有個好處，就是可以供前端的 js 直接調用，使用非常方便，但 http 本身並不是一個高效的協議，後端的內部通訊還是使用 grpc 或者 thrift 可以獲得更高的效能

其實如果只是要用 http 返回 json 本身並不是一件很難的事情，不用任何架構，golang 本身也能很方便做到，但是當你有很多 api 的時候，這些 api 的維護和管理就會變得很複雜，你自己都無法記住這些 api 應該填什麼參數，返回什麼，當然你可以花很多時間去維護一份介面文檔，這樣不僅耗時而且很難保證文檔的即時性，準確性以及一致性

swagger 有一整套規範來定義一個介面檔案，類似於 thrift 和 proto 檔案，定義了服務的請求內容和返回內容，同樣也有工具可以產生各種不同語言的架構代碼，在 golang 裡面我們使用 go-swagger 這個工具，這個工具還提供了額外的功能，可以可視化顯示這個介面，方便閱讀

下面通過一個例子來簡單介紹一下這個架構的使用，還是之前的點贊評論系統：https://github.com/hatlonely/...

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-swaggerbrew install go-swagger

Linux

go get -u github.com/go-swagger/go-swagger/cmd/swaggerexport 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 官方文檔：https://goswagger.io
• go-swagger github：https://github.com/go-swagger...
• OpenApi 2.0：https://github.com/OAI/OpenAP...

轉載請註明出處
本文連結：http://hatlonely.github.io/20...