Django-RESTful Api设计风格
这篇讲什么
- 这篇是接口设计的约定清单:协议与域名、版本号放哪、路径怎么命名、HTTP 方法怎么用对、过滤排序分页怎么做、状态码和错误响应怎么定。
- 每条约定都配了 DRF 里的落地写法,能在本机验证的(分页、排序、状态码、格式后缀)都按 Django 5.2.19 + DRF 3.18.3 跑过。
协议与域名
-
协议:API 与用户的通信一律用 HTTPS。HTTP 明文会把令牌(Token)、会话 cookie 全暴露在链路上,等于没做认证。
-
域名:尽量把 API 部署在专用域名下,例如
https://api.example.com;如果 API 很简单、不会扩展,放在主域名的子路径(https://www.example.com/api/)也可以。 -
本项目里 API 挂在子路径上(实测路由写法):
proj/urls.py 1
2
3
4
5
6from django.urls import include, path
urlpatterns = [
path("admin/", admin.site.urls),
path("api/", include("school.urls")),
]
版本
-
版本要显式化,常见两种放法:放进 URL 路径(
/api/v1/students/)或放进请求头(Accept: application/json; version=1.0)。 -
DRF 把版本控制做成可插拔的类,实测
rest_framework.versioning里可用的有 5 个(外加基类):1
2AcceptHeaderVersioning, BaseVersioning, HostNameVersioning,
NamespaceVersioning, QueryParameterVersioning, URLPathVersioning版本类 版本写在哪 适用场景 URLPathVersioningURL 路径 v1/最常见,浏览器里一眼能看出来 NamespaceVersioningDjango 命名空间 每个版本一套 urls.py,隔离最彻底AcceptHeaderVersioningAccept头严格 REST 派,路径不变 QueryParameterVersioning?version=1.0调试方便,但污染查询串 HostNameVersioning域名 v1.api.example.com需要 DNS/网关配合 settings.py 1
2
3
4
5
6REST_FRAMEWORK = {
"DEFAULT_VERSIONING_CLASS": "rest_framework.versioning.URLPathVersioning",
"DEFAULT_VERSION": "v1",
"ALLOWED_VERSIONS": ["v1", "v2"],
"VERSION_PARAM": "version",
}一个实测坑:
override_settings(REST_FRAMEWORK=...)不会改变已经导入的视图行为——DRF 的APIView把filter_backends、pagination_class这类默认值在类定义时就绑成了类属性。要验证这类配置,得在视图上显式写,或者改完settings.py重启进程。
路径
- 路径表示资源的具体网址。每个 URI 代表一种资源,所以 URL 里不要有动词,只用名词,且名词一般与表名对应。
- 单数还是复数要统一(本项目统一用复数:
/api/students/、/api/students/1/)。 - 实测 DRF 生成的路由就是这种形状(
DefaultRouter注册StudentViewSet后):注意主键那段是1
2student-list ^vs/students/$
student-detail ^vs/students/(?P<pk>[^/.]+)/$[^/.]+而不是[^/]+:故意排除点号,好让格式后缀(.json)能被单独识别。 - 层级关系用路径表达,别用查询串:
/api/grades/1/students/(某班学生)优于/api/students?grade=1(后者适合过滤,不适合表达归属)。
使用正确的 HTTP 方法
-
HTTP 方法与 SQL 操作的对应关系:
方法 语义 对应 SQL 是否幂等 GET查 SELECT是 POST增 INSERT否 PUT全量改 UPDATE(整行)是 PATCH部分改 UPDATE(指定列)是 DELETE删 DELETE是 -
实测 DRF 各写法支持的方法集合:
1
2
3@api_view(["GET", "POST"]) 的视图收到 DELETE -> 405 | Allow: POST, GET, OPTIONS
mixins 只挂 list/create 时收到 PATCH -> 405
generics.RetrieveUpdateDestroyAPIView 收到 PATCH -> 200 | 只改传上来的字段Allow头是 405 的标配,客户端据此知道该换哪个方法。PATCH在 DRF 里对应serializer(..., partial=True)语义:必填字段可以缺省。
-
安全方法(不改状态)在权限里被单列出来,实测:
1
permissions.SAFE_METHODS: ('GET', 'HEAD', 'OPTIONS')
IsAuthenticatedOrReadOnly就是靠它判断「读放行、写要登录」。
过滤、排序、搜索、分页
-
资源多时不能一次全返回,要提供参数让客户端筛选。约定式的写法:
1
GET /api/students?grade=1&sex=true&search=张&ordering=-age&page=2&size=3
- 参数允许冗余:
/api/grades/1/students/?sex=true这种「路径 + 查询」重复是可以的。
- 参数允许冗余:
-
实测:光在视图上写
filterset_fields不生效,必须挂后端。 同一个视图类,一个显式写了filter_backends、一个没写:1
2
3
4
5
6本班过滤(显式写了 DjangoFilterBackend): 200 | 条数: 25
另一个班过滤: 200 | 条数: 0
search=pgx1: 200 | 条数: 3 | 第一条: pgx1
ordering=-age 前两条: [60, 60]
乱写 ordering: 200 | 条数: 25 # 非法值直接忽略,不报错
同一 search 参数打给没写 filter_backends 的视图: 200 | 条数: 25 # 参数被无视school/views.py 1
2
3
4
5
6
7
8
9
10
11
12from django_filters.rest_framework import DjangoFilterBackend
from rest_framework.filters import OrderingFilter, SearchFilter
from rest_framework.generics import ListAPIView
class FilteredStudents2(ListAPIView):
queryset = Student.objects.all()
serializer_class = StudentSerializer
filter_backends = (DjangoFilterBackend, SearchFilter, OrderingFilter)
filterset_fields = ("grade", "sex")
search_fields = ("name",)
ordering_fields = ("age", "name")django-filter本机版本 26.2;DRF 自带的只有SearchFilter/OrderingFilter(实测rest_framework.filters里还有UnaccentedSearchFilter),字段级过滤要靠DjangoFilterBackend。
-
分页同理,实测三种分页类的响应形状:
1
2
3
4
5
6
7
8PageNumberPagination: 200 | 键: ['count', 'next', 'previous', 'results'] | count: 25 | 本页: 3
next: http://testserver/api/paged/?page=2 | previous: None
第二页: 200 | 条数: 3
越界页 ?page=999: 404 | {'detail': 'Invalid page.'}
page_size_query_param(?size=5): 200 | 条数: 5
LimitOffsetPagination(?limit=3&offset=2): 键 ['count', 'next', 'previous', 'results'] | 条数: 3
CursorPagination: 键 ['next', 'previous', 'results'] # 没有 count
视图没写 pagination_class 时: 200 | 类型: ReturnList # 还是裸数组-
?page=999是 404(Invalid page.),不是空列表——前端要按 404 处理。 -
CursorPagination不返回总数,适合无限下拉;但它要求 queryset 有序,否则实测会打警告:1
2UnorderedObjectListWarning: Pagination may yield inconsistent results with an
unordered object_list: <class 'school.models.Student'> QuerySet.解决:模型
Meta.ordering或 queryset 上order_by("id")。
-
状态码
-
状态码是服务器给客户端的结论,光靠数字不够直观,DRF 提供了常量(实测
dir(rest_framework.status)里HTTP_*共 64 个):1
2
3HTTP_200_OK=200 HTTP_201_CREATED=201 HTTP_204_NO_CONTENT=204
HTTP_400_BAD_REQUEST=400 HTTP_401_UNAUTHORIZED=401 HTTP_403_FORBIDDEN=403
HTTP_404_NOT_FOUND=404 HTTP_405_METHOD_NOT_ALLOWED=405 HTTP_415_UNSUPPORTED_MEDIA_TYPE=415- 还有分类函数:
status.is_client_error(404)、status.is_success(204)、status.is_server_error(500)实测都是True。
- 还有分类函数:
-
本项目里实测到的真实对应关系:
场景 状态码 实测响应 新建成功 201 返回新对象 删除成功 204 响应体为空 校验失败 400 {"name": ["This field is required."]}请求体不是合法 JSON 400 {"detail": "JSON parse error - ..."}只配了 TokenAuthentication 且没带令牌 401 {"detail": "Authentication credentials were not provided."}默认(Session+Basic)下未登录写数据 403 {"detail": "You do not have permission to perform this action."}非资源所有者改数据 403 同上 资源不存在 404 {"detail": "No Student matches the given query."}方法不支持 405 带 Allow头Accept要的表现层没有406 — 401 与 403 的区别实测得很干净:有没有「认证类能接住你」决定 401/403。配了
TokenAuthentication时缺凭据是 401;只有 Session/Basic 时缺凭据是 403。
错误处理
-
4xx 一定要带出错信息,且结构要固定。DRF 的默认形状有两类:
- 视图层异常(
ValidationError、ParseError、NotFound…)走exception_handler,返回{"detail": "..."}; - 序列化器错误是按字段的字典:
{"字段名": ["消息", ...]}。
- 视图层异常(
-
实测原文:
1
2
3
4
5raise_exception=True: 400 | {"age": ["Ensure this value is greater than or equal to 0."]}
缺字段: 400 | {"name": ["This field is required."], "grade_name": ["This field is required."]}
方法不允许: 405 | {"detail": "Method \"GET\" not allowed."}
解析错误: 400 | {"detail": "JSON parse error - Expecting property name enclosed in double quotes: line 1 column 2 (char 1)"}
detail 不存在: 404 | {"detail": "No Student matches the given query."} -
一个反直觉的点(实测):视图里
return Response(serializer.errors, status=400)不走异常处理器,所以自定义EXCEPTION_HANDLER对它无效。想让所有错误形状统一,就在视图里用serializer.is_valid(raise_exception=True),把出错交给exception_handler:school/views.py 1
2
3
4
5class PlainView(APIView):
def post(self, request):
serializer = PlainSerializer(data=request.data)
serializer.is_valid(raise_exception=True) # 不合法就抛 ValidationError
return Response({"收到": serializer.validated_data})settings.py 1
REST_FRAMEWORK = {"EXCEPTION_HANDLER": "school.exceptions.my_exception_handler"}
school/exceptions.py 1
2
3
4
5
6
7
8from rest_framework.views import exception_handler
def my_exception_handler(exc, ctx):
response = exception_handler(exc, ctx)
if response is not None:
response.data = {"code": "bad_request", "detail": response.data}
return response
响应结果与超链接
-
约定每种操作的返回体:
GET /students/:资源列表(配了分页则是{count, next, previous, results})。GET /students/1/:单个资源对象。POST /students/:新建成功返回这个对象本身(201),方便前端拿到服务端生成的id。PUT/PATCH:返回更新后的对象。DELETE:204,不返回内容。
-
资源之间用链接关联,而不是只给裸 id。DRF 的
HyperlinkedModelSerializer实测:1
2
3
4不带 context: AssertionError `HyperlinkedIdentityField` requires the request in the
serializer context. Add `context={'request': request}` ...
带 context 仍报错: ImproperlyConfigured Could not resolve URL for hyperlinked
relationship using view name "student-detail". ...-
第一条好懂:超链接字段需要
request才能拼绝对地址。 -
第二条是命名空间坑(实测):应用的
urls.py里写了app_name = "school",路由真实名字是school:student-detail,而序列化器默认找student-detail,于是整个接口 500。要么去掉app_name,要么显式指定:1
2
3
4
5
6
7
8class StudentHyperSerializer(serializers.HyperlinkedModelSerializer):
class Meta:
model = Student
fields = ("url", "id", "name", "age", "grade", "owner")
extra_kwargs = {
"url": {"view_name": "school:student-detail"},
"grade": {"view_name": "school:grade-detail"},
}1
带命名空间反解: /api/vs/students/8/
-
-
一份「设计规范 ↔ DRF 落地」对照表:
规范条目 DRF 里的落地手段 只用 HTTPS 部署层 + SECURE_SSL_REDIRECT、SESSION_COOKIE_SECUREURL 无动词 Router/path()生成的 list/detail 路由版本显式化 versioning的 5 个版本类表现层协商 Accept/ 格式后缀 /DEFAULT_RENDERER_CLASSES过滤排序搜索 DjangoFilterBackend+SearchFilter+OrderingFilter分页 三种 Pagination类语义化状态码 rest_framework.status的 64 个常量统一错误结构 exception_handler+raise_exception=True资源互链 HyperlinkedModelSerializer(注意命名空间)接口文档 drf-spectacular生成 OpenAPI 3.0.3(见《Django-常用插件》)
新手卡点清单
-
都是实测踩过的:
卡点 症状(实测原文) 正确做法 只写 filterset_fields不挂后端参数完全被忽略,返回全量 视图上写 filter_backends,或 settings 配好再重启用 override_settings(REST_FRAMEWORK=...)验证过滤/分页行为没变(类属性在定义时已绑定) 显式写在视图类上 分页越界当空列表处理 404 {'detail': 'Invalid page.'}按 404 分支处理 分页 queryset 没排序 UnorderedObjectListWarning加 Meta.ordering或order_by("id")乱写 ordering参数不报错,静默忽略 前端只传 ordering_fields里的名字自定义 EXCEPTION_HANDLER后错误形状没变视图自己 return Response(errors)不走它用 is_valid(raise_exception=True)Hyperlinked 序列化器不带 context AssertionError ... requires the request in the serializer context传 context={"request": request}应用有 app_name还用裸名做超链接ImproperlyConfigured Could not resolve URL ... "student-detail"view_name="school:student-detail"以为缺凭据一定 401 只有 Session/Basic 时实测是 403 按认证类判断,401/403 都要处理
参考
- Django REST framework:Versioning:5 个版本控制类的官方说明。
- Django REST framework:Filtering:
SearchFilter、OrderingFilter与DjangoFilterBackend的挂法。 - Django REST framework:Pagination:三种分页类的响应结构。
- Django REST framework:Exceptions:
exception_handler与默认错误形状。 - Django REST framework:Serializers:
HyperlinkedModelSerializer与extra_kwargs。 - django-filter 项目主页:
filterset_fields/FilterSet的用法。