说实话这两年我经手过不少后端项目最常被问到的一个问题就是团队想快速搭一套API用 Django Rest Framework简称 DRF到底行不行我的回答一般都很直接如果你的业务是基于 Django 或 ORM 那一套延续下来的DRF 几乎是当下最顺手的选择之一。它不是一个简单的工具库而是一整套把“数据模型”变成“可对外服务的 API”的工程化方案。这篇文章我打算用自己做过的项目经验把 DRF 构建 API 这件事从选型、环境搭建、序列化器设计、视图层组织到认证权限、限流、对接第三方大模型 API、上线前检查这些环节完整捋一遍。目标读者有三类刚接触后端、想系统了解 DRF 的同学已经在用 Django、准备给现有项目加 API 的开发者以及想少踩坑、想知道真实项目里哪些环节最容易出问题的中小团队。咱们不聊空理论每一步都是能直接照着操作的东西。1. 为什么选 Django Rest Framework而不是 Flask 或 Node很多人一开始纠结的点往往是Flask 轻、Node 快为什么非要挑 DRF我的经验是工具没有绝对优劣关键看你的业务底座在哪里。1.1 DRF 的核心价值是“把 API 开发变成业务梳理”DRF 的最大优势是它站在 Django 的肩膀上。Django 提供了 ORM、Admin、迁移机制、认证体系而 DRF 把这些能力无缝延伸到 API 层。你定义好数据模型DRF 的 ModelSerializer 能直接帮你生成字段映射ModelViewSet 能帮你把 CRUD 操作映射成标准的 HTTP 方法DefaultRouter 能自动生成 URL 路由。这一套组合下来我的体感是一部分纯增删改查的接口写代码的时间能压缩到原来的三分之一。举个例子我之前给一个电商数据分析平台做后端。里面有一个“商品”模型包含名称、类目、价格、库存、上架状态这些字段。传统写法需要手动写序列化、写列表视图、写详情视图、写路由用 DRF模型一定义好ModelSerializer 加 ModelViewSet 加一个 Router 注册基础接口几分钟就能跑起来。而且它自带的 Browsable API 页面还能直接在线调试前后端联调时省了非常多沟通成本。1.2 DRF 的几个“杀手级”组合模块我一般给新人介绍 DRF会重点提这六个模块Serializer序列化器负责模型实例和 Python 字典、JSON 之间的双向转换同时承担输入校验。ViewSet 与 Router把同类资源的 list、create、retrieve、update、destroy 集中在一处维护路由自动生成。认证与权限内置 Session、Token、JWT需第三方包认证权限类可以精确控制到”谁能看、谁能改“。Throttling限流内建多种限流策略防止接口被刷。Filtering过滤配合 django-filter能轻松实现按字段筛选。可扩展的渲染与文档默认支持 JSON、Browsable API配合 drf-spectacular 可以生成 OpenAPI 文档。这些模块不是生硬的拼凑而是围绕“API 开发全流程”设计的所以用起来逻辑统一几乎不用在框架之间做胶水代码。1.3 什么时候不必硬上 DRF我也要泼一点冷水。如果项目只是一两个轻量接口、没有用户体系、也不需要 ORM那 DRF 确实有点“杀鸡用牛刀”。还有纯微服务场景服务间内部调用如果只暴露一两个小接口用 FastAPI 可能更轻快。DRF 比较适合“业务模型集中、数据关系复杂、需要长期演进”的项目例如后台管理系统、电商平台、内容平台、企业级 SaaS。这类系统模型关联多、权限逻辑复杂DRF 的生态优势会非常明显。2. 从零搭建一个 DRF 项目先把底子打稳聊完选型直接进入实操。我会用一套我自己项目里常用的工程化布局而不是 Django 默认的“随手建个 app 全往里塞”的方式。2.1 环境准备和依赖安装我建议用 Python 3.10 以上的版本Django 4.2 LTS 或 Django 5.xDRF 对应版本直接装最新的稳定版即可。推荐用虚拟环境隔离依赖避免污染系统 Python。# 创建虚拟环境 python -m venv venv source venv/bin/activate # Windows 下是 venv\Scripts\activate # 安装核心依赖 pip install django djangorestframework django-filter drf-spectacular # 如果要做 JWT 认证 pip install djangorestframework-simplejwt # 如果要用 PostgreSQL pip install psycopg[binary]这里有个我踩过的小坑不要一上来就直接pip install django装最新大版本有些第三方库可能还没跟上。稳妥做法是先确定 Django 版本再装配套的 DRF 版本。实际项目里我遇到过 DRF 版本和 Django 版本不兼容导致序列化器报错的情况排查了半天最后发现是版本组合问题。2.2 项目目录与职责划分创建项目后我习惯把目录结构调整成下面这样。不要迷信 Django 默认的 app 结构工程上线后你会后悔的。project/ ├── config/ # 项目配置目录 │ ├── settings/ │ │ ├── base.py # 公共配置 │ │ ├── dev.py # 开发环境 │ │ └── prod.py # 生产环境 │ ├── urls.py │ └── asgi.py / wsgi.py ├── apps/ │ ├── users/ # 用户模块 │ ├── products/ # 商品模块 │ └── orders/ # 订单模块 ├── utils/ # 通用工具封装 ├── requirements.txt └── manage.py这样拆的核心原因是一个中型 API 项目通常有用户、订单、商品、支付、消息等模块把它们集中到apps目录下每个 app 只负责自己的领域逻辑后续加功能、做权限隔离都不费劲。你不需要一开始就做得特别“企业级”但至少别把接口逻辑全写在views.py一个文件里。2.3 settings 里必须配置的关键项DRF 的正确打开方式是在INSTALLED_APPS里注册然后在REST_FRAMEWORK字典里定义全局行为# config/settings/base.py 部分摘录 INSTALLED_APPS [ # Django 自带 django.contrib.admin, django.contrib.auth, # 第三方 rest_framework, django_filters, drf_spectacular, # 业务模块 apps.users, apps.products, ] REST_FRAMEWORK { DEFAULT_AUTHENTICATION_CLASSES: [ rest_framework.authentication.SessionAuthentication, rest_framework_simplejwt.authentication.JWTAuthentication, ], DEFAULT_PERMISSION_CLASSES: [ rest_framework.permissions.IsAuthenticated, ], DEFAULT_FILTER_BACKENDS: [ django_filters.rest_framework.DjangoFilterBackend, ], DEFAULT_PAGINATION_CLASS: utils.pagination.StandardPageNumberPagination, PAGE_SIZE: 20, DEFAULT_SCHEMA_CLASS: drf_spectacular.openapi.AutoSchema, EXCEPTION_HANDLER: utils.exceptions.custom_exception_handler, }这组配置看起来简单但每一行都有背后逻辑。比如默认权限设为IsAuthenticated等于给所有接口上了一道基础锁防止你“忘记加权限”导致敏感数据裸奔。默认分页类接入统一分页器是为了保证所有列表接口返回结构一致。EXCEPTION_HANDLER是自定义异常处理入口后面我会专门讲。3. 序列化器设计把数据变成 API 的语言序列化器是 DRF 的心脏。很多人把序列化器等同于“一个把模型转 JSON 的工具”但实际项目里序列化器还负责输入校验、字段裁剪、嵌套关系处理和性能控制。3.1 ModelSerializer 和 Serializer 怎么选我通常的决策规则很简单接口字段和模型字段高度一致时用 ModelSerializer接口字段和模型字段差异很大、或者输入输出结构完全不一样时用 Serializer。ModelSerializer 的好处是自动生成字段、自动生成create和update逻辑。比如商品列表# apps/products/serializers.py from rest_framework import serializers from .models import Product class ProductListSerializer(serializers.ModelSerializer): category_name serializers.CharField(sourcecategory.name, read_onlyTrue) sales_count serializers.IntegerField(read_onlyTrue) class Meta: model Product fields [id, name, price, stock, category_name, sales_count]注意category_name这个字段是“由模型关联字段派生出的展示字段”它不属于模型本身但通过read_onlyTrue只读输出前端拿到的是直接能展示的字符串不用再做二次处理。这是我在 API 设计里非常推荐的一种做法能少让前端做一件事就少做一件事。3.2 读写分离输入和输出是两套序列化器小项目写一套序列化器也许够用但业务复杂后输入约束和输出结构往往差异巨大。比如创建商品时前端传过来的是行业编码你需要校验后保存成数据库编码输出给前端时行业编码又要转成可读的中文名称。这种情况我会拆分InputSerializer只定义前端允许传入的字段和校验规则不含业务派生字段。OutputSerializer只定义返回给前端的展示字段多数为只读。# apps/products/serializers.py class ProductCreateSerializer(serializers.ModelSerializer): category_code serializers.CharField(max_length32) class Meta: model Product fields [name, price, stock, category_code] def validate_price(self, value): if value 0: raise serializers.ValidationError(价格必须大于 0) return value def create(self, validated_data): category_code validated_data.pop(category_code) category Category.objects.filter(codecategory_code).first() if not category: raise serializers.ValidationError({category_code: 类目编码不存在}) return Product.objects.create(categorycategory, **validated_data)这样写的好处是职责清晰。前端看到创建接口只能传哪些字段后端校验也不会被输出逻辑干扰。后面业务调整时你只需要动对应的序列化器而不是在一个文件里改来改去。3.3 字段校验的三种层次我总结了下项目里校验通常分三层字段级校验例如价格必须大于 0、手机号格式是否正确用validate_字段名方法。对象级校验例如创建订单时余额和商品库存要同时满足条件用validate方法。数据库唯一性校验例如用户名、邮箱不能重复在 Meta 里加unique_together或模型层约束序列化器能自动检查并返回 400。一个需要注意的细节是校验里的“语义校验”和“格式校验”要分开。比如手机号格式用正则校验但“该手机号是否已注册”属于业务校验可能还要查数据库。这两种校验的失败场景不同返回给前端的提示也应该不同。我在项目里会统一使用中文错误提示并附上字段名方便前端直接定位。3.4 序列化器里的三个常见坑第一个坑是SerializerMethodField滥用。它能做自定义输出但如果里面每次查一次数据库接口很容易被 N1 查询拖垮。比如上面例子里的sales_count如果循环每个商品都执行一次聚合查询性能会肉眼可见地下滑。解决办法是提前在查询集上用annotate把统计值算好序列化器只负责取字段。第二个坑是字段泄露。曾见过有人直接fields __all__把内部模型的创建时间、内部备注全部暴露给前端。是否泄露取决于具体业务但从安全习惯上我建议永远显式列出字段。第三个坑是create和update重写时忘记pop掉非模型字段。上面代码里category_code就是从validated_data里弹出来的否则保存时 Django 会因为 Product 没有该字段而报错。4. 视图层实战从 APIView 到 ViewSetDRF 的视图层有几种写法最基础的是APIView进阶的是ViewSet再配合路由生成器。我的观点是基础资源接口优先用 ViewSet特殊业务接口用 APIView不要在同一个资源上混用多种风格。4.1 APIView 和 ViewSet 到底按什么标准选拿我自己负责过的一个项目举例商品浏览统计接口它不是标准的 CRUD而是 GET 进来后要同时做计数、返回最近浏览记录这个我用APIView写最直观。# apps/products/views.py 部分 from rest_framework.views import APIView from rest_framework.response import Response class ProductViewStatsAPIView(APIView): def get(self, request, product_id): # 先做业务校验 product get_object_or_404(Product, idproduct_id) stats {views: product.view_count, favorites: product.favorite_count} return Response(stats)但如果你要做的是商品完整的 CRUD那就用ViewSet。它能通过一个类同时处理 GET 列表、POST 创建、GET 详情、PUT 更新、DELETE 删除并且路由自动生成。这比写 5 个 APIView 子类效率高得多。4.2 ModelViewSet 和 Router 的快速落地商品资源我用下面这种方式组织# apps/products/views.py from rest_framework.viewsets import ModelViewSet from rest_framework.decorators import action from rest_framework.response import Response from .models import Product from .serializers import ProductListSerializer, ProductCreateSerializer class ProductViewSet(ModelViewSet): queryset Product.objects.select_related(category).all() lookup_field id def get_serializer_class(self): if self.action in (create, update, partial_update): return ProductCreateSerializer return ProductListSerializer action(detailTrue, methods[post], permission_classes[IsAuthenticated]) def favorite(self, request, idNone): product self.get_object() # 收藏逻辑... return Response({status: ok})这里有两个细节值得留意。第一get_serializer_class根据动作自动切换序列化器这正是我前面说的“读写分离”落地的位置。第二自定义的favorite动作用action装饰器挂在 Detail 上生成的路由是/products/{id}/favorite/语义清晰。4.3 ViewSet 中 queryset 的性能细节queryset写在哪里很关键。千万不要在ViewSet里直接写Product.objects.all()这种裸查询因为每次请求都会重新计算。更好的做法是class ProductViewSet(ModelViewSet): # 提前用 select_related 关联好 category避免每个商品查一次类目表 queryset Product.objects.select_related(category).all()这样在列表接口里前端要展示category_name后端不需要对每个商品单独发起一次类目查询。这个优化在很多项目里是性能提升最大的一个点。4.4 ViewSet 常见问题一个常见问题是lookup_field不匹配。默认是pk如果你用id或其他业务编号必须显式设置否则路由会和你预期不一致。另一个问题是自定义 action 忘记继承权限比如favorite动作如果不写permission_classes默认就会套用全局的IsAuthenticated这一点不一定是问题但你要清楚它到底用的是哪套权限。还有一点是路由命名冲突多个 app 下有相同 action 名时宁可自定义url_path避免混乱。5. 认证、权限、限流与版本控制API 开发到一定阶段最重要的就是安全和治理。DRF 把这四件事做成了统一配置但很多人实际项目里只用了默认值没有真正理解它们的组合逻辑。5.1 认证方式到底怎么选DRF 支持多种认证方式组合使用。我的建议是浏览器可调试的后台接口用 SessionAuthentication移动端和第三方客户端用 JWT。JWT 我用djangorestframework-simplejwt它开箱即用。配置上要注意的是ACCESS_TOKEN_LIFETIME和刷新令牌的时长。管理后台类项目access token 可以设短一点比如 30 分钟用 refresh token 刷新第三方对接的 API反而要长一点否则对方频繁刷新体验很差。我踩过的一个坑是刷新令牌没有做轮换导致用户在多个设备上登录时旧令牌刷新后仍然可以继续使用安全隐患不小。后来统一改成ROTATE_REFRESH_TOKENSTrue并让每次刷新返回新的 refresh token才算解决。5.2 权限控制内置类和自定义类权限和认证是两个概念。认证回答“你是谁”权限回答“你能不能做这件事”。DRF 内置了IsAuthenticated、IsAdminUser、AllowAny、IsAuthenticatedOrReadOnly。但真实业务往往需要更细的控制比如“文章只能作者本人修改”。这种情况我写自定义权限类# utils/permissions.py from rest_framework.permissions import BasePermission class IsOwnerOrReadOnly(BasePermission): def has_object_permission(self, request, view, obj): if request.method in (GET, HEAD, OPTIONS): return True return obj.user request.user然后在 ViewSet 里设置permission_classes [IsAuthenticated, IsOwnerOrReadOnly]。注意has_object_permission只对详情操作生效列表操作如果要过滤当前用户数据还要在get_queryset里做处理。5.3 限流配置别让接口被刷爆限流在公开 API 里特别重要。我推荐一套三层组合匿名用户限流每分钟 20 次防止爬虫。登录用户限流每分钟 100 次照顾正常业务。关键接口额外限流比如发送验证码每天 5 次防止短信轰炸。REST_FRAMEWORK { DEFAULT_THROTTLE_CLASSES: [ rest_framework.throttling.AnonRateThrottle, rest_framework.throttling.UserRateThrottle, ], DEFAULT_THROTTLE_RATES: { anon: 20/min, user: 100/min, send_code: 5/day, }, }需要提醒的是DRF 的限流默认存在内存缓存中多进程下可能不准。生产环境要配置上 Redis 缓存后端限流计数才不会随着进程重启而丢失。5.4 API 版本控制向前兼容的保命设计API 版本控制我建议从第一天就开始做。最常用的两种方式URL 路径版本/api/v1/products/、/api/v2/products/请求头版本Accept: application/json; version2.0我更推荐 URL 路径版本因为它直观、容易调试第三方开发者也不容易传错。实现时在urls.py里用一个router注册两套版本或者简单点直接path(api/v1/, include(...))。这样后面接口破坏性更新时老版本接口还能跑一段时间给调用方留出升级时间。6. 过滤、搜索、排序、分页把接口变得真正可用这一部分很容易被忽略但它是“接口好不好用”的关键。一个列表接口如果不能筛选前端就只能在客户端做内存过滤数据一大就卡死。6.1 django-filter 的接入方法安装django-filter后在REST_FRAMEWORK里配置DEFAULT_FILTER_BACKENDS然后在 ViewSet 里定义filterset_fieldsclass ProductViewSet(ModelViewSet): filter_backends [DjangoFilterBackend, SearchFilter, OrderingFilter] filterset_fields [category, is_active, price] search_fields [name, description] ordering_fields [created_at, price, sales_count]这样前端就能直接请求/api/v1/products/?category3price19.9search手机ordering-sales_count不需要你手动写任何筛选逻辑。还有一个进阶写法是自定义FilterSet处理“价格区间、日期范围”这类复杂筛选Django-filter 官方文档写得很清楚项目里按需引入即可。6.2 搜索和排序的注意事项search_fields里面如果加了关联字段如category__name模糊搜索会带来额外的表连接开销。数据量大时建议配合数据库全文索引或者对搜索词做长度限制。排序字段ordering_fields也是白名单机制不要开放给前端任意字段尤其不要开放那种带敏感信息的内部字段。我曾见过前端把ordering-last_login当成合法参数传到用户列表接口虽然没造成事故但说明白名单控制是必要的。6.3 三种分页模式各自的适用场景DRF 自带三种分页类我分别用过PageNumberPagination按页码分页传page2page_size20适合后台管理但大页码时深度翻页性能较差。LimitOffsetPagination传limit20offset40适合以“跳过多少条”逻辑计算的业务比如移动端列表的“加载更多”。CursorPagination游标分页性能最好、数据重复率低但前端理解成本稍高多用于信息流、评论列表。我自己的默认选择是PageNumberPagination因为大多数业务方最熟。但一旦列表记录超过几万条深度翻页会很煎熬那时候我会换成CursorPagination。分页器最好做成一整套“自定义响应结构”不然每个接口分页返回格式不统一前端要做一堆兼容。6.4 过滤和性能的联动过滤条件是性能优化的“触发器”。当你允许category筛选时一定要保证数据库的category_id字段有索引。如果是复合筛选条件比如category is_active price可以考虑建立联合索引。我在项目里见过最典型的问题不是查询本身慢而是因为过滤条件导致 Django ORM 生成了大面积全表扫描加索引后接口从 1.8 秒掉到 300 毫秒。看日志、看慢查询、看执行计划这是 API 性能调优的日常工作。7. 对接第三方 API大模型、电商、短信、行情数据现在做 API 系统几乎不可能完全不调用外部服务。我接触过的项目里对接过电商平台 API、短信服务、云厂商接口、还有现在特别火的大模型 API。这一环节的共性经验非常有价值。7.1 密钥管理是第三方对接的第一条红线第三方 API 的密钥、AppSecret、Token 绝对不能硬编码在代码或配置文件里提交到仓库。我一般用环境变量或者单独的.env文件管理它们并在settings.py里统一读取# config/settings/base.py import os from dotenv import load_dotenv load_dotenv() LLM_API_KEY os.getenv(LLM_API_KEY) SMS_ACCESS_KEY os.getenv(SMS_ACCESS_KEY)密钥泄露最常见的后果是对方账上被刷出大额费用。我见过不止一次因为.env文件没有加入.gitignore导致密钥被提交到公开仓库的案例务必把这个文件当成最高优先级保护对象。7.2 统一封装一个 HTTP 客户端别让 request 满天飞项目里对接多个第三方最忌讳的是每一个接口都requests.post(...)写一遍代码重复率高出问题时排查困难。我习惯在utils里封装一个统一客户端# utils/http_client.py import time import requests class APIClient: def __init__(self, base_url, api_keyNone, timeout10, retries3): self.base_url base_url.rstrip(/) self.api_key api_key self.timeout timeout self.retries retries self.session requests.Session() if api_key: self.session.headers.update({Authorization: fBearer {api_key}}) def request(self, method, path, **kwargs): kwargs.setdefault(timeout, self.timeout) url f{self.base_url}/{path.lstrip(/)} for attempt in range(self.retries): try: response self.session.request(method, url, **kwargs) response.raise_for_status() return response.json() except requests.exceptions.Timeout: if attempt self.retries - 1: raise time.sleep(0.5 * (attempt 1)) except requests.exceptions.ConnectionError: if attempt self.retries - 1: raise time.sleep(1)这里有几个关键点设置超时时间、设置最大重试次数、用 Session 复用连接池。很多第三方 API 不稳定一次超时就抛异常会给前端带来极大的体验问题。重试策略也不是盲目重试——写操作要慎重因为可能同一请求被执行多次读操作可以安全重试。7.3 大模型 API 调用几个真实报错场景最近大模型 API 特别火很多团队都想把大模型能力接到自己业务里。我在实际项目里处理过不少调用大模型 API 时的错误这里列几个比较典型的第一个是400: This models maximum context length is 1048576 tokens...。这是提示词上下文太长超过了模型支持的 token 数量。解决办法不是无脑截断而是做内容裁剪先做摘要、只保留关键片段或者用向量数据库做相似度检索后只拼接最相关内容。这个错误在长文档分析场景里几乎一定会遇到。第二个是400: This organization has been disabled。这说明 API Key 对应的组织被停用或额度被关闭。要做的事很明确检查组织绑定关系、查看账户是否欠费、确认是否有权限上限而不是在代码层面折腾。第三个是Connection dropped (ECONNRESET)。这通常是连接被对方服务端重置。可能是网络链路问题也可能是并发数过高。合理设置连接池大小、加超时、加重试基本能缓解。第四个是No API key for provider route。这是配置层面问题往往是想要调用的模型路由对应的 API Key 没有配置好。我处理这类问题的思路永远是先验证单条请求能不能通再跑到业务代码里去排查配置读取顺序。还有一类更隐蔽的问题是 API 返回的 JSON 结构和文档不一致。大模型平台更新频繁接口偶发性的字段变更很容易造成解析失败。所以我每次对接都会先跑一个冒烟脚本把正常响应、错误响应都记录下来后面改代码时能快速对比。7.4 用 Celery 和 Redis 把第三方调用“异步化”很多第三方 API 响应慢大模型尤其明显可能要几十秒如果直接在 Django 视图里同步调用请求会一直阻塞用户体验极其糟糕。我的做法是把这类调用扔到 Celery 任务里接口先返回“任务已接收”前端再通过轮询或 WebSocket 获取结果。简单示例# utils/tasks.py from celery import shared_task from .http_client import APIClient shared_task(bindTrue, max_retries3) def call_llm_api(self, prompt): client APIClient(base_urlhttps://api.xxx.com) try: result client.request(POST, /v1/chat/completions, json{...}) return result except Exception as exc: raise self.retry(excexc, countdown60)这里self.retry(excexc, countdown60)是 Celery 自带的重试机制配合 Redis 做消息代理整个流程非常稳定。我一般是这样的调用链Django 视图收到请求 → 写入任务队列 → 立即返回任务 ID → Celery worker 处理任务 → 结果写回数据库或缓存 → 前端轮询获取。8. 错误处理、日志与上线前必须做的事接口上线不是写完代码就结束了。线上接口的稳定性、可排查性是决定这个项目后期运维成本的关键。我习惯把这部分当作“基础设施”来对待。8.1 自定义异常处理器统一错误返回格式DRF 默认的错误返回格式是{detail: ...}不同异常类型返回结构还不一样。前端处理起来很痛苦。所以我都会写一个自定义异常处理器# utils/exceptions.py from rest_framework.views import exception_handler from rest_framework.response import Response from rest_framework import status def custom_exception_handler(exc, context): response exception_handler(exc, context) if response is not None: return Response( { success: False, message: response.data.get(detail, 请求失败), errors: response.data, status_code: response.status_code, }, statusresponse.status_code, ) return Response( { success: False, message: 服务器内部错误, errors: None, status_code: status.HTTP_500_INTERNAL_SERVER_ERROR, }, statusstatus.HTTP_500_INTERNAL_SERVER_ERROR, )统一格式的好处非常明显前端只需要在 axios 拦截器里对success字段做一次判断所有错误弹窗、错误提示都能统一处理不用每个接口单独适配。这个习惯坚持下来前后端联调效率能提升不少。8.2 上线前必须过一遍的安全清单我每次上线前都会拿这份清单自查一遍DEBUG False否则错误堆栈会直接暴露给调用方。ALLOWED_HOSTS配置完整避免出现DisallowedHost异常或被伪造请求头绕过。数据库连接使用强密码并限制数据库账号的权限。关闭那些用不到的DEFAULT_PERMISSION_CLASSES别让数据裸奔。CORS_ALLOWED_ORIGINS只配置需要的前端域名不要用*通配。检查.env文件是否被.gitignore排除。确认限流、分页、认证配置在生产环境生效。数据库备份策略和迁移检查。这里面任何一项没做好上都可能出麻烦。我之前帮一个项目排查过上线后接口白屏问题最后发现就是ALLOWED_HOSTS少了当前域名Django 直接拒绝处理错误日志还特别不起眼。8.3 日志、慢查询和接口监控日志配置最基础的要求是把 Django 的请求日志、异常日志、SQL 日志分开按天切割方便排查。我常用 Python 的logging模块配合loguru做结构化日志。生产环境我还会接入django-silk来做接口性能分析。它能记录每个接口的耗时、SQL 执行次数和具体语句上线初期我会让后端团队每周看一次silk报告把所有慢接口列出来逐条优化。更进一步的方案是接入开源 APM比如 Prometheus Grafana 或 Sentry监控接口延迟、错误率和第三方调用失败率。这个根据团队规模按需使用但早期的“看日志 看 SQL”不能省。9. 常见问题与排查技巧速查表我在实际开发和帮别人看项目的过程中整理了一张高频问题速查表基本覆盖了 DRF 构建 API 时最常见的一类问题现象可能原因解决办法接口返回 403认证方式不对或权限类拒绝检查AuthenticationClasses、PermissionClasses以及是否配置了 JWT 认证接口返回 404路由没注册或 lookup_field 不一致检查 Router 注册、ViewSet 的lookup_field以及 URL 命名空间序列化器报Field name ... is not valid字段名拼写错误或字段不是模型字段检查序列化器字段是否存在是否漏写read_only列表接口很慢出现大量同结构 SQL典型的 N1 查询问题在queryset中用select_related和prefetch_related预加载关联字段更新接口总是把没有的字段置空前端只传部分字段但序列化器按全量更新处理前端改用 PATCH或把字段设为requiredFalse创建接口报AttributeErrorcreate方法里没有pop非模型字段重写create时清理validated_data限流不生效缓存后端配置有问题或多个 worker 进程各自计数配置 Redis 缓存检查DEFAULT_THROTTLE_RATES语法第三方 API 调用超时外部服务慢、网络不稳定、无超时设置HTTP 客户端统一设置 timeout 和重试必要时异步化出现ECONNRESET断连连接被对方重置可能是并发过高使用连接池、限制并发、增加重试机制大模型 API 报context length超限输入内容过长超过模型 token 上限做摘要、截断或采用向量化检索后再拼接API Key 相关报错密钥没配、被禁用或余额不足检查环境变量读取、账户状态、组织绑定关系这张表并不能覆盖所有问题但它能帮你做第一轮定位。遇到问题别急着改代码先看响应状态码、再看日志、再看数据库 SQL定位的层次越清楚修复越快。最后一说我个人在实际操作中最深的一个体会是DRF 构建 API 这件事难点从来不在框架本身而在于你是不是真的理解“接口就是产品”这句话。序列化器字段多写一个就多一份暴露风险查询集少一个 select_related 就多一分性能隐患认证权限配错一个类就可能导致数据泄露。框架给了你强能力也要求你负起责任。最后再分享一个小技巧如果你正在做一个长期项目一定从第一天就把接口文档、分页结构、错误码格式统一起来不要等前端来催。我见过太多团队因为接口结构不统一后期每个前端页面都写一堆 if 分支维护成本高到离谱。DRF 的序列化器、异常处理、分页器、版本控制都是帮你把这些“约定”固化成代码的绝佳工具。希望这篇文章能让你少走一些弯路把这些经验真正用到自己的项目里。