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 /bookings/ HTTP/1.1
Host: example.com
Accept: application/json; version=1.0
這將請求版本號為 1.0 的接口。
URLPathVersioning
這個類要求客戶端在請求的 url 中指定版本號，一個缺點是你在書寫 URL 模式時，必須包含關鍵字為 version 的模式，例如官網的一個例子：
urlpatterns = [
url(
r'^(?P<version>(v1|v2))/bookings/$',
bookings_list,
name='bookings-list'
),
url(
r'^(?P<version>(v1|v2))/bookings/(?P<pk>[0-9]+)/$',
bookings_detail,
name='bookings-detail'
)
]
這樣的話很不方便，因此我們一般不使用。
NamespaceVersioning
和上面提到的 URLPathVersioning 類似，只不過版本號不是在 URL 模式中指定，而是通過 namespace 參數指定 （稍后我們將看到它的具體用法）。
當然，django-rest-framework 還提供了其它諸如 HostNameVersioning、QueryParameterVersioning 的版本管理輔助類，可自行查看文檔了解：https://www.django-rest-framework.org/api-guide/versioning/
綜合來看，NamespaceVersioning 模式便於 URL 的設計與管理，因此我們的博客應用決定采用這種 API 版本管理方式。
為了開啟 api 版本管理，在項目的配置中加入如下配置：
settings/common.py
REST_FRAMEWORK = {
'DEFAULT_VERSIONING_CLASS': 'rest_framework.versioning.NamespaceVersioning',
'DEFAULT_VERSION': 'v1'
}
以上兩項設置分別全局指定使用的 API 版本管理方式和客戶端缺省版本號的情況下默認請求的 API 版本。盡管這些配置項也可以在單個視圖或者視圖集的范圍內指定，但是，統一的版本管理模式更為可取，因此我們在全局配置中指定。
接着在注冊的 API 接口前帶上版本號：
blogproject/urls.py
urlpatterns = [
# ...
path("api/v1/", include((router.urls, "api"), namespace="v1")),
]
注意這里比之前多了個 namespace 參數，參數值為 v1，代表包含的 URL 模式均屬於 v1 這個命名空間。還有一點需要注意，對於 include 函數，如果指定了 namespace 的值，第一個參數必須是一個元組，形式為：(url_patterns, app_name)，這里我們將 app_name 指定為 api。
一旦我們開啟了版本管理，所有請求對象 request 就會多出一個屬性 version，其值為用戶請求的版本號（如果沒有指定，就為默認的 DEFAULT_VERSION 的值）。因此，我們可以在請求中針對不同版本的請求執行不同的代碼邏輯。比如我們的博客修改文章列表 API，序列化器對返回數據的字段做了一些改動，發布在版本 v2，那么可以根據用戶用戶請求的版本，返回不同的數據，即新增了 API，又保持對原 api 的兼容：
if request.version == 'v1':
return PostSerializerV1()
return PostSerializer
if 分支可以視為一段臨時代碼，我們可以通過適當的方式提醒用戶，API 已經更改，請盡快遷移到新的版本 v2，並且在未來的某個時間，確認大部分用戶都成功遷移到新版api后移除掉這些代碼，並將默認版本設為v2，這樣原本的 v1 版本的 API 就徹底被廢棄了。
當然，我們目前的博客接口還暫時沒有需要修改升級的地方，不過為了測試 API 版本管理的設置是否生效了，我們認為添加一個測試用的視圖集，在里面做針對不同版本請求的處理，看看不同版本的請求下是否會返回符合預期的不同內容。
首先在 blog/views.py 中加一個簡單的測試視圖集，這個視圖集中有個測試用的接口，接口處理邏輯是根據不同的版本號，返回不同的內容：
class ApiVersionTestViewSet(viewsets.ViewSet):
@action(
methods=["GET"], detail=False, url_path="test", url_name="test",
)
def test(self, request, *args, **kwargs):
if request.version == "v1":
return Response(
data={
"version": request.version,
"warning": "該接口的 v1 版本已廢棄，請盡快遷移至 v2 版本",
}
)
return Response(data={"version": request.version})
當然視圖集別忘了在 router 中注冊：
blogproject/urls.py
# 僅用於 API 版本管理測試
router.register(
r"api-version", blog.views.ApiVersionTestViewSet, basename="api-version"
)
這相當於一次接口版本升級，我們再加入 v2 命名空間的接口：
urlpatterns = [
path("api/v1/", include((router.urls, "api"), namespace="v1")),
path("api/v2/", include((router.urls, "api"), namespace="v2")),
]
可以看到，包含的 URL 都是一樣的，只是 namespace 是 v2。
來測試一下效果，啟動開發服務器，先訪問版本號為 v1 的測試接口，請求返回結果如下，可以看到如期返回了 v1 版本下的內容：
GET /api/v1/api-version/test/
HTTP 200 OK
Allow: GET, HEAD, OPTIONS
Content-Type: application/json
Vary: Accept
{
"version": "v1",
"warning": "該接口的 v1 版本已廢棄，請盡快遷移至 v2 版本"
}
再訪問版本號為 v2 的測試接口，返回的內容就是 v2 了。
GET /api/v2/api-version/test/
HTTP 200 OK
Allow: GET, HEAD, OPTIONS
Content-Type: application/json
Vary: Accept
{
"version": "v2"
}
對於其它接口，無論 v1，v2 版本的接口均可以訪問，這樣就相當於完成了一次兼容的接口升級。
關注公眾號加入我們