歡迎光臨
每天分享高質量文章

才雲 Caicloud 開源 Nirvana:讓 API 從對框架的依賴中涅槃重生

來自 | 才雲 Caicloud(Caicloud2015)
內容 | 郭維 社區開發者
自 2009 年開源以來,Go 作為一種強大、高效、簡潔、易上手的編程語言,在幫助閱讀、除錯和維護大型軟體系統上發揮著越來越重要的作用。而依托其健康生態,Golang 社區也相繼涌現出諸如 beego、gin、chi、go-restful 等知名框架,為 Go 提供額外功能支持。
但選擇過多,反受其亂。面對層出不窮的優秀框架,不同團隊、不同開發者在框架選擇上往往會出現分歧,不同框架之間也彼此壁壘高築,導致業務與框架耦合,開發效率大大降低
為瞭解決這類問題,才雲 Caicloud 實現了 Golang API 框架 Nirvana,把 API 從對框架的依賴中徹底解放出來。它專為提高生產力和可用性設計,可擴展、性能高,旨在成為才雲 Caicloud 所有 Golang 服務的基石,助力業務的高速開發。

接軌 Kubernetes 這些痛點不可忽視

近年來,為了滿足業務發展需要,應對日益激烈的市場競爭,大量企業開始使用容器部署雲工作負載。而隨著容器使用量的增長、Kubernetes 成為容器編排的事實標準,在 Kubernetes 上打造新一代容器雲平臺成了企業謀求發展的必由之路。
為了順應時局,技術團隊除了進行思維上的轉變,還要應對團隊和業務方向的調整,對團隊專案和產品完成切割分化。這之中就涉及對 Go 框架變更的抉擇。
兩年前,才雲 Caicloud 團隊在構建基於 Kubernetes 的雲平臺時,在框架上遇到了不少麻煩:當時 Kubernetes 正值發展期,為了快速開發,工程師們往往傾向於選擇自己熟悉的框架。因此,雖然大多數專案用的是 go-restful(Kubernetes 的選型),但用 beego、gin、chi 等框架的工程師也不在少數,這就給業務整合帶來了很多問題:
  • 不同框架對 API 的描述形式不一致,這增加了不同團隊間的溝通成本;

  • 不同框架 API 風格差距較大,文件自動化困難;

  • 錯誤定義和處理方式在不同專案之間存在差別,會導致客戶端處理困難。

曾經開放的工程師文化成了變革的最大阻力

業務和框架隔離 Nirvana 出奇招

Nirvana 就是在這個背景下誕生的。
借鑒了 Kubernetes 宣告式 API 的設計,巧妙規避了框架對 API 的侵入。同時,為了實現業務和框架的隔離,它定義一個規範,讓 API 按照規範書寫,完全屏蔽了框架對 API 的影響。
一言以蔽之,Nirvana 框架的設計思路始終圍繞工程師們親歷的種種痛點:
  • 構建風格一致的 API 專案;

  • 使用統一的 RESTful 路由與宣告式 API 定義,避免業務對框架產生依賴;

  • 使用統一的錯誤生成和處理方式;

  • 提供開箱即用的基礎功能,包括 Prometheus metrics、tracing、profiling 等;

  • 自動生成 API 文件和客戶端代碼。

在 Nirvana 中,用一套 API Definition 來宣告式地描述業務 API。下麵是一個列出訊息串列 API 的例子:
  1. Definition{
  2.    // 這個 API 傳回的是資源陣列,所以使用 List 方法。
  3.    Method:     def.List,
  4.    // Summary 是一個短語,用於描述這個 API 的用途。這個短語在生成文件和客戶端的時候用於區分 API。
  5.    // 這個字串去掉空格後會作為生成客戶端時的函式名,因此請確保這個字串是有意義的。
  6.    Summary:    "List Messages",
  7.    // 詳細描述這個 API 的用途。
  8.    Description: "Query a specified number of messages and returns an array",
  9.    // 業務函式
  10.    Function:   message.ListMessages,
  11.    // 對應業務函式的引數信息。用於告知 Nirvana 從請求的那一部分取得資料,然後傳遞給業務函式。
  12.    Parameters: []def.Parameter{
  13.        {
  14.            // 引數來源
  15.            Source:     def.Query,
  16.            // 引數名稱,作為 key 從 Source 里取值。
  17.            // 與業務函式的引數名稱無關。
  18.            Name:       "count",
  19.            // 預設值
  20.            Default:    10,
  21.            // 引數描述
  22.            Description: "Number of messages",
  23.        },
  24.    },
  25.    // 對應業務函式的傳回結果。用於告知 Nirvana 業務函式傳回結果如何放到請求的響應中。
  26.    Results: def.DataErrorResults("A list of messages"),
  27. }
而對應業務 API 的形式則是:
  1. type Message struct {
  2.    ID      int `json:"id"`
  3.    Title   string `json:"title"`
  4.    Content string `json:"content"`
  5. }
  6. func ListMessages(ctx context.Context, count int) ([]Message, error) {
  7.    messages := make([]Message, count)
  8.    for i := 0; i < count; i++ {
  9.        messages[i].ID = i
  10.        messages[i].Title = fmt.Sprintf("Example %d", i)
  11.        messages[i].Content = fmt.Sprintf("Content of example %d", i)
  12.    }
  13.    return messages, nil
  14. }
很顯然,業務函式並不關心自身是如何暴露給外部的,實現方法也和其他內部函式沒有差別(這隻是一個簡單的例子,更多詳細內容請查閱 Nirvana Definition 文件:https://caicloud.github.io/nirvana/zh-hans/topics/definition.html)。
在這個例子里,API Definition 描述了完整的 API 結構,包括 RESTful 路徑、請求方法、請求描述、請求引數、請求響應和請求 handler。框架只需要解析 API Definition,就能得到業務邏輯的入口和出口處理方式。對開發者而言,API 的開發過程從“ 命令式路由 + 資料轉換 + 業務邏輯” 變成了“API Definition + 業務邏輯”。框架與業務邏輯之間通過 API Definition 進行橋接。
Nirvana 框架

API Definition 作為宣告式 API,除了讓框架讀取信息生成路由和對外提供服務,它本身也完整描述了一個 API 的工作方式。因此,還能用它生成 openapi 文件和客戶端。在接下來的幾個小節中,將詳述 Nirvana 提供的這些能力。
 
路由工作流
任何一個 API 框架都具備基本的 HTTP Serve 能力( HTTP 接口服務能力)。在 Nirvana 中,HTTP Serve 由 Golang 基礎庫 http 提供。HTTP 請求的路由方式如下圖所示:
在這個請求的工作流中:
 
  • Filters 是請求過濾器,可以對不符合要求的請求進行提前響應,而不會進入路由匹配過程;

  • Middlewares 是圍繞請求的中間件,能夠控制請求的處理行為;

  • Executor 是最終處理請求的執行器,負責通過引數生成器(ParameterGenerators)和結果處理器(DestinationHandlers)將請求註入到業務邏輯之中,並將傳回結果處理後傳回。

在這裡,Filters、Middlewares、ParameterGenerators 和 DestinationHandlers 都是可以被開發者重新定義的。這也意味著開發者可以改變 Nirvana 的原生處理行為,使之符合自身需求。
 
服務構建工作流
Nirvana 另一個工作流是將 API Definition 構建到路由中去,並完成整個服務的啟動工作。
在 Nirvana 啟動時,除 API Definition 之外,它還能夠通過插件往框架里註入一些功能,包括註冊 Filters、Middlewares、添加其他路由 endpoint 等。目前 Nirvana 已經提供對 metrics、profiling、tracing、log 等常用插件的支持。
通過以上兩個工作流,以及 Nirvana 中大量的模塊方法註冊接口,開發者可以自行擴展 API Definition 的能力,讓 API Definition 與業務邏輯更加貼合。API Definition 單向依賴並描述了業務邏輯,並作為框架和業務之間的橋梁,既達到了宣告式 API 的定義形式,也滿足了業務不依賴框架的標的。
 
框架擴展
無論是路由還是服務構建過程,Nirvana 的實現都不是 hardcode 的。在框架的大部分包里,你能發現類似以下形式的代碼結構:
  1. var consumers = map[string]Consumer{
  2.    definition.MIMENone:        &NoneSerializer{},
  3.    definition.MIMEText:        NewSimpleSerializer(definition.MIMEText),
  4.    definition.MIMEJSON:        &JSONSerializer{},
  5.    definition.MIMEXML:         &XMLSerializer{},
  6.    definition.MIMEOctetStream: NewSimpleSerializer(definition.MIMEOctetStream),
  7.    definition.MIMEURLEncoded:  &URLEncodedConsumer{},
  8.    definition.MIMEFormData:    &FormDataConsumer{},
  9. }
  10. // RegisterConsumer register a consumer. A consumer must not handle "*/*".
  11. func RegisterConsumer(c Consumer) error {
  12.    if c.ContentType() == definition.MIMEAll {
  13.        return invalidConsumer.Error(definition.MIMEAll)
  14.    }
  15.    consumers[c.ContentType()] = c
  16.    return nil
  17. }
在這種結構里,開發者可以自定義每一塊的實現方式,甚至替換框架預設行為。幫助自己最大限度地利用 Nirvana,使它符合業務特定需求。
 
插件機制
在服務構建工作流中,提到了插件機制。下麵介紹三個重要插件 metrics、profiling和tracing。
 
1. metrics 插件
Prometheus 作為 CNCF 的開源專案,為我們提供了非常適於描述業務指標的格式:Prometheus Metrics。Nirvana 提供的 metrics 插件可以在啟動時預設暴露 /metrics 接口。對此,開發者可以將業務指標註冊到 Prometheus 中,通過這個接口讓 Prometheus 採集。也就是說,Nirvana 不僅能幫助開發者瞭解業務的運行狀態,也為開發者定位業務問題提供了強有力的幫助。
 
2. profiling 插件
Golang 提供了行程級別的 profiling 能力。Nirvana 通過 profiling 插件直接將這個能力註入到框架中。開發者只需要啟用插件即可獲得這些除錯和性能測試能力,獲得業務內部執行的狀態信息。 
 
3. tracing 插件
在 CloudNative 時代,業務通常會以微服務或 Serverless 的形式進行架構。多個服務之間的交互通常是黑盒的,這易導致我們難以定位分佈式架構中的服務問題。Tracing 作為解決分佈式架構下的呼叫鏈方案,可以在分佈式系統出現問題時為開發者提供大量的信息,幫助開發者排查問題。Nirvana 的 tracing 插件使用了 open-tracing 的接口規範,並借助 CNCF 開源專案 jaeger 的能力,為開發者提供一站式 tracing 方案。
 
文件和客戶端生成
API Definition 和 Nirvana 的結合幫助我們完成了服務構建。在服務之外,通過 API Definition 的描述能力,Nirvana 還實現了基於 openapi 的文件生成和客戶端生成。
Nirvana 的文件生成基於 openapi 2.0(即 swagger 2.0)規範,從 API Definition 中提取 API 信息,生成 API 描述檔案 swagger.json。除了生成 API 描述檔案之外,它還能通過 ReDoc 直接提供文件服務(更多信息請查看 https://caicloud.github.io/nirvana/zh-hans/guides/doc.html)。
在 Nirvana 中,生成文件的方式十分簡單:
  1. $ nirvana api --serve=":8081"
只需一條命令,API 文件即可生成,並通過 8081 端口提供服務。之後我們就能通過網頁查看文件了:
Nirvana 的客戶端生成同樣基於 API Definition ——讀取型別信息,生成客戶端包(目前僅支持生成 Golang 包)。客戶可以直接取用這個包來呼叫服務,整個客戶端的使用方式與本地呼叫一致(更多信息請查看 https://caicloud.github.io/nirvana/zh-hans/guides/client.html)。 
下麵是一鍵生成客戶端的示例:
  1. $ nirvana client
這個命令會在當前目錄下生成一個 client 目錄,在這個目錄內生成 Golang 客戶端代碼:
  1. type Client struct {
  2.    rest *rest.Client
  3. }
  4. // ListMessages returns all messages.
  5. func (c *Client) ListMessages(ctx context.Context, count int) (messages []Message, err error) {
  6.    err = c.rest.Request("GET", 200, "/apis/v1/messages").
  7.        Query("count", count).
  8.        Data(&messages).
  9.        Do(ctx)
  10.    return
  11. }
如果您想進一步瞭解 Nirvana,可以參考才雲 Caicloud 雲原生 CI/CD 專案 Cyclone(更多信息請查看 https://github.com/caicloud/cyclone)。它包含一個 API 組件 Cyclone Server, 基於 Nirvana 對外提供簡單易用的 API。
Nirvana:涅槃

Nirvana,梵語中的涅槃。
一如我們對它的期待:讓 API 從對框架的依賴中涅槃重生。
經過一年多的開源,目前 Nirvana 在基礎 API 服務能力上已經經過內部驗證。由於資料傳輸層和轉換層的複雜度被大大降低,才雲 Caicloud 也切物體驗到了這個開源框架帶來的便捷,以及它在加速業務開發上的顯著效果。
未來,Nirvana 將在以下幾方面繼續發力:
  • 持續優化擴展文件和客戶端生成的能力,降低開發者在這兩塊上的心智負擔;

  • 持續優化 metrics、profiling、tracing 的能力,並增加新的雲原生能力,讓這些能力成為雲原生應用的標配;

  • 框架模塊化加強,讓 Nirvana 的每一塊代碼皆可定製;

  • 優化框架性能,降低反射對服務的影響;

  • 讓 Nirvana 成為 Golang 的 CloudNative & SOA 框架。

Nirvana 正致力於成為讓業務無感知的框架。目前,才雲 Caicloud 正在這條路上踽踽獨行,也真誠地希望將來能有更多開發者願意加入進來,一起構建 Nirvana,一起建設 Golang 社區,一起擁抱開源的勝利。
也許你的加入,能讓這場涅槃更加炫目!
感謝參與開源本專案的所有開發者!
Nirvana GitHub:https://github.com/caicloud/nirvana
Nirvana 文件:https://caicloud.github.io/nirvana/zh-hans/

來自 | 才雲 Caicloud(Caicloud2015);內容 | 郭維 社區開發者

赞(0)

分享創造快樂