罗罗编程学习记录
本页内容 展开查看

04.7.17.3 版本、异常、性能与测试

所属:全栈开发面试题库 / 04 后端语言与运行时 / 04.7 Python / 04.7.17 Django REST Framework

覆盖范围

  • APIException 与 exception_handler 定制、统一错误结构与错误码
  • ValidationError 字段级细节、401/403/404 语义与 raise_exception
  • 版本控制策略(URLPath/Header/QueryParameter/Namespace)与弃用兼容
  • select_related/prefetch_related 配合、序列化开销、N+1 复现与定位
  • 序列化器与 Pydantic 的取舍、不用 DRF 的场景
  • APIClient/APITestCase、force_authenticate、fixture 与工厂
  • drf-spectacular 与 OpenAPI 契约、文件上传解析
  • 常见坑:context 缺失、source='*'、partial=True 误用

04.7.17.3-001 DRF 异常处理整体流程是怎样的?

一句话结论

视图 dispatch 包裹动作调用,捕获异常后交给 handle_exception(exc);后者调用配置的 exception_handler(默认 rest_framework.views.exception_handler)把 APIException 及其子类转成 Response。处理器返回 None 表示非 DRF 异常,异常重新抛出交给 Django 兜底 500。全局处理器在 EXCEPTION_HANDLER 配置,可统一记录日志、补充错误码与请求 ID。

概念解释

  • 异常链保证 DRF 异常输出 JSON 结构,而不是 Django 默认错误页。
  • 业务代码抛 APIException 子类即可接入统一处理,不需要每个视图 try/except。

原理流程

  1. dispatch 内 try: response = handler(request, ...) except Exception as exc。
  2. handle_exception 调 exception_handler(exc, context)。
  3. 处理器生成响应返回;返回 None 时重新抛给 Django 中间件。

代码或图示

from rest_framework.views import exception_handler

def custom_exception_handler(exc, context):
    response = exception_handler(exc, context)
    if response is not None:
        response.data["code"] = response.data.get("code", "internal_error")
    return response

常见误区

  • 在动作里 try/except Exception 后返回 200 或裸字典,绕过统一错误结构;异常应上抛由处理器归一。
  • 自定义处理器把非 DRF 异常也包装成 200/400,泄露服务端堆栈信息;未处理异常应保持上抛。

追问

  • 默认处理器能处理哪些异常?答:APIException 子类与 Django Http404、PermissionDenied 等映射异常(待确认:具体映射清单以 DRF 3.1x 源码为准)。
  • 异常处理器能改状态码吗?答:能,修改 response.status_code 或在自定义异常类上声明。

04.7.17.3-002 APIException 基类有哪些核心属性?

一句话结论

APIException 是 DRF 异常基类,核心属性:status_code(HTTP 状态码,默认 500)、default_detail(默认可读消息)、default_code(默认错误码标识)。构造时可传 detail 覆盖消息、code 覆盖错误码;detail 支持字符串、列表或字段字典,最终经 get_full_details() 输出结构化错误。自定义业务异常继承它并声明状态码与默认消息。

概念解释

  • 错误码是机器可读标识,detail 是给人看的消息,两者分离便于前端按码分支。
  • 子类只需覆盖类属性,不必重写抛异常逻辑。

原理流程

  1. 异常被实例化,detail/code 写入实例。
  2. 处理器读取 status_code 与 get_full_details()。
  3. 组装响应体:消息、错误码、字段细节。

代码或图示

from rest_framework.exceptions import APIException

class InsufficientBalance(APIException):
    status_code = 400
    default_detail = "余额不足"
    default_code = "insufficient_balance"

常见误区

  • 自定义异常只写消息不设 code,前端无法按稳定错误码分支,只能匹配文案;错误码必须固定。
  • 把 HTTP 500 用于业务可预期错误(如余额不足);业务失败应使用 4xx 状态码,500 留给未预期服务端错误。

追问

  • get_full_details() 返回什么?答:含 message 与 code 的字典,字段级错误还带字段细节结构。
  • 异常消息能传多语言吗?答:default_detail 可对接 Django 翻译,按请求语言输出。

04.7.17.3-003 ValidationError 的字段级细节是什么结构?

一句话结论

ValidationError 携带的 detail 聚合为字段映射:键是字段名,值是错误字符串列表;对象级错误固定在 non_field_errors 键下;嵌套序列化器错误是同构嵌套字典,many=True 时为「索引 → 字段错误」列表。抛异常时传字符串归 non_field_errors,传字典则挂到指定字段。detail 每条含消息与可选错误码。

概念解释

  • 错误结构与请求体结构同构,前端按路径定位表单项。
  • 400 响应默认由 JSON 渲染器输出该映射。

原理流程

  1. 字段校验失败抛 ValidationError(detail, code=...)。
  2. run_validation 捕获并合并进字段映射。
  3. 嵌套子序列化器错误挂在嵌套键,列表按索引聚合。

代码或图示

raise serializers.ValidationError({
    "end": "结束时间必须晚于开始时间",
    "password": ["长度不足 8 位", "缺少数字"],
})

常见误区

  • 抛字符串消息却希望挂到具体字段,结果全部进 non_field_errors;字段级错误必须传字典。
  • 错误码只取消息字符串丢弃 code,前端丢失机器可读标识;统一错误结构应保留码。

追问

  • non_field_errors 能改名吗?答:可通过序列化器 NON_FIELD_ERRORS_KEY 配置键名(待确认:配置项以版本为准)。
  • 批量提交部分失败如何定位?答:ListSerializer 按列表索引聚合错误,前端按序号定位失败条目。

04.7.17.3-004 如何设计统一错误响应结构与错误码?

一句话结论

统一结构建议含:code(机器可读稳定错误码,如 auth.token_expired)、message(可读消息)、details(字段级细节或附加上下文)、request_id(链路追踪标识)。错误码分层命名(模块.场景),HTTP 状态码表达大类,业务码表达细分原因。全局异常处理器负责装配公共字段,序列化器校验错误映射进 details,日志记录原始异常与请求 ID。

概念解释

  • HTTP 状态码粗分类,业务错误码细定位;两者不互相替代。
  • 结构前后端约定后纳入 OpenAPI 文档,避免响应形态漂移。

原理流程

  1. 异常处理器接收 exc 与上下文(含请求、视图)。
  2. 提取状态码、消息、错误码与字段细节。
  3. 补充请求 ID、时间戳等公共字段后返回响应。

代码或图示

{
  "code": "order.insufficient_balance",
  "message": "余额不足",
  "details": {"amount": ["金额超出余额"]},
  "request_id": "7c2f..."
}

常见误区

  • 错误码用 HTTP 状态码充当,细分错误无法区分;业务码必须独立分层。
  • 错误结构在不同接口各写一套,前端解析逻辑分叉;统一在处理器层收口。

追问

  • 字段级错误放哪个字段?答:details 下按字段名映射错误列表,与 ValidationError 结构对齐。
  • 未预期异常对外暴露什么?答:只返回通用 500 消息与请求 ID,堆栈进日志,不回传前端。

04.7.17.3-005 自定义异常类如何注册到全局处理器?

一句话结论

先继承 APIException 声明 status_code/default_detail/default_code;再编写处理器函数 handler(exc, context),在 settings.py 的 REST_FRAMEWORK.EXCEPTION_HANDLER 指向该函数路径。处理器内可先调默认处理器拿到响应,再补充业务字段;自定义异常在动作或序列化器中直接 raise。

概念解释

  • 异常类定义「是什么错误」,处理器定义「怎么输出」,两者分工。
  • 全局处理器对所有 DRF 视图生效,无需逐视图配置。

原理流程

  1. 定义业务异常类并声明属性。
  2. 编写处理器:调默认处理器、补充公共字段、记录日志。
  3. settings 注册处理器路径,业务代码抛异常接入链。

代码或图示

# exceptions.py
class QuotaExceeded(APIException):
    status_code = 429
    default_detail = "配额已用完"
    default_code = "quota_exceeded"

def handler(exc, context):
    response = exception_handler(exc, context)
    if response is not None:
        response.data.setdefault("request_id", get_request_id(context))
    return response

常见误区

  • 处理器里对每种异常 isinstance 硬编码分支,新增异常要改处理器;异常自身携带码与消息,处理器只做通用装配。
  • 注册路径写错(模块/函数名),启动或请求时导入失败;注册后跑一次冒烟请求验证。

追问

  • 处理器能拿到当前用户吗?答:通过 context["request"].user 读取,上下文由视图传入。
  • 自定义异常需要在视图捕获吗?答:不需要,上抛后由全局处理器统一处理。

04.7.17.3-006 401/403/404 语义与 raise_exception 如何使用?

一句话结论

401 未认证(缺有效凭证),403 已认证但无权限,404 资源不存在;raise_exception=True 用在 serializer.is_valid(raise_exception=True),校验失败直接抛 ValidationError 由异常处理转 400,避免视图内手写判断。NotFound/PermissionDenied/AuthenticationFailed 分别对应 404/403/401,业务代码按语义选择抛出类型。

概念解释

  • 状态码语义错误会误导客户端重试与提示;401 跳登录,403 提示无权限,404 提示不存在。
  • raise_exception 是序列化器校验的快捷短路方式。

原理流程

  1. 动作内 is_valid(raise_exception=True),失败抛异常。
  2. 异常经处理器映射到对应状态码。
  3. 权限/对象不存在场景抛对应 DRF 异常。

代码或图示

serializer = ArticleSerializer(data=request.data)
serializer.is_valid(raise_exception=True)
serializer.save()

if not obj:
    raise NotFound("文章不存在")

常见误区

  • 无权限也抛 401,客户端反复跳转登录;已识别身份的拒绝必须用 403。
  • 资源不存在抛 403 隐藏存在性;公开资源 404,私有资源可按安全策略统一 404 防探测。

追问

  • raise_exception 与手动 if not serializer.is_valid(): return Response(...) 区别?答:前者走统一异常结构,后者手写响应,结构易分叉。
  • 404 由哪个异常触发?答:NotFound,也可由 Django Http404/对象不存在映射。

04.7.17.3-007 常用 DRF 异常类分别对应什么状态码?

一句话结论

AuthenticationFailed/NotAuthenticated → 401;PermissionDenied → 403;NotFound → 404;ValidationError → 400;MethodNotAllowed → 405;NotAcceptable → 406;Throttled → 429;UnsupportedMediaType → 415;ParseError → 400。APIException 基类默认 500,子类覆盖 status_code 表达具体语义。

概念解释

  • 异常类与 HTTP 状态码一一对应,选择时先定语义再选类。
  • 部分异常同时携带 detail 与 code,处理器可读取。

原理流程

  1. 业务代码按场景抛对应异常。
  2. 处理器读取异常 status_code 与 detail。
  3. 生成对应状态码的 JSON 响应。

代码或图示

from rest_framework.exceptions import (
    NotFound, PermissionDenied, ValidationError, Throttled,
)

if not order:
    raise NotFound("订单不存在")
if order.owner != request.user:
    raise PermissionDenied("只能操作本人订单")

常见误区

  • 用 ValidationError 表达权限或不存在问题,状态码全部变 400,语义混淆。
  • 自定义异常继承 APIException 却忘改 status_code,业务错误返回 500。

追问

  • NotAuthenticated 与 AuthenticationFailed 区别?答:前者表示未提供凭证(匿名要求登录),后者表示凭证无效/过期,两者都渲染 401。
  • 429 异常类名是什么?答:Throttled,携带 wait 秒数写入 Retry-After。

04.7.17.3-008 异常处理器如何记录日志与请求 ID?

一句话结论

处理器通过 context 拿到 request、视图与异常实例,在生成响应前后记录日志:异常类型、消息、请求路径、用户、请求 ID;对外响应只回传请求 ID 与通用消息,堆栈进服务端日志。请求 ID 由中间件在入口生成并挂到请求/日志上下文,处理器从上下文读取写入响应。

概念解释

  • 日志用于排障,响应用于客户端提示,两者信息粒度不同。
  • 未预期异常要记录完整堆栈,业务异常记录码与上下文即可。

原理流程

  1. 入口中间件生成/透传请求 ID。
  2. 异常处理器接收 exc, context,提取请求与用户。
  3. 记录日志(含堆栈),响应体补充请求 ID,不泄露内部细节。

代码或图示

import logging
logger = logging.getLogger("drf")

def handler(exc, context):
    request = context.get("request")
    logger.warning("api error: %s", exc.__class__.__name__,
                    extra={"path": request.path, "user": getattr(request, "user", None)})
    response = exception_handler(exc, context)
    return response

常见误区

  • 把异常堆栈直接写进响应体返回前端,泄露框架路径、源码结构与数据库信息。
  • 业务异常不记录日志,线上出问题只能靠客户端描述;处理器统一留痕便于追踪。

追问

  • 请求 ID 从哪里取?答:入口中间件生成写入请求属性与日志上下文,处理器透传到响应。
  • 日志级别怎么分?答:4xx 业务异常 warning,5xx 未预期异常 error 并附堆栈。

04.7.17.3-009 非 DRF 异常如何兜底?

一句话结论

默认处理器对非 APIException(裸 Exception、数据库错误、第三方库异常)返回 None,handle_exception 随即重新抛出,交给 Django 中间件按 DEBUG 配置渲染 500 页面或生产错误页。如需统一兜底,可在自定义处理器中识别未处理异常:记录完整堆栈,返回通用 500 结构与请求 ID;不能把原始异常细节回传前端。

概念解释

  • DRF 只归一它认识的异常,其他异常交给 Django 错误处理链。
  • 生产环境 DEBUG 关闭时 Django 不暴露堆栈,只返回通用 500。

原理流程

  1. 动作抛出非 DRF 异常。
  2. 默认处理器返回 None。
  3. 异常上抛 Django,中间件记录并渲染 500;自定义处理器可在此之前兜底包装。

代码或图示

def handler(exc, context):
    response = exception_handler(exc, context)
    if response is None:
        logger.exception("unhandled: %s", exc)
        return Response({"code": "internal_error", "message": "服务器内部错误"}, status=500)
    return response

常见误区

  • 兜底处理器把所有异常转成 200/400 并吞掉堆栈,线上无法定位根因;必须先记录日志再包装。
  • 裸 except Exception 绕过 DRF 链,丢失统一结构;兜底逻辑应放在处理器层。

追问

  • 数据库完整性错误属于哪类?答:非 DRF 异常,默认走 Django 500;可在处理器或服务层捕获转业务 409/400。
  • DEBUG=True 时异常页面可见堆栈,生产必须关闭并依赖日志排查。

04.7.17.3-010 detail 字段与多语言翻译如何处理?

一句话结论

detail 是异常可读消息载体,支持字符串、列表、字段字典;default_detail 可包裹 Django gettext 标记,按请求语言环境翻译。序列化器校验消息同理,字段 error_messages 可配多语言文案。对外响应的 message 展示翻译后文案,code 保持不翻译的稳定标识;不要把翻译后的文案当错误码匹配。

概念解释

  • 消息面向人,错误码面向机器;多语言只作用于消息层。
  • 语言环境由 Django 中间件按请求头/参数解析。

原理流程

  1. 异常/字段声明可翻译消息标记。
  2. 处理器按当前语言环境取翻译文案。
  3. 响应分离 message(翻译)与 code(固定)。

代码或图示

from django.utils.translation import gettext_lazy as _

class InsufficientBalance(APIException):
    status_code = 400
    default_detail = _("余额不足")
    default_code = "insufficient_balance"

常见误区

  • 前端用翻译后文案做分支判断,换语言后匹配失效;分支必须基于错误码。
  • 消息拼接用户输入未转义,跨语言场景下注意输出编码与注入风险。

追问

  • 序列化器校验消息怎么翻译?答:字段 error_messages 字典值用 gettext_lazy 包裹。
  • 错误码需要多语言吗?答:不需要,码是稳定标识,各语言保持一致。

04.7.17.3-011 DRF 版本控制策略总览有哪些?

一句话结论

DRF 提供四种版本控制:URLPathVersioning(路径前缀,如 /v1/articles/)、URLNamespaceVersioning(URL 命名空间映射版本)、HeaderVersioning(自定义请求头携带版本)、QueryParameterVersioning(查询参数 ?version=1)。版本经 request.version 读取,策略在 DEFAULT_VERSIONING_CLASS 或视图 versioning_class 配置;默认版本、允许版本与版本键名均可配置。

概念解释

  • 版本控制解决接口演进期的多版本兼容,不是路由隔离的唯一手段。
  • 不同策略对客户端与网关的暴露方式不同:路径直观,头/参数不改变 URL 结构。

原理流程

  1. 版本类从请求(路径/头/参数/命名空间)解析版本标识。
  2. 写入 request.version 与 request.versioning_scheme。
  3. 视图/序列化器按版本分支响应或兼容字段。

代码或图示

REST_FRAMEWORK = {
    "DEFAULT_VERSIONING_CLASS": "rest_framework.versioning.URLPathVersioning",
    "DEFAULT_VERSION": "v1",
    "ALLOWED_VERSIONS": ["v1", "v2"],
}

常见误区

  • 把版本当主要路由隔离手段,大量复制视图;版本分支应集中在序列化字段与响应兼容层。
  • 未配置 ALLOWED_VERSIONS 导致任意版本号被接受,兼容逻辑失控。

追问

  • request.version 在哪里读取?答:视图方法内直接访问,类型为版本字符串。
  • 版本控制需要配合 URL 路由吗?答:路径/命名空间策略依赖路由结构,头/参数策略不改变路径。

04.7.17.3-012 URLPathVersioning 与 URLNamespaceVersioning 怎么用?

一句话结论

URLPathVersioning 从 URL 路径前缀解析版本(如 path("v1/", include(...))),版本段由 URLconf 捕获;URLNamespaceVersioning 依据 Django URL 命名空间(include(..., namespace="v1"))映射版本名。两者都把版本固化在路由结构里,适合版本与路由分组对应的项目;路径版本直观可调试,命名空间版本更适合多应用挂载。

概念解释

  • 路径版本是 URL 第一段,命名空间版本是 include 的 namespace 别名。
  • 版本类从 resolver match 中提取标识,不改变视图代码。

原理流程

  1. URLconf 按版本分组注册路由。
  2. 版本类从路径段或命名空间解析版本。
  3. 写入 request.version 供业务分支。

代码或图示

urlpatterns = [
    path("v1/", include(("api_v1.urls", "v1"), namespace="v1")),
]

常见误区

  • 路径前缀与 ALLOWED_VERSIONS 不一致,未列出的版本被拒或被默认版本兜底。
  • 命名空间版本改动路由名后忘记同步版本映射,request.version 取空。

追问

  • 路径版本对 SEO/分享链接有影响吗?答:版本前缀固定在 URL,旧版本链接长期可访问。
  • 一个路由能挂多个版本命名空间吗?答:可以,按 include 分组注册不同版本 URL 模块。

04.7.17.3-013 HeaderVersioning 与 QueryParameterVersioning 怎么用?

一句话结论

HeaderVersioning 从自定义请求头(默认 Accept-Version)读取版本;QueryParameterVersioning 从查询参数(默认 version)读取版本。两者不改变 URL 结构,同一路由服务多版本,适合移动端 API 与网关转发场景;版本头/参数缺失时回退 DEFAULT_VERSION。可通过 version_param 配置头名或参数名。

概念解释

  • 头版本适合客户端能自定义请求头的场景;参数版本调试简单但暴露在日志与历史记录。
  • 两种策略都需要客户端显式带版本标识,未带走默认版本。

原理流程

  1. 版本类从请求头或查询参数取版本值。
  2. 校验是否在允许列表内。
  3. 写入 request.version。

代码或图示

from rest_framework.versioning import HeaderVersioning

class ArticleView(APIView):
    versioning_class = HeaderVersioning
    version_param = "X-Api-Version"

常见误区

  • 参数版本把版本号写进可分享链接,缓存与日志混入版本差异;头版本更适合不可变客户端。
  • 版本缺失静默走默认版本,客户端误以为在用新版本;关键接口可校验版本显式提供。

追问

  • 默认版本在哪里配?答:DEFAULT_VERSION,未识别版本号时兜底使用。
  • 版本参数名能改吗?答:version_param 属性/配置指定头名或查询参数名。

04.7.17.3-014 request.version 与 versioning_class 如何配置和读取?

一句话结论

全局在 REST_FRAMEWORK.DEFAULT_VERSIONING_CLASS 配置版本类路径;视图级 versioning_class 属性覆盖全局。版本解析后挂到 request.version,视图内据此分支:选择序列化器、裁剪字段、调整响应结构。request.versioning_scheme 持有版本类实例,可读取配置的默认版本与允许版本列表。

概念解释

  • 版本是请求上下文的一部分,与认证、分页同属视图前置解析。
  • 业务分支集中读取 request.version,不要在各处解析请求头。

原理流程

  1. 视图装配版本类实例。
  2. determine_version 解析版本写入请求。
  3. 动作方法按 request.version 选择行为。

代码或图示

def get_serializer_class(self):
    if self.request.version == "v2":
        return ArticleV2Serializer
    return ArticleSerializer

常见误区

  • 视图内直接解析请求头取版本,绕过版本类配置,换策略时代码全量改动。
  • 版本分支散落在序列化器与模板各处;按版本集中装配序列化器与响应结构。

追问

  • 未配置版本类时 request.version 是什么?答:通常为 None 或默认版本(待确认:未配置时的具体取值以 DRF 3.1x 行为为准)。
  • 版本能在序列化器里读取吗?答:通过 self.context["request"].version 间接读取。

04.7.17.3-015 版本升级时如何处理弃用字段与响应兼容?

一句话结论

兼容策略:新版本新增字段不破坏旧客户端读取(旧版本忽略多余字段);废弃字段在旧版本响应中保留、新版本移除;请求字段做向后兼容(可选字段给默认值)。按 request.version 选择序列化器或在序列化器 to_representation 中裁剪/重命名字段。响应头可标注弃用信息(如 Deprecation/Sunset 头),旧版本进入维护期后下线。

概念解释

  • API 兼容原则:新增字段安全,删除/改名字段破坏旧客户端。
  • 版本分支落在序列化表示层,业务模型保持稳定。

原理流程

  1. 识别旧版本依赖的字段与行为。
  2. 新版本序列化器调整字段,旧版本序列化器保留旧结构。
  3. 过渡期并行服务,下线前通知客户端迁移。

代码或图示

def to_representation(self, instance):
    data = super().to_representation(instance)
    if self.context["request"].version == "v1":
        data["legacy_name"] = data.pop("name")
    return data

常见误区

  • 在模型层删改字段直接影响所有版本,旧客户端响应结构断裂;字段兼容放在序列化表示层。
  • 只在文档标注弃用,响应无任何提示;过渡阶段可用响应头或响应字段标记废弃状态。

追问

  • 新版本能否要求旧字段必填?答:破坏性变更应开新版本,旧版本保持可选与默认值。
  • 弃用响应头有哪些?答:Deprecation 与 Sunset(标准草案),告知废弃与下线时间(待确认:头部标准支持程度按网关与客户端确认)。

04.7.17.3-016 什么情况下应该开新版本而不是原地兼容?

一句话结论

当变更破坏旧客户端契约:删除/重命名字段、改变字段类型或语义、改错误码与状态码、调整必填约束、移除接口行为,应开新版本并行服务;新增可选字段、放宽校验、增加接口属于向后兼容,可原地迭代。版本号策略保持语义化,旧版本进入维护期,预留迁移窗口后下线。

概念解释

  • 向后兼容变更不强制新版本,降低维护分支数量。
  • 破坏性变更必须隔离版本,避免旧客户端在不知情下断裂。

原理流程

  1. 评估变更对旧客户端请求/响应结构的影响。
  2. 判定兼容级别:新增安全、修改谨慎、删除破坏。
  3. 破坏性变更走新版本路由/策略,过渡期并行服务。

代码或图示

新增可选字段 / 新接口        → 原地迭代
字段改类型 / 必填收紧        → 新版本
删除字段 / 改响应结构         → 新版本

常见误区

  • 所有小改动都开新版本,版本分支泛滥、测试矩阵膨胀;先判断是否真的破坏契约。
  • 不开新版本直接改旧接口,线上旧客户端报错后才紧急回滚;破坏性变更必须先评估客户端覆盖。

追问

  • 版本下线流程是什么?答:公告迁移期 → 旧版本响应标记废弃 → 到期移除路由与代码。
  • 内部系统也需要版本号吗?答:内部强同步发布可简化,对外/跨团队 API 应版本化。

04.7.17.3-017 DRF list 接口常见性能瓶颈有哪些?

一句话结论

典型瓶颈按链路分层:数据库层 N+1 查询、缺索引导致全表扫描/排序 filesort;序列化层全量实例化与 SerializerMethodField 逐行调用;数据传输层未分页导致大响应体;缓存缺失重复计算;下游调用在序列化循环内逐条发起。定位时先看查询数与扫描行数,再看序列化 CPU 与响应体积。

概念解释

  • 接口耗时 = DB 查询 + Python 序列化 + 网络传输,三者分别测量。
  • 列表接口随数据量退化,多为查询与预加载问题,而非框架本身慢。

原理流程

  1. 测量单次请求 SQL 数量、总耗时与扫描行数。
  2. 统计序列化对象数、响应体积与 CPU 占用。
  3. 按瓶颈分层优化:预加载/索引/分页/缓存/批量调用。

代码或图示

瓶颈分层:
DB: N+1、缺索引、大偏移排序
序列化: 全量实例化、MethodField 循环调用
传输: 未分页、冗余字段
下游: 循环内逐条 RPC/HTTP

常见误区

  • 接口慢就怀疑 DRF 框架开销,实际多为查询集未预加载;先开 SQL 计数定位。
  • 只优化查询不裁剪响应字段,大列表序列化仍产出冗余 JSON,序列化与传输成本居高不下。

追问

  • 怎么判断是 DB 还是序列化慢?答:对比 SQL 总耗时与 Python 段耗时,结合查询数和响应体积。
  • 列表接口 CPU 高常见原因?答:大量对象序列化、MethodField 计算、嵌套字典构造,以及响应编码。

一句话结论

select_related 用于一对一、多对一外键的单条关联加载,SQL 用 JOIN 一次查出主对象与关联对象,避免序列化访问外键时逐条查询。序列化器中嵌套展示的外键字段(如 author 嵌套对象),视图查询集应 select_related("author");它是 JOIN 加载,不适用多对多与反向一对多。

概念解释

  • 单向外键、反向一对一属于 JOIN 可覆盖的关联。
  • 嵌套层级深时逐层 select_related("author__profile") 链式预加载。

原理流程

  1. 查询集 select_related 构造 JOIN。
  2. 单次 SQL 取出主表与关联表字段。
  3. 序列化访问关联属性直接取已加载对象,不再发查询。

代码或图示

class ArticleViewSet(viewsets.ReadOnlyModelViewSet):
    serializer_class = ArticleSerializer

    def get_queryset(self):
        return Article.objects.select_related("author", "category")

常见误区

  • 对多对多关系用 select_related,Django 报错或无效;多对多用 prefetch_related。
  • JOIN 加载过多表导致 SQL 膨胀、重复字段;只预加载序列化实际输出的关联。

追问

  • select_related 能加载反向一对多吗?答:不能,反向多条记录无法在单条 JOIN 行表达,用 prefetch_related。
  • 链式预加载怎么写?答:select_related("author__profile") 沿外键路径加载。

一句话结论

prefetch_related 用于多对多、反向一对多等多条关联:先查主对象,再用 IN 批量查关联记录并组装到对象缓存,避免逐条查询。Prefetch 对象可指定自定义查询集(过滤、排序、只取字段)与结果归属名。序列化嵌套输出反向集合(如文章的评论列表)时,在查询集上 prefetch_related("comments")。

概念解释

  • prefetch 是二次查询组装,不做 JOIN,适合一对多集合。
  • Prefetch 可对关联表加过滤与索引字段,缩小批量查询范围。

原理流程

  1. 第一次查询取主对象列表。
  2. 第二次查询按主对象 ID 批量取关联记录。
  3. ORM 按关联关系回填到对象,序列化直接读取。

代码或图示

from django.db.models import Prefetch

def get_queryset(self):
    return Article.objects.prefetch_related(
        Prefetch("comments", queryset=Comment.objects.filter(approved=True).only("id", "content"))
    )

常见误区

  • prefetch 的关联查询集没限制字段与条件,二次查询仍拉全表记录;用 only/过滤裁剪。
  • 在 SerializerMethodField 里访问未 prefetch 的反向集合,每个对象触发一次查询,回到 N+1。

追问

  • prefetch 与 select_related 能混用吗?答:能,外键 JOIN、多对多/反向集合 prefetch,按关联类型选择。
  • Prefetch 的 to_attr 干什么用?答:把预加载结果挂到指定对象属性名,避免覆盖默认关联缓存。

04.7.17.3-020 N+1 问题如何复现与定位?

一句话结论

N+1 指列表先查 1 次主对象,序列化访问每个对象的关联时各发 1 次查询,共 N+1 次。复现:在未预加载的查询集上序列化含关联嵌套的列表。定位:开启 Django 查询日志或 assertNumQueries,统计 SQL 数量随列表条数线性增长;也可用 django-debug-toolbar 查看每条 SQL。修复:按关联类型补 select_related/prefetch_related。

概念解释

  • 判定特征:查询数 ≈ 1 + 记录数,关联查询重复出现同一张表。
  • 嵌套越深,未预加载的关联越多,N+1 越严重。

原理流程

  1. 构造 N 条记录的列表接口。
  2. 统计 SQL 语句数量与类型。
  3. 发现关联查询随 N 增长后,在查询集补预加载并复核查询数回落。

代码或图示

from django.test import TestCase

class ArticleApiTest(TestCase):
    def test_list_queries(self):
        # 预加载后查询数应固定,不随文章数增长
        with self.assertNumQueries(3):
            self.client.get("/articles/")

常见误区

  • 只在详情接口测查询数,列表 N+1 漏检;必须用列表接口并放大数据量观察查询增长。
  • 修复后只看接口不报错,不复核 SQL 数量;预加载是否生效要以查询计数为准。

追问

  • 日志里怎么识别 N+1?答:同一关联表 SQL 反复出现,参数为主对象 ID 逐个变化。
  • N+1 只在 DRF 出现吗?答:ORM 序列化/模板遍历关联都会触发,DRF 视图只是常见暴露点。

04.7.17.3-021 序列化开销来自哪些环节?

一句话结论

序列化开销包括:字段遍历与取值(get_attribute 按 source 解析属性链)、类型转换与 to_representation、嵌套序列化器递归、SerializerMethodField 逐行回调方法、字典组装与 JSON 编码。列表越大对象越多,成本线性增长;MethodField 内若再查库,叠加 N+1。优化方向:裁剪字段、预加载、避免循环内计算、必要时用 Values/字典直出。

概念解释

  • 序列化是 Python CPU 密集段,对象数是主要放大因子。
  • 嵌套层级增加表示层递归成本,字段越多遍历越慢。

原理流程

  1. 每个对象遍历声明字段,按 source 取值。
  2. 字段做类型转换与表示转换,嵌套字段递归。
  3. 组装字典交给渲染器 JSON 编码。

代码或图示

class OrderSerializer(serializers.ModelSerializer):
    # 每行调用一次方法,方法内避免查库
    summary = serializers.SerializerMethodField()

    def get_summary(self, obj):
        return f"{obj.item_count} 件 / {obj.amount}"

常见误区

  • 把聚合计算(求和、计数)放在 MethodField 逐行执行,本可 SQL 注解一次算出;应在查询集 annotate。
  • 序列化器字段超出响应需要,输出冗余 JSON 增加序列化与传输成本;按动作裁剪字段。

追问

  • 序列化慢怎么量化?答:用查询计数之外测量接口 CPU 时间、响应体积,对比裁剪字段前后。
  • 能否跳过序列化器直出字典?答:性能敏感场景可在视图构造 Values 字典,但会失去校验与字段约定,权衡复用与性能。

04.7.17.3-022 many=True 批量序列化与手写列表推导有什么区别?

一句话结论

many=True 由 ListSerializer 遍历子序列化器逐项表示,统一处理列表级校验、错误按索引聚合与上下文共享;手写列表推导逐项调序列化器或拼字典,灵活但要自行处理上下文、字段一致性与错误结构。批量输出场景优先复用序列化器 many=True,性能极致场景才考虑直出字典。

概念解释

  • ListSerializer 是集合级封装,子序列化器负责单项。
  • 手写推导绕过框架校验与 schema 生成,契约保障减弱。

原理流程

  1. many=True 构造 ListSerializer 包裹子序列化器。
  2. 逐项 to_representation 收集结果列表。
  3. 输出统一列表结构,错误按索引聚合。

代码或图示

# 框架批量序列化
serializer = ArticleSerializer(queryset, many=True)
return Response(serializer.data)

# 手写直出(性能场景)
data = [{"id": a.id, "title": a.title} for a in queryset]

常见误区

  • 手写推导里重复实例化子序列化器且不传 context,CurrentUserDefault 等上下文失效。
  • 为微优化手写直出,后续字段变更两处不同步;除非压测证明序列化器是瓶颈,否则保持复用。

追问

  • 批量序列化能复用同一个子序列化器实例吗?答:ListSerializer 内部对子项统一委派,不要在循环外手动复用实例绕框架。
  • 列表级字段(如总数)在哪加?答:分页包装或响应外层,不塞进 ListSerializer 单项结果。

04.7.17.3-023 为什么列表接口必须分页?全量序列化有什么压力?

一句话结论

全量返回会同时放大三类压力:数据库一次取出大量行与关联记录,内存持有全部模型实例;Python 序列化全量对象并构造大字典;响应体巨大占用带宽并延长客户端解析时间。分页把单次处理限制在当前页大小,DB、内存、序列化、传输都有上界。导出等批量场景另走异步/流式方案,不在在线 list 接口全量返回。

概念解释

  • 分页是在线浏览接口的资源保护,不是功能装饰。
  • 未分页接口随表增长从慢变不可用,属于容量隐患。

原理流程

  1. 不分页:查询集全量实例化 → 全量序列化 → 大响应传输。
  2. 分页:切片当前页 → 只序列化当前页 → 元数据导航翻页。
  3. 单次资源占用随页大小固定,不随总量增长。

代码或图示

class ArticleViewSet(viewsets.ModelViewSet):
    pagination_class = PageNumberPagination  # 默认页大小兜底

常见误区

  • 后台管理图方便关闭分页,数据量上来后接口超时 OOM;后台同样需要分页或分批加载。
  • 分页只切数据库行,序列化仍遍历全量;确认分页器在序列化前完成切片。

追问

  • 分页能解决大响应体吗?答:限制单次返回条数,响应体积有界;极端大字段仍需裁剪。
  • 全量导出走哪条路径?答:异步任务分批写文件,提供下载链接,不在同步请求内序列化全量。

04.7.17.3-024 only/defer 如何与序列化字段对齐?

一句话结论

only 只从数据库取指定列,defer 排除指定列;应按序列化器实际输出的字段选择查询列,避免取了不用的大字段(正文、二进制、JSON 文本)。关联预加载查询集同样可加 only/defer。注意:延迟字段在后续访问时才触发查询,若序列化输出该字段会再次回表,造成额外查询。

概念解释

  • 列裁剪减少单行数据量与传输,与行预加载(select/prefetch)互补。
  • 字段对齐指查询列集合是序列化输出字段的超集。

原理流程

  1. 梳理序列化器输出字段与嵌套关联字段。
  2. 查询集 only(...) 取必要列,关联查询集同步裁剪。
  3. 序列化访问未取列时确认是否触发延迟回表,必要时补进 only。

代码或图示

Article.objects.only("id", "title", "created_at").select_related("author")

常见误区

  • only 列少了序列化输出字段,访问时触发延迟字段查询,反而增加 SQL 次数;列集合必须覆盖输出字段。
  • 对含大文本/附件的模型默认取全列,列表接口拉取冗余大字段拖慢传输;列表序列化器与查询列一起裁剪。

追问

  • defer 与 only 区别?答:only 白名单取哪些列,defer 黑名单排除哪些列。
  • 延迟字段访问一定回表吗?答:未在初始查询取出的字段,首次访问时触发补充查询。

04.7.17.3-025 大数据量下计数查询与分页有什么注意点?

一句话结论

分页响应的总数通常来自 queryset.count(),大表 COUNT(*) 在 InnoDB 上随行数变慢;深分页 OFFSET 越往后扫描成本越高。计数可接受延迟时用近似值/缓存计数,翻页优先游标分页避免大偏移;不要对全量序列化结果取 len() 算总数。关联多、过滤条件复杂的计数要核对执行计划。

概念解释

  • 精确计数与翻页深度是两个独立性能点,都随数据量退化。
  • 总数只用于展示总页数,可按业务容忍度降级。

原理流程

  1. 分页器对过滤后查询集执行 count()。
  2. 切片取当前页对象。
  3. 深偏移改为游标定位,计数按预算缓存或近似。

代码或图示

# 避免:len(serializer.data) 触发全量实例化
# 推荐:count() 数据库聚合
total = Article.objects.filter(status="published").count()

常见误区

  • 列表接口为展示总数每次实时 count(),大表计数拖慢首屏;热门列表可缓存计数或延迟统计。
  • 页码分页跳到很深的页,OFFSET 扫描大量行;流式/大数据翻页改游标分页。

追问

  • count() 会实例化模型吗?答:不会,走数据库聚合 COUNT,不构造 Python 对象。
  • 近似计数怎么实现?答:维护计数表/缓存,或用数据库统计估算,精度按业务接受。

04.7.17.3-026 序列化结果如何做缓存与失效?

一句话结论

可缓存的是序列化后的表示结果或聚合数据:按资源标识 + 版本 + 权限范围做缓存键,命中直接返回缓存字典;失效在创建/更新/删除对应资源时主动清除,或设短 TTL 兜底。缓存前注意数据权限差异(不同用户可见数据不同),缓存键要含身份/范围维度;动态个人数据不适合全局缓存。

概念解释

  • 缓存对象是响应表示,不是模型实例;模型变更要让缓存失效。
  • 缓存粒度按资源、列表页、聚合统计分层。

原理流程

  1. 构造缓存键:资源 ID/列表条件/版本/身份范围。
  2. 命中返回缓存序列化字典;未命中查询序列化后写缓存。
  3. 数据变更时删除相关缓存键,TTL 作为兜底过期。

代码或图示

from django.core.cache import cache

def get_cached_article(article_id):
    key = f"article:{article_id}:v2"
    data = cache.get(key)
    if data is None:
        obj = get_object_or_404(Article, pk=article_id)
        data = ArticleSerializer(obj).data
        cache.set(key, data, 300)
    return data

常见误区

  • 把私有数据按公共键缓存,A 用户读到 B 用户可见内容;缓存键必须含权限/归属维度。
  • 更新后不主动失效缓存,只靠长 TTL,旧数据长时间残留;写路径同步清缓存。

追问

  • 缓存序列化字典还是模型实例?答:缓存可 JSON 化的表示字典;缓存实例需处理序列化依赖与版本兼容。
  • 列表缓存怎么失效?答:资源新增/变更时清理列表键,或列表缓存短 TTL + 主动刷新热点页。

04.7.17.3-027 大查询集 iterator() 与分页如何取舍?

一句话结论

iterator() 按批次流式取记录,避免一次性把全量对象加载进内存,适合导出、批处理等非在线浏览场景;分页是在线接口按页返回并支持翻页导航。在线 list 用分页控制单次量级,后台批量任务/导出用 iterator() 分批处理;两者都避免全量实例化,但产物形态与使用场景不同。

概念解释

  • iterator 减少内存峰值,代价是不支持随机翻页与计数。
  • 分批大小可通过 chunk_size 调整。

原理流程

  1. 批量任务遍历 queryset.iterator(chunk_size=500)。
  2. 每批处理/序列化/写出,释放引用。
  3. 在线接口走分页器切片当前页。

代码或图示

def export_articles():
    for obj in Article.objects.iterator(chunk_size=500):
        write_row(ArticleExportSerializer(obj).data)

常见误区

  • 在线接口用 iterator 替代分页,没有翻页元数据,前端无法导航;分页职责不能用流式替代。
  • iterator 批次内仍访问未预加载关联,批次内重复 N+1;关联预加载在查询集上完成。

追问

  • iterator 会绕过缓存吗?答:查询集缓存行为不同,迭代时按批次取数,注意不要重复迭代同一查询集。
  • 大批量导出内存怎么控?答:分批读取、分批写出文件,序列化结果不累积在内存。

04.7.17.3-028 序列化器校验成本与批量写入怎么优化?

一句话结论

校验成本随字段数与条目数增长:类型转换、字段 validator、跨字段校验逐条执行;批量写入默认逐条 create,无 bulk_create 优化。大批量提交应在 ListSerializer.create 内批量入库,校验仍逐条通过但持久化合并;校验涉及数据库唯一检查时,批量场景注意重复与事务边界。

概念解释

  • 校验是数据安全前置,不能为性能跳过;持久化批量可合并。
  • 批量写入需要事务包裹,部分失败回滚策略明确。

原理流程

  1. many=True 逐项校验通过后汇总 validated_data。
  2. ListSerializer.create 重写为 bulk_create 批量插入。
  3. 事务内批量入库,返回批量结果。

代码或图示

class BulkTagListSerializer(serializers.ListSerializer):
    def create(self, validated_data):
        return Tag.objects.bulk_create([Tag(**item) for item in validated_data])

class TagSerializer(serializers.ModelSerializer):
    class Meta:
        model = Tag
        list_serializer_class = BulkTagListSerializer

常见误区

  • 批量提交在循环内逐条 save(),每条触发信号与 INSERT,批量接口吞吐低;持久化合并批量入库。
  • 批量写入不开事务,部分成功部分失败留下脏数据;批量操作必须 transaction.atomic 包裹。

追问

  • bulk_create 会发送模型信号吗?答:默认不发送 post_save 等信号,依赖信号的逻辑要另行处理。
  • 批量唯一冲突怎么处理?答:数据库唯一约束兜底,批量前查重或捕获 IntegrityError 转业务错误。

04.7.17.3-029 过滤、排序字段为什么要核对数据库索引?

一句话结论

WHERE 过滤、ORDER BY 排序、JOIN 关联都依赖索引:无索引过滤全表扫描,无索引排序 filesort,数据量增长后接口退化。开放给前端的过滤/排名字段要与表索引对齐;复合索引遵循最左前缀,等值条件在前、区间在后。变更索引后用查询计划核对扫描行数与排序方式。

概念解释

  • 索引服务三类操作:过滤、连接、排序。
  • 索引不是越多越好,写入开销与索引体积随数量上升。

原理流程

  1. 梳理开放过滤/排序/关联字段。
  2. 为高频组合建复合索引,核对最左前缀。
  3. 用 EXPLAIN/查询计划验证扫描行数与是否 filesort。

代码或图示

class Article(models.Model):
    status = models.CharField(max_length=16)
    created_at = models.DateTimeField()

    class Meta:
        indexes = [models.Index(fields=["status", "created_at"])]

常见误区

  • 给每个开放字段单独建索引,写入变慢且索引冗余;按实际查询组合评估复合索引。
  • 排序字段与过滤字段分属不同索引,数据库无法同时利用,出现 filesort;设计复合排序过滤索引。

追问

  • 文本包含搜索能用普通索引吗?答:%kw% 前缀通配通常不能,需全文索引或搜索引擎。
  • 索引上线后怎么验证有效?答:看执行计划 type/key/rows,对比加索引前后扫描行数。

04.7.17.3-030 有哪些工具定位 DRF 接口性能问题?

一句话结论

常用手段:Django 数据库查询日志/assertNumQueries 统计 SQL 数量;django-debug-toolbar 查看每条 SQL、时间与模板/序列化耗时;日志记录接口路径、耗时、查询数与响应体积;压测工具测吞吐与延迟分布。定位顺序:先确认查询数与扫描行数,再看序列化 CPU 与响应体积,最后排查下游调用。

概念解释

  • 工具提供量化指标,不靠感觉判断瓶颈。
  • 测试环境放大数据量复现退化,小数据量看不出 N+1 与索引问题。

原理流程

  1. 开启 SQL 日志或测试断言统计查询数。
  2. 工具栏/日志查看 SQL 计划、耗时与 Python 段耗时。
  3. 压测记录 P50/P95/P99 延迟与吞吐,验证优化效果。

代码或图示

from django.test import TestCase
from django.db import connection

class PerfTest(TestCase):
    def test_queries(self):
        self.client.get("/articles/")
        print(len(connection.queries))

常见误区

  • 只看接口平均耗时,忽略 P95/P99;慢请求集中在长尾,平均值掩盖退化。
  • 优化后不回归查询数与耗时对比,无法确认收益;每次调整留量化前后对比。

追问

  • 生产环境怎么看慢查询?答:数据库慢查询日志 + 接口日志关联,按 SQL 指纹聚合。
  • 序列化耗时怎么单独测?答:视图外单独实例化序列化器遍历数据,计时对比裁剪字段前后。

04.7.17.3-031 DRF 序列化器与 Pydantic 如何取舍?

一句话结论

DRF 序列化器与 Django ORM、视图、权限、分页、schema 深度集成,适合 Django 项目内 API 校验与表示;Pydantic 是独立数据校验模型,类型提示友好、生态广(FastAPI、设置管理、消息契约),不绑定 ORM。选型:Django 单体 API 用 DRF 序列化器;非 Django 服务、需要类型推导/异步栈、跨语言契约优先 Pydantic。两者可并存:DRF 视图内用序列化器,内部消息/配置用 Pydantic。

概念解释

  • DRF 序列化器承担校验 + 模型持久化钩子 + 表示输出;Pydantic 聚焦数据模型校验与序列化。
  • Pydantic v2 基于 Rust 核心,校验性能与类型体验是优势;DRF 优势在 Django 生态集成。

原理流程

  1. 评估项目技术栈:是否 Django ORM、是否需要视图/权限/分页集成。
  2. 评估数据模型用途:API 表示、内部消息、配置、跨服务契约。
  3. 按栈选择,边界处可做双向转换。

代码或图示

# DRF 序列化器:绑定模型与视图
class ArticleSerializer(serializers.ModelSerializer):
    class Meta:
        model = Article
        fields = ["id", "title"]

# Pydantic 模型:独立校验
from pydantic import BaseModel

class ArticlePayload(BaseModel):
    title: str
    content: str

常见误区

  • 在 Django 项目里为每个接口再写一套 Pydantic 模型,校验与字段定义重复维护;栈内优先复用 DRF 序列化器。
  • 把 DRF 序列化器搬到 FastAPI 项目,依赖 Django 请求上下文与 ORM,无法独立运行。

追问

  • Pydantic 能替代 DRF 做响应 schema 吗?答:可做数据校验与 OpenAPI 生成,但 DRF 视图编排、权限分页需另建。
  • 两者数据怎么互转?答:validated_data/模型实例与 Pydantic 模型之间手动构造或用 model_validate/model_dump 转换。

04.7.17.3-032 什么场景不适合使用 DRF?

一句话结论

不适合场景:纯异步高并发小服务(栈是 FastAPI/Starlette,无 Django ORM);需要轻量路由与最小依赖的内部 RPC;非 Django 技术栈的微服务;前端重交互、后端只出聚合数据且已有其他框架约定。DRF 价值在于 Django 生态集成,脱离 Django 后这些集成优势不复存在,框架本身的样板反而成为负担。

概念解释

  • 选型先定技术栈,再定框架;DRF 是 Django 生态内的 API 层。
  • 极简服务用原生 Django 视图或轻量框架即可,不必引入整套 DRF。

原理流程

  1. 确认项目是否使用 Django ORM 与 Django 中间件体系。
  2. 评估性能模型:同步请求栈还是异步事件循环。
  3. 栈匹配用 DRF,不匹配选 FastAPI/其他轻量方案。

代码或图示

Django 单体 / 后台 / 标准 CRUD API   → DRF
异步高并发 / 无 ORM 绑定             → FastAPI
极简内部 RPC / 最小依赖              → 原生视图或轻量路由

常见误区

  • 团队熟悉 DRF 就在非 Django 项目硬套,引入不必要的 Django 依赖与同步模型。
  • 为用 DRF 把简单接口拆成 ViewSet/序列化器/权限类多层结构,过度设计。

追问

  • DRF 能跑在纯 ASGI 异步栈吗?答:DRF 3.1x 对异步有一定支持,但核心编排围绕同步请求模型;异步优先场景评估 FastAPI 更合适(待确认:异步支持范围以当前版本文档为准)。
  • 不用 DRF 还能复用序列化器校验吗?答:Serializer 可脱离视图实例化,但依赖 Django 字段与上下文,复用价值有限。

04.7.17.3-033 DRF 与 Django ORM 耦合带来哪些限制?

一句话结论

耦合体现在:ModelSerializer 直接读取模型字段与关系,ModelViewSet 围绕查询集与模型实例编排,权限/过滤/分页都以 ORM QuerySet 为中心。限制:非模型数据源(外部 API、聚合字典、NoSQL 文档)需要手写 Serializer;换数据层要重写数据访问层;序列化器行为受模型字段约束影响;异步与非关系数据源集成受限。

概念解释

  • 耦合提高 Django 内开发效率,也锁定数据层假设。
  • 视图编排假设数据源是可过滤、可分页的 QuerySet。

原理流程

  1. ModelSerializer 反射模型字段生成 DRF 字段。
  2. ViewSet 方法基于 get_queryset 返回的 QuerySet 取对象。
  3. 数据层替换时,序列化器与视图的数据访问假设需要同步调整。

代码或图示

# 非模型数据源:手写 Serializer,不绑定 Meta.model
class ExternalStatsSerializer(serializers.Serializer):
    total = serializers.IntegerField()
    active = serializers.IntegerField()

常见误区

  • 把外部聚合数据硬塞进 ModelSerializer,模型字段与 API 结构不匹配,反复 source 打补丁;数据源非模型时直接用 Serializer。
  • 假设所有数据源都支持 filter_queryset 与分页;外部 API 数据源要自行实现过滤分页适配。

追问

  • DRF 序列化器必须绑定模型吗?答:不是,基础 Serializer 可处理任意字典/对象数据。
  • ORM 耦合影响测试吗?答:测试仍走 Django 测试数据库,非 ORM 数据源需要 mock 适配层。

04.7.17.3-034 在 FastAPI 项目中复用 Django 模型要注意什么?

一句话结论

复用 Django 模型意味着同时引入 Django ORM 与配置加载:需要 django.setup()、配置 DATABASES、迁移与模型注册;FastAPI 异步栈中直接用同步 ORM 会阻塞事件循环,需线程池包裹或改用异步 ORM 驱动。模型可作为数据结构与表定义复用,但 DRF 序列化器、视图、权限不能直接搬到 FastAPI,校验层应改用 Pydantic。

概念解释

  • 复用模型定义 ≠ 复用 DRF 整套 API 层。
  • 同步 ORM 在异步服务里是阻塞点,连接池与线程模型要单独规划。

原理流程

  1. 初始化 Django 配置并 django.setup() 注册模型。
  2. 数据访问走 ORM,同步调用放入线程池避免阻塞循环。
  3. 请求/响应模型用 Pydantic 定义,不依赖 DRF 序列化器。

代码或图示

import django
from django.conf import settings

settings.configure(DATABASES={...}, INSTALLED_APPS=[...])
django.setup()

常见误区

  • 在 FastAPI 路由里直接同步调用 ORM 查询,阻塞事件循环导致并发下降;同步 DB 操作必须走线程池或换异步驱动。
  • 把 DRF 序列化器当 Pydantic 模型挂到 FastAPI 依赖注入,缺少 DRF 上下文且类型不兼容。

追问

  • 模型迁移在 FastAPI 项目里怎么跑?答:仍用 Django makemigrations/migrate,依赖 Django 管理命令。
  • 有没有轻量替代复用模型?答:只复用字段定义可抽取纯 Python 数据类/Pydantic 模型,不引入 Django 运行时。

04.7.17.3-035 APIClient 与 Django 原生 Client 有什么区别?

一句话结论

APIClient 继承 Django Client,在其基础上提供 DRF 测试辅助:直接发送 JSON 数据、解析 DRF 渲染响应(.data 取解析后字典、.json() 取原始 JSON)、force_authenticate 快捷认证、支持格式后缀与内容协商。原生 Client 只处理表单编码与原始响应内容;测 DRF 接口应使用 APIClient/APITestCase,断言解析后结构而非 HTML 表单。

概念解释

  • APIClient 是测试层封装,不改变生产视图行为。
  • 响应 .data 是 DRF 渲染前解析结构,便于断言字段与错误码。

原理流程

  1. 测试用 APIClient() 构造客户端。
  2. get/post/put/patch/delete 携带 JSON 与认证头。
  3. 响应对象同时提供 .data(解析字典)与 .json()(原始 JSON)。

代码或图示

from rest_framework.test import APIClient

client = APIClient()
response = client.post("/articles/", {"title": "测试"}, format="json")
assert response.status_code == 201
assert response.data["title"] == "测试"

常见误区

  • 用原生 Django Client 测 DRF 接口,响应是原始内容,需手动 json.loads,且无法用 force_authenticate。
  • 断言只看状态码不校验响应结构,字段缺失或错误码漂移漏检。

追问

  • APIClient 能模拟未认证请求吗?答:能,不调 force_authenticate 即为匿名;也可 force_authenticate(user=None) 重置。
  • 上传文件测试用什么方法?答:post 携带 uploaded_file 字典,format="multipart"。

04.7.17.3-036 APITestCase 与 force_authenticate 怎么使用?

一句话结论

APITestCase 继承 Django TestCase,内置 APIClient 实例(self.client)与 DRF 断言辅助;force_authenticate(user=None, token=None) 在客户端层面强制设置认证身份,跳过真实登录流程,便于测已认证接口。测试结束随事务回滚,认证状态不跨用例泄漏。需要测试真实登录流程时再走账号密码 POST 登录接口。

概念解释

  • force_authenticate 是测试快捷方式,模拟认证结果,不发 Token/Session。
  • 每个测试方法独立客户端与事务,状态隔离。

原理流程

  1. 继承 APITestCase,self.client 即 APIClient。
  2. 前置 self.client.force_authenticate(user=...)。
  3. 发请求断言响应;用例结束回滚数据库。

代码或图示

from rest_framework.test import APITestCase

class ArticleTest(APITestCase):
    def setUp(self):
        self.user = User.objects.create_user(username="u", password="p")
        self.client.force_authenticate(user=self.user)

    def test_create(self):
        response = self.client.post("/articles/", {"title": "x"}, format="json")
        self.assertEqual(response.status_code, 201)

常见误区

  • 在类级别 force_authenticate 后某个用例需要匿名,忘记重置;调 force_authenticate(user=None) 恢复匿名。
  • 用 force_authenticate 测试认证失败场景,跳过了真实凭证校验;认证链路本身要用登录接口或伪造凭证测试。

追问

  • force_authenticate 能传 token 吗?答:可传 token= 参数挂到 request.auth,模拟凭证对象。
  • 测试数据库会保留吗?答:TestCase 内事务回滚,用例间数据隔离。

04.7.17.3-037 测试数据如何构造:fixture、factory_boy、setUpTestData?

一句话结论

Django 测试基类提供 setUp(每用例前新建数据)与 setUpTestData(类级一次性建数据,用例间只读共享,提速);fixture 加载固定初始数据;factory_boy 用工厂类按模板生成带默认值的测试对象,适合多实例与关联数据。选择:少量固定数据用 setUp,同组用例共享只读数据用 setUpTestData,复杂关联与批量造数用工厂。

概念解释

  • setUpTestData 在事务内一次创建,用例回滚到该事务保存点,比每用例重建快。
  • 工厂封装默认值与关联构造,避免测试里重复填字段。

原理流程

  1. 测试类定义 setUpTestData 建共享基准数据。
  2. 每用例 setUp 补充本用例专属数据。
  3. 工厂按需生成关联对象,断言后随事务回滚。

代码或图示

class ArticleTest(APITestCase):
    @classmethod
    def setUpTestData(cls):
        cls.user = User.objects.create_user(username="owner")

    def setUp(self):
        self.client.force_authenticate(user=self.user)

常见误区

  • 在 setUpTestData 里修改共享对象,用例间数据互相污染;共享数据保持只读,可变数据放 setUp。
  • 测试里硬编码大量字段值,字段变更时多处修改;用工厂集中默认值。

追问

  • setUpTestData 与 setUp 性能差在哪?答:前者类级一次建数据,后者每用例重建,数据量大时差距明显。
  • factory_boy 怎么构造关联对象?答:工厂类用 SubFactory/RelatedFactory 声明关联,调用 create() 级联生成。

04.7.17.3-038 如何断言响应状态、结构与错误码?

一句话结论

断言分三层:状态码(assertEqual(response.status_code, 201))、响应结构(response.data 字段存在、类型、嵌套结构)、错误码(400/403 响应体的 code/detail/字段错误列表)。DRF 测试断言可直接读解析后的 response.data;错误场景断言字段错误挂在对应键下,而不仅是状态码。结构断言防止字段漂移与错误码回归。

概念解释

  • 状态码表达大类,结构与错误码表达契约细节。
  • 列表响应还要断言分页元数据与结果条数。

原理流程

  1. 发请求取响应。
  2. 断言状态码符合预期。
  3. 断言 response.data 字段、类型、嵌套与错误码结构。

代码或图示

def test_validation_error(self):
    response = self.client.post("/articles/", {"title": ""}, format="json")
    self.assertEqual(response.status_code, 400)
    self.assertIn("title", response.data)
    self.assertEqual(response.data["code"], "validation_error")

常见误区

  • 只断言状态码 400,不校验错误字段与码,校验规则改了测试仍通过。
  • 断言 response.data 时假设字段顺序;字典按键比较,不依赖顺序。

追问

  • 列表接口断言什么?答:状态码、结果列表条数、元素字段,分页场景断言 count/next/previous 元数据。
  • 错误码在响应哪个字段?答:按统一错误结构约定,通常在 code,字段细节在 details/字段映射。

04.7.17.3-039 如何覆盖认证与权限场景的测试?

一句话结论

测试矩阵覆盖:匿名访问、已认证普通用户、管理员/归属用户、无对象权限用户;分别断言 200/401/403。认证场景验证未带凭证与伪造凭证返回 401;权限场景验证身份已识别但越权返回 403;对象级权限构造他人对象断言拒绝。force_authenticate 切换身份,权限规则变化时测试先行暴露回归。

概念解释

  • 认证测试回答「身份是否识别」,权限测试回答「身份是否被允许」。
  • 水平越权场景要构造他人资源并尝试访问。

原理流程

  1. 准备不同身份用户与归属数据。
  2. 各身份分别请求同一接口。
  3. 断言状态码与响应错误,覆盖放行与拒绝分支。

代码或图示

def test_owner_only(self):
    other = User.objects.create_user(username="other")
    self.client.force_authenticate(user=other)
    response = self.client.get(f"/articles/{self.article.pk}/")
    self.assertEqual(response.status_code, 403)

常见误区

  • 只测放行路径,拒绝分支无覆盖;权限被放宽后测试无法发现。
  • 权限测试用同一用户既造数据又访问,归属恒为真,越权场景漏检。

追问

  • 401 与 403 测试怎么区分?答:匿名/伪造凭证断言 401,已认证越权断言 403。
  • 对象级权限测试需要查数据库吗?答:构造他人对象入库,请求后断言拒绝,验证 has_object_permission 分支。

04.7.17.3-040 分页与过滤接口如何测试?

一句话结论

分页测试:构造超过页大小的数据,断言首页条数、count、下一页链接,翻页取第二页校验不重复;过滤测试:按各过滤条件构造匹配/不匹配数据,断言结果只含匹配项;排序测试传 ordering 参数断言顺序。测试同时验证白名单字段与非法参数被忽略,分页元数据结构符合约定。

概念解释

  • 分页测试覆盖切片与导航元数据,过滤测试覆盖条件命中与排除。
  • 排序测试验证方向与白名单约束。

原理流程

  1. 批量构造基准数据。
  2. 带分页/过滤/排序参数请求接口。
  3. 断言结果条数、成员、顺序与分页元数据。

代码或图示

def test_pagination(self):
    Article.objects.bulk_create([Article(title=f"a{i}") for i in range(25)])
    response = self.client.get("/articles/?page=1")
    self.assertEqual(response.data["count"], 25)
    self.assertEqual(len(response.data["results"]), 20)

常见误区

  • 测试数据量小于页大小,分页逻辑未被覆盖;必须构造跨页数据。
  • 过滤测试只断言状态码 200,不校验结果成员,条件失效漏检。

追问

  • 游标分页怎么测翻页?答:取首页 next 游标参数请求第二页,断言条目不重复且顺序一致。
  • 非法排序参数断言什么?答:应被白名单忽略,结果按默认排序,不报错。

04.7.17.3-041 限流测试如何重置缓存?

一句话结论

限流计数存缓存,测试间需要清空限流缓存避免用例互相影响:测试前置 cache.clear() 或按限流 key 删除;TestCase 默认使用本地内存缓存,用例回滚不清缓存,需显式清理。模拟超限可直接把缓存历史写满,或临时调低速率配置;断言 429 与 Retry-After 头。测试结束清理缓存状态。

概念解释

  • 缓存不随数据库事务回滚,是测试隔离的常见漏点。
  • 降低速率阈值比手工构造历史时间戳更贴近真实判定。

原理流程

  1. 前置清理限流缓存键或全量 cache.clear()。
  2. 按场景请求至超限(或预置计数)。
  3. 断言 429 状态码与等待头,用例后再次清理。

代码或图示

from django.core.cache import cache

class ThrottleTest(APITestCase):
    def setUp(self):
        cache.clear()

    def test_throttled(self):
        for _ in range(11):
            response = self.client.get("/articles/")
        self.assertEqual(response.status_code, 429)

常见误区

  • 不清缓存,前一用例耗尽配额导致后续用例误判 429。
  • 测试依赖生产缓存配置,缓存后端切换后限流行为不可复现;测试使用隔离缓存别名或内存缓存。

追问

  • 怎么只清某类限流键?答:按 key 前缀遍历删除,或调用限流类的缓存清理方法。
  • 限流测试能改速率配置吗?答:可在测试内覆盖视图 throttle_scope/速率字典,或临时替换限流类。

04.7.17.3-042 测试数据库与事务回滚机制是什么?

一句话结论

Django TestCase 每个用例在事务内执行,结束回滚到保存点,数据不跨用例;setUpTestData 类级事务保存共享基准数据。TransactionTestCase 提交真实事务,用例间通过清空数据库表隔离,适合测试事务提交行为、外部提交副作用。DRF APITestCase 基于 TestCase,默认回滚隔离;需要验证 on_commit 信号或提交后行为时才用 TransactionTestCase。

概念解释

  • 回滚隔离快,但测不到提交瞬间触发的逻辑。
  • TransactionTestCase 慢,因为每用例清空表并重建数据。

原理流程

  1. TestCase 开事务跑用例,结束回滚。
  2. 共享数据在 setUpTestData 保存点创建。
  3. 提交相关逻辑改用 TransactionTestCase,用例间清空数据。

代码或图示

from rest_framework.test import APITransactionTestCase

class CommitSideEffectTest(APITransactionTestCase):
    # 验证 on_commit 信号、提交后外部副作用
    ...

常见误区

  • 在 TestCase 中断言 on_commit 回调执行,回调因未提交而不触发;提交相关测试必须用 TransactionTestCase。
  • 测试数据写在模块级或全局变量,用例间污染;数据在 setUp/工厂内构造。

追问

  • 测试数据库会重复创建吗?答:首次建库,后续用事务/清表隔离,不每次重建 schema。
  • 事务内能测并发行为吗?答:TestCase 单事务隔离下不适合,并发场景用独立线程/进程与专用测试库。

04.7.17.3-043 如何做响应与 OpenAPI 一致性测试?

一句话结论

一致性测试确保实际响应符合 schema:用 drf-spectacular 生成 OpenAPI schema,测试中校验响应结构与声明的请求/响应模型一致;可对关键接口比对 response.data 与 schema 定义字段、类型。CI 中跑 schema 生成校验,防止序列化器改动后文档与接口脱节。契约测试再结合前端消费场景验证字段语义。

概念解释

  • schema 是机器可读契约,测试把运行时响应与契约对齐。
  • 一致性测试防止「文档更新了代码没改」或反之。

原理流程

  1. 视图与序列化器生成 OpenAPI 片段。
  2. 测试发请求取实际响应。
  3. 比对响应字段/类型与 schema 声明,CI 校验 schema 可生成无错误。

代码或图示

from drf_spectacular.validation import validate_schema
# 测试中生成 schema 并校验结构合法

常见误区

  • 只维护手写文档,不生成机器可读 schema;字段漂移无人发现。
  • schema 生成报错被忽略,文档本身已不可靠;CI 应把 schema 校验纳入门禁。

追问

  • 一致性测试与契约测试区别?答:前者比对响应与接口 schema,后者验证跨端约定(字段语义、错误码、版本兼容)满足消费方预期。
  • 怎么校验响应类型匹配 schema?答:按 schema 字段类型逐项断言 Python 类型,或用 schema 校验库解析响应。

04.7.17.3-044 契约测试在前后端协作中解决什么问题?

一句话结论

契约测试固化前后端约定:请求字段、响应结构、错误码、分页格式、版本兼容,接口变更先改契约再同步双方。DRF 侧用 OpenAPI schema 作为契约来源,测试验证后端响应符合契约;前端按 mock schema 开发,联调时校验真实接口。契约变更走评审,避免一方先改导致联调断裂。

概念解释

  • 契约是双方对数据结构与错误语义的共同约定。
  • 契约测试介于单元测试与端到端测试之间,聚焦接口边界。

原理流程

  1. 定义接口契约(schema/错误码/分页结构)。
  2. 后端测试验证响应符合契约,前端按契约 mock。
  3. 联调与 CI 校验契约一致,变更走评审同步。

代码或图示

schema 定义 → 后端响应测试 → 前端 mock 开发 → 联调校验 → CI 契约门禁

常见误区

  • 口头约定字段,前后端各自实现,联调才发现结构不一致;契约必须机器可读并纳入测试。
  • 后端随意改响应字段不更新 schema,前端页面静默报错;契约变更与代码同 PR 评审。

追问

  • 契约测试覆盖业务逻辑吗?答:不覆盖内部业务规则,只验证接口边界结构与约定语义。
  • OpenAPI 能作为前端 mock 依据吗?答:可以,按 schema 生成 mock 数据与类型定义。

04.7.17.3-045 drf-spectacular 如何接入与标注 schema?

一句话结论

drf-spectacular 从 DRF 视图与序列化器自动推导 OpenAPI 3 schema:配置 DEFAULT_SCHEMA_CLASS 为 SpectacularAutoSchema,提供 /schema/ 与 /schema/swagger-ui/ 端点;@extend_schema 装饰器手工标注请求/响应序列化器、参数、错误码与描述。自动推导覆盖常规 CRUD,复杂动作与动态序列化器用装饰器补充标注。

概念解释

  • spectacular 是 DRF 生态主流 OpenAPI 生成库,替代旧版 coreapi 方案。
  • schema 生成依赖序列化器字段声明,动态选择类需要显式标注。

原理流程

  1. 安装配置 spectacular 自动 schema 类。
  2. 扫描视图方法与序列化器推导 path/operation/参数/响应。
  3. @extend_schema 覆盖自动推导,生成 OpenAPI 文档与 UI。

代码或图示

from drf_spectacular.utils import extend_schema

class ArticleViewSet(viewsets.ModelViewSet):
    serializer_class = ArticleSerializer

    @extend_schema(
        request=ArticleWriteSerializer,
        responses={200: ArticleDetailSerializer},
        description="发布文章",
    )
    def publish(self, request, pk=None):
        ...

常见误区

  • 动态 get_serializer_class 返回多个序列化器,spectacular 只识别默认类,文档请求/响应类型缺失;用 @extend_schema 显式声明。
  • 自定义 @action 未标注参数与响应,OpenAPI 出现空 operation;补装饰器或配置内联标注。

追问

  • 安装后需要迁移吗?答:spectacular 不建表,只配置 schema 类与路由端点。
  • 怎么导出 OpenAPI 文件?答:CLI 或视图端点生成 schema.yml/schema.json,供前端生成类型与 mock。

04.7.17.3-046 OpenAPI 文档结构包含哪些核心对象?

一句话结论

OpenAPI 3 结构:paths 按 URL 路径组织,每个路径下按 HTTP 方法是 operation(操作描述、摘要、标签);parameters 声明路径/查询/头参数;requestBody 绑定请求 schema;responses 按状态码绑定响应 schema;components 复用可复用模式(序列化器模型)。DRF/spectacular 把视图动作映射为 operation,序列化器字段映射为 schema 属性。

概念解释

  • 路径与方法定位接口,schema 描述数据结构,两者分离复用。
  • 错误响应也应在 responses 中声明状态码与结构。

原理流程

  1. 路由器注册生成路径清单。
  2. 视图动作映射 operation 与参数。
  3. 序列化器推导 components schema,请求/响应引用对应模式。

代码或图示

paths:
  /articles/{pk}/:
    get:
      operationId: articleRetrieve
      parameters: [{name: pk, in: path, required: true}]
      responses:
        "200": {content: {application/json: {schema: {$ref: ArticleSerializer}}}}

常见误区

  • 只标注成功响应,错误码与字段细节不出现在文档;前端无法按契约处理 400/403。
  • 参数与序列化器字段重复定义且不一致;参数声明与模型字段保持同源。

追问

  • components/schemas 从哪来?答:序列化器自动推导,重复引用同一模型定义,避免模式复制。
  • 接口标签怎么分组?答:operation 的 tags 字段分组文档目录,装饰器可指定。

04.7.17.3-047 序列化器如何自动生成 schema,有哪些限制?

一句话结论

spectacular 遍历视图序列化器字段,按字段类型映射 OpenAPI 类型:字符串/整数/布尔/日期/嵌套对象/列表;read_only/write_only 分别归入响应或请求 schema;关系字段按主键或嵌套序列化器推导。限制:动态选择序列化器、SerializerMethodField 返回类型、手写 Serializer 字段、条件嵌套需要手工标注;source 重命名字段需确保文档键与输出一致。

概念解释

  • 自动推导依赖字段显式声明,反射不出方法内计算的返回结构。
  • 只读/只写标记自动区分请求与响应模型。

原理流程

  1. 读取视图 serializer_class 与字段声明。
  2. 字段类型映射 OpenAPI 类型与约束(长度、必填、可空)。
  3. 嵌套字段递归推导,无法推断处留空等待手工标注。

代码或图示

class ArticleSerializer(serializers.ModelSerializer):
    # MethodField 返回类型需在 schema 标注,否则推导为自由对象
    summary = serializers.SerializerMethodField()

    class Meta:
        model = Article
        fields = ["id", "title", "summary"]

常见误区

  • 依赖自动推导却在序列化器里动态改字段/返回结构,文档与实际响应漂移;复杂分支显式 @extend_schema。
  • 嵌套可写字段在请求 schema 中缺失,前端不知道可提交嵌套数据。

追问

  • write_only 字段出现在哪个 schema?答:请求体 schema,不进响应模型。
  • 枚举选项能自动推导吗?答:模型/字段 choices 可映射 schema 枚举值(待确认:推导覆盖程度以 spectacular 版本为准)。

04.7.17.3-048 哪些场景需要手工标注请求/响应 schema?

一句话结论

需要手工标注的场景:动态 get_serializer_class 返回多个序列化器;SerializerMethodField 或自定义字段返回复杂结构;@action 自定义动作无标准 CRUD 推导;请求与响应使用不同序列化器;文件上传/特殊媒体类型;错误响应结构需要显式声明。手工标注通过 @extend_schema 的 request、responses、parameters、examples 完成。

概念解释

  • 自动推导覆盖常规模型 CRUD,偏离约定的部分必须显式补全。
  • 标注同时服务文档阅读与前端类型生成。

原理流程

  1. 识别自动推导无法确定的操作与字段。
  2. 装饰器指定请求/响应序列化器或内联 schema。
  3. 补充参数、错误码与示例值。

代码或图示

@extend_schema(
    request=ArticleWriteSerializer,
    responses={201: ArticleDetailSerializer, 400: ArticleValidationErrorSerializer},
    parameters=[OpenApiParameter(name="tag", type=str, required=False)],
)
def create(self, request, *args, **kwargs):
    ...

常见误区

  • 只标注 200 响应,错误 schema 留空;前端错误处理无契约依据。
  • 手工标注的序列化器与实际使用类不同步,文档误导前端;标注类应与视图动态选择结果一致。

追问

  • 内联 schema 怎么写?答:@extend_schema 可传字典结构描述字段,不必总是引用序列化器类。
  • 示例值在哪里配?答:examples 或字段 default/help_text,文档展示示例请求与响应。

04.7.17.3-049 如何在 CI 中校验 schema 文档?

一句话结论

CI 中运行 spectacular 的 schema 生成校验命令(如 spectacular 命令导出 schema 并校验无错误),确保视图/序列化器改动后 OpenAPI 仍可生成、无未解析引用;可把导出的 schema 纳入版本管理或发布给前端。schema 生成失败(字段类型无法推断、引用缺失)应阻断合并,防止文档与接口脱节。

概念解释

  • 校验在构建期发现 schema 问题,而不是前端联调时才暴露。
  • 导出文件可作为契约产物交付前端生成类型与 mock。

原理流程

  1. CI 安装项目依赖与 spectacular。
  2. 运行 schema 生成/校验命令,检查退出码与警告。
  3. 失败阻断流水线;成功可上传 schema 产物。

代码或图示

# 生成并校验 OpenAPI schema(命令名以所装 spectacular 版本为准)
python manage.py spectacular --file schema.yml --validate

常见误区

  • 本地手写文档不跑生成校验,序列化器改名/删字段后文档仍引用旧结构。
  • 把 schema 警告当信息忽略;未解析引用与类型缺失应作为问题修复。

追问

  • schema 文件要提交仓库吗?答:可提交作为契约快照,或 CI 生成后分发给前端;策略团队约定。
  • 怎么校验响应与 schema 一致?答:运行时一致性测试比对实际响应,CI 命令保证 schema 可生成。

04.7.17.3-050 MultiPartParser/FormParser 与文件字段如何配合?

一句话结论

MultiPartParser 解析 multipart/form-data,支持文件与表单字段混合上传,request.FILES 保存上传文件;FormParser 解析 application/x-www-form-urlencoded 纯表单。文件上传接口视图需挂对应解析器,序列化器用 FileField/ImageField 接收;JSON 接口挂 JSONParser,不解析文件。解析器按请求 Content-Type 由内容协商选择。

概念解释

  • 解析器决定 request.data 的构造方式,文件对象进入 request.FILES。
  • 一个视图可挂多个解析器,按 Content-Type 匹配。

原理流程

  1. 请求携带 multipart/form-data。
  2. MultiPartParser 解析字段与文件,填充 request.data/request.FILES。
  3. 序列化器文件字段校验上传对象,保存时写入存储后端。

代码或图示

from rest_framework.parsers import MultiPartParser, FormParser

class UploadView(APIView):
    parser_classes = [MultiPartParser, FormParser]

    def post(self, request):
        file = request.FILES["attachment"]
        ...

常见误区

  • 文件接口只挂 JSONParser,request.FILES 为空,文件字段校验报缺失。
  • 上传 JSON 字段与文件混在 multipart 里,嵌套 JSON 需字段内字符串解析;复杂嵌套建议单独 JSON 接口。

追问

  • 解析器全局在哪配?答:DEFAULT_PARSER_CLASSES,视图 parser_classes 覆盖。
  • request.data 与 request.FILES 关系?答:表单字段在 data,文件对象在 FILES,序列化器文件字段从 FILES 取值。

04.7.17.3-051 FileField/ImageField 上传如何校验与限制大小?

一句话结论

FileField 校验文件对象类型与空值,ImageField 额外校验是否为可识别图片并可取尺寸;大小限制可在字段 max_length(存储名长度)或校验器/视图层检查 uploaded_file.size。Django 模型层可用 FileExtensionValidator、validate_image_file 限制扩展名与内容;上传大小还受 Django DATA_UPLOAD_MAX_MEMORY_SIZE 与服务端限制约束。

概念解释

  • 扩展名校验不等于内容校验,文件头/内容仍需检查防伪造。
  • 图片字段依赖 Pillow 解析图片格式。

原理流程

  1. 上传文件进入序列化器文件字段。
  2. 字段校验空值、类型;ImageField 解析图片尺寸格式。
  3. 大小/扩展名/内容校验通过后保存到存储后端。

代码或图示

from rest_framework import serializers
from django.core.validators import FileExtensionValidator

class AttachmentSerializer(serializers.Serializer):
    file = serializers.FileField(
        validators=[FileExtensionValidator(allowed_extensions=["pdf", "png", "jpg"])]
    )

    def validate_file(self, value):
        if value.size > 10 * 1024 * 1024:
            raise serializers.ValidationError("文件不能超过 10MB")
        return value

常见误区

  • 只校验扩展名,上传伪造后缀的恶意文件;图片/文档应校验文件头内容。
  • 限制大小只在前端做,后端不校验,绕过前端即可上传超大文件占满存储。

追问

  • ImageField 必装 Pillow 吗?答:是,图片解析与尺寸读取依赖 Pillow。
  • 上传大小全局限制在哪?答:Django DATA_UPLOAD_MAX_MEMORY_SIZE 控制内存阈值,超出落临时文件;代理层也有上传体积限制。

04.7.17.3-052 上传请求在什么时机被解析?request.FILES 如何填充?

一句话结论

DRF Request 惰性解析:首次访问 request.data 时,内容协商选出解析器,解析器按 Content-Type 解析请求体,表单字段进 data,上传文件进 FILES。文件对象是 UploadedFile 封装(name/size/content_type/chunks()),内存或临时文件存储由 Django 阈值决定。序列化器文件字段从 request.FILES 取值校验。

概念解释

  • 惰性解析避免不需要 body 的请求无谓读取请求体。
  • 大文件超过内存阈值写入临时文件,chunks() 流式读取。

原理流程

  1. 视图访问 request.data 触发解析。
  2. 解析器拆分 multipart 部件,普通字段入 data,文件部件封装 UploadedFile 入 FILES。
  3. 序列化器读取文件对象校验并保存。

代码或图示

def post(self, request):
    upload = request.FILES.get("file")
    if upload is None:
        raise serializers.ValidationError("缺少文件")
    serializer = AttachmentSerializer(data=request.data)
    serializer.is_valid(raise_exception=True)

常见误区

  • 视图在解析前读取 request.FILES,此时尚未填充;访问顺序应先触发 request.data 或直接经序列化器。
  • 把整个上传文件读进内存(read() 全量),大文件撑爆内存;大文件用 chunks() 分块写出。

追问

  • UploadedFile 有哪些属性?答:name 原始文件名、size 字节数、content_type、charset 与 chunks() 迭代方法。
  • 文件存哪由谁决定?答:Django 存储后端配置(本地/对象存储),序列化器保存时按模型字段存储路径写入。

04.7.17.3-053 大文件上传有哪些注意事项?

一句话结论

大文件避免同步全量读入内存:用 chunks() 分块写出到存储;控制单文件与总上传大小,配合临时文件阈值;超大文件采用分块上传(前端切片、后端合并)或对象存储直传,服务端只接收元数据。注意超时设置、磁盘/对象存储容量、病毒扫描与文件类型校验;同步接口只处理小文件,大文件走异步或直传链路。

概念解释

  • 在线请求有超时与内存上限,GB 级文件不应经应用服务器中转。
  • 分块上传支持断点续传与失败重试,合并时校验完整性。

原理流程

  1. 小文件:multipart 上传 → 校验 → 存储后端保存。
  2. 大文件:前端切片上传分块 → 服务端暂存 → 校验合并 → 登记元数据。
  3. 超大文件:客户端直传对象存储,后端签发临时凭证。

代码或图示

def save_upload(uploaded, destination):
    with open(destination, "wb") as f:
        for chunk in uploaded.chunks():
            f.write(chunk)

常见误区

  • 应用服务器中转大文件再转存对象存储,带宽与内存翻倍占用;应直传或走流式。
  • 分块上传不校验文件总数与大小上限,恶意分块耗尽存储;合并前配额检查与类型校验。

追问

  • 分块上传状态怎么记录?答:临时目录/元数据表记录块归属、序号、校验值,合并后清理。
  • 服务端超时怎么配?答:同步接口控制文件大小上限,大文件改异步任务或直传,避免请求挂死。

04.7.17.3-054 常见坑:context 未传导致 request 缺失

一句话结论

在视图外独立实例化序列化器(测试、脚本、命令、服务层)时,若不传 context={"request": request},self.context 为空字典,访问 self.context["request"] 抛 KeyError;CurrentUserDefault、超链接字段、依赖请求的方法字段同时失效。视图内经 get_serializer 会自动装配上下文;脱离视图必须显式传入所需上下文键。

概念解释

  • context 是序列化器与请求层的通道,视图装配与手动构造两条路径。
  • 嵌套子序列化器共享父级上下文。

原理流程

  1. 视图 get_serializer_context 组装 request/view/format。
  2. 手动构造序列化器缺省上下文为空。
  3. 方法/默认值读取上下文键时缺失报错。

代码或图示

# 视图内:自动带上下文
ser = self.get_serializer(data=request.data)

# 视图外:必须显式传 context
ser = NoteSerializer(data=payload, context={"request": request})

常见误区

  • 测试里 Serializer(data=...) 不传 context,CurrentUserDefault 取不到用户,创建接口报 500。
  • 在序列化器方法里把 request 对象放进 validated_data 持久化;上下文只读使用,只取需要的标量值。

追问

  • 上下文能补哪些键?答:除默认 request/view/format,可注入业务对象、配置等,在 get_serializer_context 统一补充。
  • 子序列化器会自动拿到上下文吗?答:共享父级传入的同一上下文字典。

04.7.17.3-055 常见坑:source='*' 的嵌套映射与限制

一句话结论

source="*" 把整个父对象传给字段(通常是嵌套序列化器),子序列化器按自己的字段列表读取父实例;适合把模型按职责拆成多组字段复用。限制:反序列化时嵌套数据不会自动拆回父模型多个属性,跨表/多字段更新需手动解包;子父字段重复声明会产生键冲突;取值链路为 None 时易触发属性异常。

概念解释

  • 普通 source 是属性路径,"*" 是整对象语义。
  • 多用于表示层分组,不用于级联写入。

原理流程

  1. 输出:get_attribute 遇 "*" 返回当前实例给子序列化器。
  2. 子序列化器在实例上取值表示。
  3. 输入:嵌套字典进入父级 validated_data,默认保存实现不解包。

代码或图示

class ProfileSerializer(serializers.ModelSerializer):
    class Meta:
        model = User
        fields = ["nickname", "avatar"]

class UserSerializer(serializers.ModelSerializer):
    profile = ProfileSerializer(source="*")

    class Meta:
        model = User
        fields = ["id", "username", "profile"]

常见误区

  • 以为 source="*" 嵌套字段可级联更新父模型多字段;默认 update 只做标量 setattr,嵌套字典需手动处理。
  • 子序列化器字段与父级 Meta.fields 重复,输出与校验键冲突,需核对字段归属。

追问

  • source="*" 输出什么结构?答:子序列化器 to_representation 产出的嵌套字典。
  • 什么时候用它优于普通嵌套?答:一个模型按职责拆组、分组复用序列化器时。

04.7.17.3-056 常见坑:partial=True 误用与 PATCH 语义

一句话结论

partial=True 临时关闭字段必填检查,用于 PATCH 部分更新:只提交需要改的字段,未传字段保持原值。误用场景:PUT 全量更新也加 partial=True,缺失字段被跳过,破坏全量替换语义;创建接口加 partial 无意义。partial 只放宽必填,不改类型校验与只读标记;已传值仍走完整校验。

概念解释

  • PUT 语义全量替换,PATCH 语义部分更新,两者校验要求不同。
  • 未传的可选字段在 validated_data 中缺失,保存时不更新对应属性。

原理流程

  1. PATCH 实例化序列化器传 instance, data, partial=True。
  2. 校验阶段跳过未传字段的必填检查。
  3. update 只更新 validated_data 中出现的字段。

代码或图示

# PATCH
ser = ArticleSerializer(instance=article, data=request.data, partial=True)
# PUT:全量更新,不加 partial
ser = ArticleSerializer(instance=article, data=request.data)

常见误区

  • PATCH 接口把所有字段当可选,误把可空值写成缺省;未传与显式传空语义不同,业务区分处理。
  • 以为 partial=True 能跳过只读字段写入;只读标记独立,只读字段仍不参与保存。

追问

  • partial 能在序列化器类默认设置吗?答:可在构造/视图层控制,标准做法是按 HTTP 方法在动作内传入。
  • 部分更新后未传字段会被清空吗?答:不会,validated_data 不含该键,update 不触碰对应属性。

04.7.17.3-057 常见坑:save() 如何判断走 create 还是 update?

一句话结论

serializer.save() 依据实例化时是否传入 instance 分发:有 instance 调 update(instance, validated_data),无 instance 调 create(validated_data)。忘记在更新接口传 instance,save() 会走创建产生重复记录;把已有实例误当新数据提交是常见线上问题。save(**kwargs) 传入的额外参数先合并进 validated_data 再分发。

概念解释

  • 分发依据是 self.instance,与 HTTP 方法无关;PATCH/PUT 都要传实例。
  • ModelSerializer 默认实现按字典构造或更新模型。

原理流程

  1. 构造序列化器记录 instance 与 data。
  2. 校验通过后 save 合并额外参数。
  3. 按 instance 是否存在调 create 或 update。

代码或图示

# 更新:必须传 instance
ser = ArticleSerializer(article, data=request.data, partial=True)
ser.is_valid(raise_exception=True)
ser.save()  # 走 update

# 创建:不传 instance
ser = ArticleSerializer(data=request.data)
ser.is_valid(raise_exception=True)
ser.save()  # 走 create

常见误区

  • 更新视图漏传 article 实例,重复插入新记录;代码评审检查更新动作的序列化器实例化参数。
  • 同一序列化器实例二次 save(),已有 instance 时仍走 update,不会新建;需要新建要重新实例化。

追问

  • save() 传的额外参数进哪?答:合并进 validated_data,供 create/update 使用。
  • 怎么确认走了哪个分支?答:调试 self.instance 是否为 None,或在 create/update 内断点/日志。

04.7.17.3-058 常见坑:嵌套可写序列化器忘记实现 create/update

一句话结论

嵌套字段默认只读友好:反序列化得到嵌套 validated_data,但父级默认 create/update 不识别嵌套结构,不会级联保存子对象。要支持嵌套写入,必须在父序列化器实现 create/update:pop 嵌套数据,新建/更新/解绑子对象并挂接;多对多、一对多策略各不相同。忘记实现时嵌套数据被忽略,子记录不入库且不报错。

概念解释

  • 不可写根源是关联语义模糊:新建、更新、解绑策略框架无法推断。
  • 级联保存需要事务包裹,部分失败回滚。

原理流程

  1. 嵌套字段反序列化得到子级 validated_data。
  2. 父级 create/update 取出嵌套数据。
  3. 按关联类型新建/更新/挂接/解绑子对象。

代码或图示

class PostSerializer(serializers.ModelSerializer):
    comments = CommentSerializer(many=True)

    def create(self, validated_data):
        comments = validated_data.pop("comments")
        post = Post.objects.create(**validated_data)
        Comment.objects.bulk_create([Comment(post=post, **c) for c in comments])
        return post

常见误区

  • 只声明嵌套序列化器就以为可写,提交的子数据静默丢弃;写入路径必须实现保存逻辑。
  • 嵌套级联保存不开事务,父成功子失败留下脏数据;批量级联放 transaction.atomic。

追问

  • 嵌套更新如何区分新建与已有?答:子数据带主键则更新,无主键则新建,被移除的关联按需解绑,规则在 update 中实现。
  • 第三方库能自动处理吗?答:drf-writable-nested 等可生成嵌套保存逻辑(待确认:版本与 DRF 兼容性按项目验证)。

04.7.17.3-059 常见坑:SerializerMethodField 访问关联对象引发 N+1

一句话结论

SerializerMethodField 每行调用一次方法,方法内访问 obj.relation.all()、外键对象或反向集合时,若查询集未预加载,每个对象触发一次查询,形成 N+1。修复:视图查询集按关联类型 select_related/prefetch_related,或用 SQL 注解把聚合值算好;方法内只读已加载属性,不做查库动作。

概念解释

  • MethodField 是派生值计算点,也是隐藏 N+1 的高发位置。
  • 派生聚合优先数据库注解,避免 Python 循环内逐条查询。

原理流程

  1. 列表序列化逐行回调方法。
  2. 方法访问关联属性,未预加载则回表查询。
  3. N 个对象产生 N 次关联查询;预加载后关联数据已在对象缓存。

代码或图示

class OrderSerializer(serializers.ModelSerializer):
    item_count = serializers.SerializerMethodField()

    def get_item_count(self, obj):
        return obj.items.count()  # 未预加载/注解时每行一次 COUNT

常见误区

  • 以为 MethodField 只读本地字段不会查库;方法内任何关联访问都可能触发查询。
  • 用 prefetch 加载集合后在方法内 len(obj.items.all()),重复访问已缓存集合尚可,但 count() 仍可能发查询;优先注解聚合。

追问

  • 聚合值最佳实践是什么?答:查询集 annotate(count=Count("items")),方法直接读注解属性。
  • 怎么确认 MethodField 引发 N+1?答:开查询计数,对比有/无该字段的 SQL 数量变化。

04.7.17.3-060 综合:一次接口故障按什么清单排查?

一句话结论

排查清单按分层展开:先看状态码定位层——401 查认证凭证/类配置,403 查权限与归属过滤,429 查限流缓存与阈值,400 查序列化校验错误字段,404 查查询集过滤与主键,500 查异常日志与堆栈。再查数据:查询集归属过滤、N+1 与索引、分页参数;最后查序列化器:字段映射、上下文、嵌套保存与响应结构。按链路从横切到数据到表示逐层缩小范围,避免一上来改业务代码。

概念解释

  • 故障定位先分层后定位点,状态码是第一层路由信号。
  • 每个层有对应验证手段:日志、查询计数、测试用例、schema 比对。

原理流程

  1. 记录请求状态码、响应体、请求参数与身份。
  2. 按状态码进入认证/权限/限流/校验/对象/服务端分支排查。
  3. 数据与表示层复核查询集、预加载、分页、序列化器上下文与保存逻辑。

代码或图示

401 → 认证类 / 凭证 / request.user
403 → 权限类 / 对象归属 / 查询集过滤
429 → 限流缓存 / 阈值 / key
400 → 校验字段错误 / 输入类型
404 → 过滤查询集 / 主键存在性
500 → 异常堆栈 / 上下文缺失 / 未处理异常

常见误区

  • 跳过状态码分层直接读业务代码,在错误的层反复修改;先用响应码缩小范围。
  • 只在本地复现成功,忽略数据归属、缓存状态、限流计数等环境因素;复现要核对环境数据与缓存。

追问

  • 接口慢按什么顺序查?答:先 SQL 数量与扫描行数,再序列化 CPU 与响应体积,最后下游调用与缓存命中。
  • 故障怎么留痕?答:记录请求 ID、身份、参数、状态码、查询数与异常堆栈,便于复盘回归测试。

本节高频题

  • 异常处理链与 APIException(001、002、005)
  • 统一错误结构与错误码(004、008)
  • 401/403/404 语义(006、007、023 对照第二页)
  • 版本策略与兼容字段(011、012、013、015、016)
  • N+1 复现与预加载(018、019、020、059)
  • 序列化开销与字段裁剪(021、024)
  • 分页必要性与计数查询(023、025)
  • 缓存失效与批量写入(026、028)
  • 索引与查询性能工具(029、030)
  • 序列化器 vs Pydantic 与 DRF 适用边界(031、032、033)
  • APIClient/APITestCase 与认证测试(035、036、039)
  • 分页过滤测试与限流缓存清理(040、041)
  • OpenAPI/spectacular 标注与 CI 校验(045、046、047、048、049)
  • 文件上传解析与大文件注意(050、051、052、053)
  • 常见坑:context/source/partial/instance/嵌套保存(054、055、056、057、058)
  • 故障排查清单(060)