自 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 的例子：

Definition{ // 這個 API 返回的是資源數組，所以使用 List 方法。 Method: def.List, // Summary 是一個短語，用于描述這個 API 的用途。這個短語在生成文檔和客戶端的時候用于區分 API。 // 這個字符串去掉空格后會作為生成客戶端時的函數名，因此請確保這個字符串是有意義的。 Summary: \u0026quot;List Messages\u0026quot;, // 詳細描述這個 API 的用途。 Description: \u0026quot;Query a specified number of messages and returns an array\u0026quot;, // 業務函數 Function: message.ListMessages, // 對應業務函數的參數信息。用于告知 Nirvana 從請求的那一部分取得數據，然后傳遞給業務函數。 Parameters: []def.Parameter{ { // 參數來源 Source: def.Query, // 參數名稱，作為 key 從 Source 里取值。 // 與業務函數的參數名稱無關。 Name: \u0026quot;count\u0026quot;, // 默認值 Default: 10, // 參數描述 Description: \u0026quot;Number of messages\u0026quot;, }, }, // 對應業務函數的返回結果。用于告知 Nirvana 業務函數返回結果如何放到請求的響應中。 Results: def.DataErrorResults(\u0026quot;A list of messages\u0026quot;),}

而對應業務 API 的形式則是：

type Message struct { ID int `json:\u0026quot;id\u0026quot;` Title string `json:\u0026quot;title\u0026quot;` Content string `json:\u0026quot;content\u0026quot;`}func ListMessages(ctx context.Context, count int) ([]Message, error) { messages := make([]Message, count) for i := 0; i \u0026lt; count; i++ { messages[i].ID = i messages[i].Title = fmt.Sprintf(\u0026quot;Example %d\u0026quot;, i) messages[i].Content = fmt.Sprintf(\u0026quot;Content of example %d\u0026quot;, i) } return messages, nil}

很顯然，業務函數并不關心自身是如何暴露給外部的，實現方法也和其他內部函數沒有差別（這只是一個簡單的例子，更多詳細內容請查閱 Nirvana Definition 文檔）。

在這個例子里，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 的。在框架的大部分包里，你能發現類似以下形式的代碼結構：

var consumers = map[string]Consumer{ definition.MIMENone: \u0026amp;NoneSerializer{}, definition.MIMEText: NewSimpleSerializer(definition.MIMEText), definition.MIMEJSON: \u0026amp;JSONSerializer{}, definition.MIMEXML: \u0026amp;XMLSerializer{}, definition.MIMEOctetStream: NewSimpleSerializer(definition.MIMEOctetStream), definition.MIMEURLEncoded: \u0026amp;URLEncodedConsumer{}, definition.MIMEFormData: \u0026amp;FormDataConsumer{},}// RegisterConsumer register a consumer. A consumer must not handle \u0026quot;*/*\u0026quot;.func RegisterConsumer(c Consumer) error { if c.ContentType() == definition.MIMEAll { return invalidConsumer.Error(definition.MIMEAll) } consumers[c.ContentType()] = c return nil}

在這種結構里，開發者可以自定義每一塊的實現方式，甚至替換框架默認行為。幫助自己最大限度地利用 Nirvana，使它符合業務特定需求。

插件機制

在服務構建工作流中，我們提到了插件機制。下面我們會介紹三個重要插件 metrics、profiling和tracing。

metrics 插件

Prometheus 作為 CNCF 的開源項目，為我們提供了非常適于描述業務指標的格式：Prometheus Metrics。Nirvana 提供的 metrics 插件可以在啟動時默認暴露 /metrics 接口。對此，開發者可以將業務指標注冊到 Prometheus 中，通過這個接口讓 Prometheus 采集。也就是說，Nirvana 不僅能幫助開發者了解業務的運行狀態，也為開發者定位業務問題提供了強有力的幫助。

profiling 插件

Golang 提供了進程級別的 profiling 能力。Nirvana 通過 profiling 插件直接將這個能力注入到框架中。開發者只需要啟用插件即可獲得這些調試和性能測試能力，獲得業務內部執行的狀態信息。

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 直接提供文檔服務（更多信息請查看文檔）。

在 Nirvana 中，生成文檔的方式十分簡單：

$ nirvana api --serve=\u0026quot;:8081\u0026quot;

只需一條命令，API 文檔即可生成，并通過 8081 端口提供服務。之后我們就能通過網頁查看文檔了：

Nirvana 的客戶端生成同樣基于 API Definition ——讀取類型信息，生成客戶端包（目前僅支持生成 Golang 包）。客戶可以直接引用這個包來調用服務，整個客戶端的使用方式與本地調用一致（更多信息請查看文檔）。

下面是一鍵生成客戶端的示例：

$ nirvana client

這個命令會在當前目錄下生成一個 client 目錄，在這個目錄內生成 Golang 客戶端代碼：

type Client struct { rest *rest.Client}// ListMessages returns all messages.func (c *Client) ListMessages(ctx context.Context, count int) (messages []Message, err error) { err = c.rest.Request(\u0026quot;GET\u0026quot;, 200, \u0026quot;/apis/v1/messages\u0026quot;). Query(\u0026quot;count\u0026quot;, count). Data(\u0026amp;messages). Do(ctx) return}

如果您想進一步了解 Nirvana，可以參考才云 Caicloud 云原生 CI/CD 項目 Cyclone。它包含一個 API 組件 Cyclone Server， 基于 Nirvana 對外提供簡單易用的 API。

Nirvana：涅槃

Nirvana，梵語中的涅槃。

一如我們對它的期待：讓 API 從對框架的依賴中涅槃重生。

經過一年多的開源，目前 Nirvana 在基礎 API 服務能力上已經經過內部驗證。由于數據傳輸層和轉換層的復雜度被大大降低，才云 Caicloud 也切實體驗到了這個開源框架帶來的便捷，以及它在加速業務開發上的顯著效果。

未來，Nirvana 將在以下幾方面繼續發力：

• 持續優化擴展文檔和客戶端生成的能力，降低開發者在這兩塊上的心智負擔；
• 持續優化 metrics、profiling、tracing 的能力，并增加新的云原生能力，讓這些能力成為云原生應用的標配；
• 框架模塊化加強，讓 Nirvana 的每一塊代碼皆可定制；
• 優化框架性能，降低反射對服務的影響；
• 讓 Nirvana 成為 Golang 的 CloudNative \u0026amp; SOA 框架。

Nirvana 正致力于成為讓業務無感知的框架。目前，才云 Caicloud 正在這條路上踽踽獨行，我們也真誠地希望將來能有更多開發者愿意加入進來，一起構建 Nirvana，一起建設 Golang 社區，一起擁抱開源的勝利。

也許你的加入，能讓這場涅槃更加炫目！

感謝參與開源本項目的所有開發者！

Nirvana GitHub：https://github.com/caicloud/nirvana

Nirvana 文檔：https://caicloud.github.io/nirvana/zh-hans/

總結

以上是生活随笔為你收集整理的才云开源 Nirvana：Golang REST API框架的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。