Django多版本路由控制实战指南：两种主流方案深度解析-CSDN博客

本文链接：https://blog.csdn.net/weixin_63779518/article/details/147893707

一、版本控制核心需求

1.1 为什么要做版本控制

接口演进：业务迭代时保证旧客户端可用
灰度发布：逐步替换旧版本接口
数据隔离：不同版本使用独立数据结构
统计分析：监控各版本接口使用情况

1.2 方案对比选型

维度	URL路径版本控制	请求头版本控制
可见性	高（版本号在URL中）	低（版本在Header中）
调试便利性	简单（直接访问）	需要工具查看Header
客户端适配	需修改URL	只需修改Header
路由配置	显式路径	隐式逻辑处理
适用场景	公开API、需要明确版本	内部系统、保持URL稳定

二、URL路径版本控制实现

2.1 实现原理

核心思路：在URL路径中嵌入版本标识符，通过路由分发到对应版本的处理模块

2.2 具体实现步骤

步骤1：项目结构规划

myproject/
├── api/
│   ├── v1/
│   │   ├── urls.py
│   │   └── views.py
│   └── v2/
│       ├── urls.py
│       └── views.py
└── config/
    └── urls.py

步骤2：主路由配置

# config/urls.py
from django.urls import include, path

urlpatterns = [
    path('api/v1/', include('api.v1.urls')),
    path('api/v2/', include('api.v2.urls')),
]

步骤3：版本子路由定义

# api/v1/urls.py
from django.urls import path
from . import views

urlpatterns = [
    path('users/', views.UserList.as_view()),
    path('users/<int:pk>/', views.UserDetail.as_view()),
]

# api/v2/urls.py
from django.urls import path
from . import views

urlpatterns = [
    path('users/', views.UserListV2.as_view()),
    path('users/<uuid:pk>/', views.UserDetailV2.as_view()),
]

步骤4：视图版本差异处理

# api/v1/views.py
from rest_framework.generics import ListAPIView

class UserList(ListAPIView):
    """v1版本返回基础字段"""
    queryset = User.objects.all()
    serializer_class = UserSerializerV1

# api/v2/views.py
class UserListV2(ListAPIView):
    """v2版本增加扩展字段"""
    queryset = User.objects.all()
    serializer_class = UserSerializerV2
    pagination_class = PageNumberPagination

步骤5：版本回退处理

# config/urls.py
from django.http import HttpResponseRedirect

urlpatterns = [
    # ...其他路由...
    path('api/users/', lambda r: HttpResponseRedirect('/api/v2/users/'))
]

三、请求头版本控制实现

3.1 实现原理

核心思路：通过中间件解析请求头中的版本信息，动态路由到对应处理逻辑

3.2 具体实现步骤

步骤1：自定义版本解析器

# api/versioning.py
from rest_framework.versioning import BaseVersioning

class HeaderVersioning(BaseVersioning):
    """
    从X-API-Version头获取版本号
    示例请求头：X-API-Version: 1.0
    """
    default_version = 'v2'
    allowed_versions = ['v1', 'v2']

    def determine_version(self, request, *args, **kwargs):
        version = request.headers.get('X-API-Version', self.default_version)
        if version not in self.allowed_versions:
            raise exceptions.NotFound("不支持的API版本")
        return version

步骤2：配置版本控制类

# settings.py
REST_FRAMEWORK = {
    'DEFAULT_VERSIONING_CLASS': 'api.versioning.HeaderVersioning',
    'DEFAULT_VERSION': 'v2',
    'ALLOWED_VERSIONS': ['v1', 'v2']
}

步骤3：视图动态路由

# api/views.py
from rest_framework.views import APIView
from .v1.serializers import UserSerializerV1
from .v2.serializers import UserSerializerV2

class UserListView(APIView):
    def get_serializer_class(self):
        return {
            'v1': UserSerializerV1,
            'v2': UserSerializerV2
        }[self.request.version]

    def get(self, request):
        queryset = User.objects.all()
        serializer = self.get_serializer_class()(queryset, many=True)
        return Response(serializer.data)

步骤4：中间件处理（可选）

# api/middleware.py
class VersionHeaderMiddleware:
    def __init__(self, get_response):
        self.get_response = get_response

    def __call__(self, request):
        response = self.get_response(request)
        # 在响应头中返回当前版本
        response['X-API-Version'] = getattr(request, 'version', 'v2')
        return response

四、混合方案实现

4.1 方案设计

# config/urls.py
urlpatterns = [
    path('api/v1/', include('api.v1.urls')),  # 显式路径版本
    path('api/', include('api.latest.urls')), # 隐式头控制版本
]

4.2 优先级处理逻辑

class HybridVersioning(BaseVersioning):
    def determine_version(self, request):
        # 优先检查路径版本
        if 'v1' in request.path:
            return 'v1'
        # 其次检查请求头
        return request.headers.get('X-API-Version', self.default_version)

五、生产环境最佳实践

5.1 版本生命周期管理

# api/versioning.py
class ExpirationVersioning(HeaderVersioning):
    version_expires = {
        'v1': '2024-01-01',
        'v2': '2025-01-01'
    }

    def determine_version(self, request):
        version = super().determine_version(request)
        expire_date = self.version_expires[version]
        if timezone.now().date() > datetime.strptime(expire_date, "%Y-%m-%d").date():
            warnings.warn(f"API版本{version}已过期，请尽快升级")
        return version

5.2 文档集成方案

# api/schemas.py
class VersionedSchemaGenerator(OpenAPISchemaGenerator):
    def get_schema(self, request=None, public=False):
        schema = super().get_schema(request, public)
        # 添加版本说明
        schema.info.description += "\n当前活动版本：v2"
        return schema

六、常见问题解决方案

6.1 版本兼容性处理

# 数据迁移示例
class UserSerializerV2(UserSerializerV1):
    def to_internal_value(self, data):
        # v2版本兼容v1字段
        data = super().to_internal_value(data)
        if self.context['request'].version == 'v1':
            data['new_field'] = default_value
        return data

6.2 弃用版本处理

# 响应头添加警告
response = self.get_response(request)
if request.version == 'v1':
    response.headers['Deprecation'] = 'true'
    response.headers['Sunset'] = 'Wed, 01 Jan 2025 00:00:00 GMT'
return response