第 13 篇：DRF 框架之 API 版本管理

首頁>技術>HelloGitHub2020-07-24 16:34

第 13 篇：DRF 框架之 API 版本管理

API 不可能一成不變，無論是新增或者刪除已有 API，都會對呼叫它的客戶端產生影響。如果對 API 的增刪沒有管理，隨著 API 的增增減減，呼叫它的客戶端就會逐漸陷入迷茫，到底哪個 API 是可用的？為什麼之前可用的 API 又不可用了，新增了哪些 API 可以使用？為了方便 API 的管理，我們引入版本功能。

給 API 打上版本號，在某個特定版本下，原來已有的 API 總是可用的。如果要對 API 做重大變更，可以釋出一個新版本的 API，並及時提醒使用者 API 已變更，敦促使用者遷移到新的 API，這樣可以給客戶端提供一個緩衝過渡期，不至於昨天能用的 API，今天突然報錯了。

django-rest-framework 提供了多個 API 版本輔助類，分別實現不同的 API 版本管理方式。比較實用的有：

AcceptHeaderVersioning

這個類要求客戶端在 HTTP 的 Accept 請求頭加上版本號以表明想請求的 API 版本，例如如下請求：

GET&nbsp;/bookings/&nbsp;HTTP/1.1Host:&nbsp;example.comAccept:&nbsp;application/json;&nbsp;version=1.0

這將請求版本號為 1.0 的介面。

URLPathVersioning

這個類要求客戶端在請求的 url 中指定版本號，一個缺點是你在書寫 URL 模式時，必須包含關鍵字為 version 的模式，例如官網的一個例子：

urlpatterns&nbsp;=&nbsp;[&nbsp;&nbsp;&nbsp;&nbsp;url(&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;r&#39;^(?P&lt;version&gt;(v1|v2))/bookings/$&#39;,&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;bookings_list,&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;name=&#39;bookings-list&#39;&nbsp;&nbsp;&nbsp;&nbsp;),&nbsp;&nbsp;&nbsp;&nbsp;url(&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;r&#39;^(?P&lt;version&gt;(v1|v2))/bookings/(?P&lt;pk&gt;[0-9]+)/$&#39;,&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;bookings_detail,&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;name=&#39;bookings-detail&#39;&nbsp;&nbsp;&nbsp;&nbsp;)]

這樣的話很不方便，因此我們一般不使用。

NamespaceVersioning

和上面提到的 URLPathVersioning 類似，只不過版本號不是在 URL 模式中指定，而是通過 namespace 引數指定（稍後我們將看到它的具體用法）。

當然，django-rest-framework 還提供了其它諸如 HostNameVersioning、QueryParameterVersioning 的版本管理輔助類，可自行檢視文件了解：https://www.django-rest-framework.org/api-guide/versioning/

綜合來看，NamespaceVersioning 模式便於 URL 的設計與管理，因此我們的部落格應用決定採用這種 API 版本管理方式。

為了開啟 api 版本管理，在專案的配置中加入如下配置：

settings/common.pyREST_FRAMEWORK&nbsp;=&nbsp;{&nbsp;&nbsp;&nbsp;&nbsp;&#39;DEFAULT_VERSIONING_CLASS&#39;:&nbsp;&#39;rest_framework.versioning.NamespaceVersioning&#39;,&nbsp;&nbsp;&nbsp;&nbsp;&#39;DEFAULT_VERSION&#39;:&nbsp;&#39;v1&#39;}

以上兩項設定分別全域性指定使用的 API 版本管理方式和客戶端預設版本號的情況下預設請求的 API 版本。儘管這些配置項也可以在單個檢視或者檢視集的範圍內指定，但是，統一的版本管理模式更為可取，因此我們在全域性配置中指定。

接著在註冊的 API 介面前帶上版本號：

blogproject/urls.pyurlpatterns&nbsp;=&nbsp;[&nbsp;&nbsp;&nbsp;&nbsp;#&nbsp;...&nbsp;&nbsp;&nbsp;&nbsp;path(&#34;api/v1/&#34;,&nbsp;include((router.urls,&nbsp;&#34;api&#34;),&nbsp;namespace=&#34;v1&#34;)),]

注意這裡比之前多了個 namespace 引數，引數值為 v1，代表包含的 URL 模式均屬於 v1 這個名稱空間。還有一點需要注意，對於 include 函式，如果指定了 namespace 的值，第一個引數必須是一個元組，形式為：(url_patterns, app_name)，這裡我們將 app_name 指定為 api。

一旦我們開啟了版本管理，所有請求物件 request 就會多出一個屬性 version，其值為使用者請求的版本號（如果沒有指定，就為預設的 DEFAULT_VERSION 的值）。因此，我們可以在請求中針對不同版本的請求執行不同的程式碼邏輯。比如我們的部落格修改文章列表 API，序列化器對返回資料的欄位做了一些改動，釋出在版本 v2，那麼可以根據使用者使用者請求的版本，返回不同的資料，即新增了 API，又保持對原 api 的相容：

if&nbsp;request.version&nbsp;==&nbsp;&#39;v1&#39;:&nbsp;return&nbsp;PostSerializerV1()return&nbsp;PostSerializer

if 分支可以視為一段臨時程式碼，我們可以通過適當的方式提醒使用者，API 已經更改，請儘快遷移到新的版本 v2，並且在未來的某個時間，確認大部分使用者都成功遷移到新版api後移除掉這些程式碼，並將預設版本設為v2，這樣原本的 v1 版本的 API 就徹底被廢棄了。

當然，我們目前的部落格介面還暫時沒有需要修改升級的地方，不過為了測試 API 版本管理的設定是否生效了，我們認為新增一個測試用的檢視集，在裡面做針對不同版本請求的處理，看看不同版本的請求下是否會返回符合預期的不同內容。

首先在 blog/views.py 中加一個簡單的測試檢視集，這個檢視集中有個測試用的介面，介面處理邏輯是根據不同的版本號，返回不同的內容：

class&nbsp;ApiVersionTestViewSet(viewsets.ViewSet):&nbsp;&nbsp;&nbsp;&nbsp;@action(&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;methods=[&#34;GET&#34;],&nbsp;detail=False,&nbsp;url_path=&#34;test&#34;,&nbsp;url_name=&#34;test&#34;,&nbsp;&nbsp;&nbsp;&nbsp;)&nbsp;&nbsp;&nbsp;&nbsp;def&nbsp;test(self,&nbsp;request,&nbsp;*args,&nbsp;**kwargs):&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;if&nbsp;request.version&nbsp;==&nbsp;&#34;v1&#34;:&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;return&nbsp;Response(&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;data={&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&#34;version&#34;:&nbsp;request.version,&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&#34;warning&#34;:&nbsp;&#34;該介面的&nbsp;v1&nbsp;版本已廢棄，請儘快遷移至&nbsp;v2&nbsp;版本&#34;,&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;}&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;)&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;return&nbsp;Response(data={&#34;version&#34;:&nbsp;request.version})

當然檢視集別忘了在 router 中註冊：

blogproject/urls.py#&nbsp;僅用於&nbsp;API&nbsp;版本管理測試router.register(&nbsp;&nbsp;&nbsp;&nbsp;r&#34;api-version&#34;,&nbsp;blog.views.ApiVersionTestViewSet,&nbsp;basename=&#34;api-version&#34;)

這相當於一次介面版本升級，我們再加入 v2 名稱空間的介面：

urlpatterns&nbsp;=&nbsp;[&nbsp;&nbsp;&nbsp;&nbsp;path(&#34;api/v1/&#34;,&nbsp;include((router.urls,&nbsp;&#34;api&#34;),&nbsp;namespace=&#34;v1&#34;)),&nbsp;&nbsp;&nbsp;&nbsp;path(&#34;api/v2/&#34;,&nbsp;include((router.urls,&nbsp;&#34;api&#34;),&nbsp;namespace=&#34;v2&#34;)),]

可以看到，包含的 URL 都是一樣的，只是 namespace 是 v2。

來測試一下效果，啟動開發伺服器，先訪問版本號為 v1 的測試介面，請求返回結果如下，可以看到如期返回了 v1 版本下的內容：

GET&nbsp;/api/v1/api-version/test/HTTP&nbsp;200&nbsp;OKAllow:&nbsp;GET,&nbsp;HEAD,&nbsp;OPTIONSContent-Type:&nbsp;application/jsonVary:&nbsp;Accept{&nbsp;&nbsp;&nbsp;&nbsp;&#34;version&#34;:&nbsp;&#34;v1&#34;,&nbsp;&nbsp;&nbsp;&nbsp;&#34;warning&#34;:&nbsp;&#34;該介面的&nbsp;v1&nbsp;版本已廢棄，請儘快遷移至&nbsp;v2&nbsp;版本&#34;}

再訪問版本號為 v2 的測試介面，返回的內容就是 v2 了。

GET&nbsp;/api/v2/api-version/test/HTTP&nbsp;200&nbsp;OKAllow:&nbsp;GET,&nbsp;HEAD,&nbsp;OPTIONSContent-Type:&nbsp;application/jsonVary:&nbsp;Accept{&nbsp;&nbsp;&nbsp;&nbsp;&#34;version&#34;:&nbsp;&#34;v2&#34;}

對於其它介面，無論 v1，v2 版本的介面均可以訪問，這樣就相當於完成了一次相容的介面升級。

143

Django

JSON

∨ flutter使用 amap_location(高德) 外掛獲取位置資訊「完整記錄」

劇多