Django 3.1 版本发行说明

异步视图和中间件支持

Django 现在支持完全异步的请求路径，包括：

• 异步视图
• 异步中间件
• 异步测试和测试客户端

要开始使用异步视图，你需要使用 async def 来声明一个视图：

async def my_view(request):
    await asyncio.sleep(0.5)
    return HttpResponse('Hello, async world!')

无论你是在 WSGI 或 ASGI 模式下运行，都支持所有的异步功能。但是，在 WSGI 模式下使用 async 代码会有性能上的惩罚。你可以在 异步支持 文档中阅读更多的具体内容。

你可以自由地混合异步和同步视图、中间件和测试，只要你愿意。Django 会确保你最终使用正确的执行上下文。我们希望大多数项目会保持大部分视图的同步，只有少数视图在异步模式下运行，但这完全是你的选择。

Django 的 ORM、缓存层和其他做长期网络调用的代码还不支持异步访问。我们希望在即将发布的版本中增加对它们的支持。但是，异步视图是很理想的，如果你在视图里面做了大量的 API 或 HTTP 调用，你现在可以原生地将所有这些 HTTP 调用并行进行，以大大加快你的视图的执行速度。

异步支持应该是完全向后兼容的，我们已经尝试确保它不会对你现有的同步代码造成速度上的倒退。它应该不会对任何现有的 Django 项目产生明显的影响。

JSONField 适用于所有支持的数据库后端。

Django 现在包含 models.JSONField 和 forms.JSONField，可以在所有支持的数据库后端使用。这两个字段都支持使用自定义 JSON 编码器和解码器。模型字段支持自省、查找和变换，这些功能以前只有 PostgreSQL 才有：

from django.db import models

class ContactInfo(models.Model):
    data = models.JSONField()

ContactInfo.objects.create(data={
    'name': 'John',
    'cities': ['London', 'Cambridge'],
    'pets': {'dogs': ['Rufus', 'Meg']},
})
ContactInfo.objects.filter(
    data__name='John',
    data__pets__has_key='dogs',
    data__cities__contains='London',
).delete()

如果你的项目使用了 django.contrib.postgres.fields.JSONField，加上相关的表单字段和变换，你应该调整使用新的字段，并生成和应用数据库迁移。目前，旧的字段和变换体作为新字段的引用留存下来，并且 从这个版本开始取消。

次要特性

数据库后端 API

本节介绍了第三方数据库后端可能需要的更改。

• DatabaseOperations.fetch_returned_insert_columns() 现在需要一个额外的 returning_params 参数。
• connection.timezone 属性现在默认为 'UTC，或者当 USE_TZ 为 True 时，支持时区的数据库上的 TIME_ZONE。此前，在支持时区的数据库上是 None。
• connection._nodb_connection 属性改为 connection._nodb_cursor() 方法，现在返回一个产生游标的上下文管理器，并在退出 with 语句后自动关闭游标和连接。
• DatabaseClient.runshell() 现在需要一个额外的 parameters 参数，作为传递给命令行客户端的额外参数列表。
• DatabaseOperations.sql_flush() 的 sequences 位置参数被只用关键字的布尔参数 reset_sequences 取代。如果 True，截断表的序列将被重置。
• DatabaseOperations.sql_flush() 的 allow_cascade 参数现在是一个纯关键字的参数。
• DatabaseOperations.execute_sql_flush() 的 using 位置参数被删除。该方法现在使用被调用实例的数据库。
• 第三方数据库后端必须实现对 JSONField 的支持，或者将 DatabaseFeatures.supports_json_field 设置为 False。如果不支持存储基元，则设置 DatabaseFeatures.supports_primitives_in_json_field 为 False。如果 JSON 的数据类型为真，则设置 DatabaseFeatures.has_native_json_field 为 True。如果不支持 jsonfield.contains 和 jsonfield.contains_by，则将 DatabaseFeatures.support_json_field_contains 设置为 False。
• 第三方数据库后端必须实现对 JSONField 的自省，或者将 can_introspect_json_field 设置为 False。

丢弃了对 MariaDB 10.1 的支持

对 MariaDB 10.1 的上游支持在 2020 年 10 月结束。Django 3.1 支持 MariaDB 10.2 及以上版本。

contrib.admin 浏览器支持

管理不再支持传统的 Internet Explorer 浏览器。关于支持的浏览器，请参见 管理常见问题。

AbstractUser.first_name 的 max_length 增加到 150

包含了 django.contrib.auth.models.User.first_name 的迁移。如果你有一个继承自 AbstractUser 的自定义用户模型，你将需要为你的用户模型生成并应用数据库迁移。

如果你想保留 first name 的 30 个字符限制，请使用自定义表单：

from django import forms
from django.contrib.auth.forms import UserChangeForm

class MyUserChangeForm(UserChangeForm):
    first_name = forms.CharField(max_length=30, required=False)

如果你想在管理中编辑用户时保留这个限制，请将 UserAdmin.form 设置为使用这个表单：

from django.contrib.auth.admin import UserAdmin
from django.contrib.auth.models import User

class MyUserAdmin(UserAdmin):
    form = MyUserChangeForm

admin.site.unregister(User)
admin.site.register(User, MyUserAdmin)

杂项

• cache 使用的缓存密钥和 make_template_fragment_key() 生成的缓存密钥与旧版本 Django 生成的密钥不同。升级到 Django 3.1 后，第一次请求任何之前缓存的模板片段都会被缓存错过。
• 从 set_language() 视图中返回重定向回退或 204 HTTP 响应背后的逻辑现在是基于 Accept HTTP 头而不是 X-Requested-With HTTP 头的存在。
• django.db.models.query、django.db.models.sql 和 django.db.models.sql.datastructures 中的 django.core.exceptions.EmptyResultSet 的兼容性导入被移除。
• 删除了 django.db.models.field 中 django.core.exceptions.FieldDoesNotExist 的兼容性导入。
• 删除了 django.forms.utils.pretty_name() 和 django.forms.boundfield.BoundField 的兼容性导入。
• django.template.base 中的 Context、ContextPopException 和 RequestContext 的兼容性导入被移除。
• 删除了 django.contrib.admin.helpers.ACTION_CHECKBOX_NAME 中的兼容性导入。
• 设置为相对路径的 STATIC_URL 和 MEDIA_URL 配置现在以服务器提供的 SCRIPT_NAME 的值为前缀（如果没有设置，则为 /）。这一变化不应影响设置为有效 URL 或绝对路径的配置。
• ConditionalGetMiddleware 不再为空 content 的响应添加 ETag 头。
• django.utils.disturators.classproperty() 装饰器被公开并移到 django.utils.functional.classproperty()。
• floatform 模板过滤器现在对四舍五入为零的负数输出（正）``0```。
• Meta.ordering 和 Meta.unique_together <django.db.models.Options.unique_together>` 模块中模型的选项，以前是元组，现在是列表。
• 管理日历部件现在根据开放组规范处理两位数的年份，即 69 和 99 之间的值被映射到上一个世纪，0 和 68 之间的值被映射到当前世纪。
• 从 DATETIME_INPUT_FORMATS 的默认列表中删除了仅限日期的格式。
• 当初始数据存在时，FileInput 小部件不再使用 required HTML 属性进行渲染。
• 删除了未记录的 django.views.debug.ExceptionReporterFilter 类。根据 自定义错误报告 文档，与 DEFAULT_EXCEPTION_REPORTER_FILTER 一起使用的类需要继承 django.views.debug.SafeExceptionReporterFilter。
• cache_page() 装饰器设置的缓存超时现在优先于 Cache-Control 头的 max-age 指令。
• 在 ForeignKey.to_field 参数中提供一个非本地的远程字段，现在会引发 FieldError。
• SECURE_REFERRER_POLICY 现在默认为 'same-origin'。更多细节请参见 新变化 安全章节。
• check 管理命令现在只对使用 check --database 选项指定的数据库别名运行 database 系统检查。
• migrate 管理命令现在只运行 database 系统检查要迁移的数据库。
• 管理 CSS 类 row1 和 row2 被删除，取而代之的是 :nth-child(odd) 和 :nth-child(even) 伪类。
• make_password() 函数现在要求其参数为字符串或字节。其他类型的参数应该显式地转换为其中之一。
• 删除了 AsKML 函数中未记录的 version 参数。
• JSON 和 YAML 序列化器，由 dumpdata 使用，现在默认使用 Unicode 转储所有数据。如果你需要以前的行为，传递 ensure_ascii=True 给 JSON 序列化器，或者 allow_unicode=False 给 YAML 序列化器。
• 自动重新加载器不再监控内置 Django 翻译文件的变化。
• mysqlclient 的最低支持版本从 1.3.13 增加到 1.4.0。
• 未记录的 django.contrib.postgres.forms.InvalidJSONInput 和 django.contrib.postgres.forms.JSONString 被移至 django.forms.field。
• 删除了未记录的 django.contrib.postgres.field.jsonb.JsonAdapter 类。
• {% localize off %} 标签和 unlocalize 过滤器不再遵守 DECIMAL_SEPARATOR 配置。
• asgiref 的最低支持版本从 3.2 增加到 3.2.10。
• Media 类现在不使用 type 属性来渲染 <script> 标签，以遵循 WHATWG 建议 。
• ModelChoiceIterator，由 ModelChoiceField 和 ModelMultipleChoiceField 使用，现在产生 2 个包含 ModelChoiceIteratorValue 实例的选择，作为每个选择的第一个 value 元素。在大多数情况下，这个代理是透明的，但如果你需要 field 值本身，请使用 ModelChoiceIteratorValue.value 属性代替。

杂项

• PASSWORD_RESET_TIMEOUT_DAYS 配置已被取消，改为 PASSWORD_RESET_TIMEOUT。

• 未记录的 isnull 查找使用非布尔值作为右侧的用法已被废弃，请使用 True 或 False 代替。

• 勉强记录的 django.db.models.query_utils.InvalidQuery 异常类被废弃，取而代之的是 FieldDoesNotExist 和 FieldError。

• django-admin.py 的入口点已被废弃，改为 django-admin。

• HttpRequest.is_ajax() 方法已被废弃，因为它依赖于 jQuery 特定的方式来表示 AJAX 调用，而当前的用法倾向于使用 JavaScript Fetch API 。根据你的用例，你可以写你自己的 AJAX 检测方法，或者使用新的 HttpRequest.accepts() 方法，如果你的代码依赖于客户端 Accept HTTP 头。

  如果你正在编写自己的 AJAX 检测方法，request.is_ajax() 可以完全复制为 request.headers.get('x-requested-with') == 'XMLHttpRequest'。

• 传递 None 作为 django.utils.deprecation.MiddlewareMixin.__init__() 的第一个参数是过时的。

• CookieStorage 使用的 cookie 值的编码格式与旧版本 Django 生成的格式不同。在 Django 4.0 之前，仍然支持旧的格式。

• 会话的编码格式与旧版 Django 生成的格式不同。在 Django 4.0 之前，仍然支持旧的格式。

• Signal 的纯文档化 providing_args 参数已被废弃。如果你依赖这个参数作为文档，你可以将文本移到代码注释或 docstring 中。

• 没有 length 参数的情况下调用 django.utils.crypto.get_random_string() 已被废弃。

• ModelMultipleChoiceField 的 list 信息已被弃用，改为 invalid_list。

• 向 QuerySet.order_by() 传递原始列别名已经被废弃。通过事先在 RawSQL 中传递别名，可以达到同样的效果。

• NullBooleanField 模型字段被废弃，改为 BooleanField(null=True)。

• django.conf.urls.url() 的 django.urls.re_path() 别名已被废弃。

• {% ifequal %} 和 {% ifnotequal %} 模板标签已被废弃，改为 {% if %}。{% if %} 涵盖了所有的用例，但如果你需要继续使用这些标签，可以将它们从 Django 中提取到一个模块中，并作为一个内置标签包含在 'buildins' 选项中的 OPTIONS 中。

• DEFAULT_HASHING_ALGORITHM 过渡性配置已废弃。