如何在Python Django REST Framework中利用Versioning实现API版本管理？-Python教程-PHP中文网

drf的versioning需显式配置，urlpathversioning依赖路径捕获组命名（必须为version）、正则与version_param对齐，queryparameterversioning则依赖version_param参数名匹配，allowed_versions为硬性白名单，request.version是字符串需手动切换逻辑。

如何在python django rest framework中利用versioning实现api版本管理？

直接上结论：DRF 的 versioning 不是“开箱即用”的功能，必须显式配置类、声明允许版本、并在 URL 或请求中携带版本标识，否则 request.version 永远是 None。

URLPathVersioning 配置和路由写法容易错

这是最常用也最容易出错的方案。关键不是“加个 v1 就行”，而是路径捕获组命名、正则表达式、VERSION_PARAM 三者必须对齐。

settings.py 中 DEFAULT_VERSIONING_CLASS 必须设为 'rest_framework.versioning.URLPathVersioning'，且 VERSION_PARAM 默认是 'version' —— 这个值只在部分方案（如 QueryParameterVersioning）里真正参与解析，但在 URLPathVersioning 中它**不起作用**，实际靠 URL 捕获组传入
urls.py 必须用 path('api/v<version>/users/', ...)</version> 或正则 url(r'^api/v(?P<version>[v1|v2]+)/users/$', ...)</version>；注意捕获组名必须是 version（不能是 v 或 ver），否则 DRF 内部无法绑定到 request.version
如果用了 include()，比如 path('api/v<version>/', include('app.urls'))</version>，那子路由里不能再重复写 v<version></version>，否则会解析失败或返回 404

QueryParameterVersioning 的参数名必须匹配 VERSION_PARAM

当你想用 /api/users/?version=v2 这种方式时，VERSION_PARAM 就变成关键开关。

Python Code Tester

代码功能测试skill，根据用户需求搜索代码、生成测试用例、执行测试并修复问题

下载

settings.py 中设置 'DEFAULT_VERSIONING_CLASS': 'rest_framework.versioning.QueryParameterVersioning' 后，VERSION_PARAM 值（默认 'version'）会直接用于 request.query_params.get(VERSION_PARAM)
如果改成 'api_version'，那请求就必须是 /api/users/?api_version=v2，否则 request.version 仍为 None
ALLOWED_VERSIONS 是硬性白名单，哪怕 URL 里写了 v3，只要没列在 ALLOWED_VERSIONS 里，DRF 就会返回 406 Not Acceptable，而不是静默降级

视图中根据 version 切换逻辑的实际写法

request.version 是字符串（如 'v1' 或 '1'），不是数字，也不是对象，直接比较即可，但要注意格式一致性。

序列化器切换推荐写在 get_serializer_class() 里：
if self.request.version == 'v1': return UserSerializerV1 —— 注意字符串值要和 ALLOWED_VERSIONS 里声明的一致
数据过滤可放在 get_queryset()：
if self.request.version == 'v2': return queryset.filter(is_active=True)
不要在视图函数里用 try/except 捕获 request.version 为 None，而应确保全局或局部 versioning_class 已设置；未启用 versioning 时它就是 None，不是异常

反向 URL 生成必须传 request 参数

用 reverse() 生成带版本的链接时，漏掉 request=request 会导致版本丢失，生成的 URL 没有 v1/ 或 ?version=v1。

正确写法：reverse('user-list', request=request)
错误写法：reverse('user-list') → 返回 /api/users/，不带版本
序列化器中用 HyperlinkedModelSerializer 时，必须传 context={'request': request}，否则所有 url 字段都不含版本信息

最常被忽略的是：DRF 的 versioning 不做自动迁移或兼容层，v1 和 v2 视图完全隔离，连 URL resolver 都是独立的——你得自己保证旧版接口不删、新版字段不破坏旧契约，版本控制只是开关，不是魔法。