Khung công tác Django REST Tìm kiếm Trước Kế tiếp GitHub

Chế độ xem chung

Ví dụ
Tham chiếu API

Chế độ xem API chung

Mixin
Danh sáchMô hìnhMixin
TạoModelMixin
Truy xuấtModelMixin
Cập nhậtModelMixin
Phá hủyMô hìnhMixin
Các lớp xem cụ thể

TạoAPIView
Danh sáchAPIView
Truy xuấtAPIView
Phá hủy chế độ xem API
Cập nhậtAPIView
Danh sáchTạoAPIView
Truy xuấtUpdateAPIView
Truy xuấtTiêu hủyAPIView
Truy xuấtCập nhậtTiêu hủyAPIView
Tùy chỉnh chế độ xem chung

Tạo mixin tùy chỉnh

Tạo các lớp cơ sở tùy chỉnh
PUT khi tạo

Gói của bên thứ ba

Django Rest Nhiều mô hình

generics.py mixins.py

Chế độ xem chung

“
Các chế độ xem chung của Django... được phát triển như một lối tắt cho các kiểu
sử dụng phổ biến... Chúng sử dụng một số thành ngữ và mẫu phổ biến nhất định
được tìm thấy trong quá trình phát triển chế độ xem và trừu tượng hóa chúng để
bạn có thể nhanh chóng viết các chế độ xem dữ liệu chung mà không cần phải
lặp lại.
- Tài liệu Django

Một trong những lợi ích chính của chế độ xem dựa trên lớp là cách chúng cho phép bạn tổng hợp các hành vi
có thể sử dụng lại. Khung REST tận dụng lợi thế này bằng cách cung cấp một số chế độ xem dựng sẵn cung
cấp các mẫu thường được sử dụng.

Các chế độ xem chung do khung REST cung cấp cho phép bạn nhanh chóng xây dựng các chế độ xem API
ánh xạ chặt chẽ với các mô hình cơ sở dữ liệu của bạn.

Nếu các chế độ xem chung không phù hợp với nhu cầu API của bạn, bạn có thể chuyển sang sử dụng
APIView lớp thông thường hoặc sử dụng lại các mixin và lớp cơ sở được các chế độ xem chung sử dụng để
soạn tập hợp các chế độ xem chung có thể sử dụng lại của riêng bạn.

Ví dụ
Thông thường khi sử dụng chế độ xem chung, bạn sẽ ghi đè chế độ xem và đặt một số thuộc tính lớp.

from django.contrib.auth.models import User

from myapp.serializers import UserSerializer
from rest_framework import generics
from rest_framework.permissions import IsAdminUser

class UserList(generics.ListCreateAPIView):
queryset = User.objects.all()
serializer_class = UserSerializer
permission_classes = [IsAdminUser]

Đối với các trường hợp phức tạp hơn, bạn cũng có thể muốn ghi đè các phương thức khác nhau trên lớp
khung nhìn. Ví dụ.

class UserList(generics.ListCreateAPIView):
queryset = User.objects.all()
serializer_class = UserSerializer
permission_classes = [IsAdminUser]

def list(self, request):

# Note the use of `get_queryset()` instead of `self.queryset`
queryset = self.get_queryset()
serializer = UserSerializer(queryset, many=True)
return Response(serializer.data)

Đối với những trường hợp rất đơn giản, bạn có thể muốn chuyển qua bất kỳ thuộc tính lớp nào bằng
.as_view() phương thức này. Ví dụ: URLconf của bạn có thể bao gồm nội dung nào đó giống như mục sau:

path('users/', ListCreateAPIView.as_view(queryset=User.objects.all(), serializer_clas

Tham chiếu API

Chế độ xem API chung
Lớp này mở rộng APIView lớp của khung công tác REST, bổ sung các hành vi thường được yêu cầu cho các
chế độ xem danh sách và chi tiết tiêu chuẩn.

Mỗi chế độ xem chung cụ thể được cung cấp đều được xây dựng bằng cách kết hợp GenericAPIView với
một hoặc nhiều lớp mixin.

Thuộc tính
Các cài đặt cơ bản :

Các thuộc tính sau đây kiểm soát hành vi xem cơ bản.

queryset - Bộ truy vấn nên được sử dụng để trả về các đối tượng từ chế độ xem này. Thông thường, bạn
phải đặt thuộc tính này hoặc ghi đè get_queryset() phương thức. Nếu bạn đang ghi đè một phương
thức xem, điều quan trọng là bạn phải gọi get_queryset() thay vì truy cập trực tiếp vào thuộc tính này,
vì queryset nó sẽ được đánh giá một lần và những kết quả đó sẽ được lưu vào bộ đệm cho tất cả các
yêu cầu tiếp theo.
serializer_class - Lớp trình tuần tự hóa nên được sử dụng để xác thực và giải tuần tự hóa đầu vào
cũng như để tuần tự hóa đầu ra. Thông thường, bạn phải đặt thuộc tính này hoặc ghi đè
get_serializer_class() phương thức.
lookup_field - Trường mô hình nên được sử dụng để thực hiện tra cứu đối tượng của các phiên bản
mô hình riêng lẻ. Mặc định là 'pk' . Lưu ý rằng khi sử dụng API siêu liên kết, bạn cần đảm bảo rằng cả
chế độ xem API và lớp trình tuần tự hóa đều đặt trường tra cứu nếu bạn cần sử dụng giá trị tùy chỉnh.
lookup_url_kwarg - Đối số từ khóa URL nên được sử dụng để tra cứu đối tượng. Cấu hình URL phải
bao gồm đối số từ khóa tương ứng với giá trị này. Nếu không được đặt, giá trị mặc định này sẽ sử dụng
cùng giá trị với lookup_field .

Phân trang :

Các thuộc tính sau được sử dụng để kiểm soát phân trang khi sử dụng với chế độ xem danh sách.

pagination_class - Lớp phân trang nên được sử dụng khi phân trang kết quả danh sách. Mặc định có
cùng giá trị với DEFAULT_PAGINATION_CLASS cài đặt, đó là
'rest_framework.pagination.PageNumberPagination' . Cài đặt pagination_class=None sẽ vô
hiệu hóa phân trang trên chế độ xem này.

Lọc :

filter_backends - Danh sách các lớp phụ trợ bộ lọc nên được sử dụng để lọc bộ truy vấn. Mặc định có
cùng giá trị với DEFAULT_FILTER_BACKENDS cài đặt.

phương pháp
Các phương pháp cơ bản :

get_queryset(self)

Trả về bộ truy vấn sẽ được sử dụng cho chế độ xem danh sách và nên được sử dụng làm cơ sở để tra cứu
trong chế độ xem chi tiết. Mặc định trả về bộ truy vấn được chỉ định bởi queryset thuộc tính.

Phương pháp này phải luôn được sử dụng thay vì truy cập self.queryset trực tiếp, vì self.queryset chỉ
được đánh giá một lần và những kết quả đó được lưu vào bộ đệm cho tất cả các yêu cầu tiếp theo.

Có thể được ghi đè để cung cấp hành vi động, chẳng hạn như trả về một bộ truy vấn, dành riêng cho người
dùng đưa ra yêu cầu.

Ví dụ:
 def get_queryset(self):
user = self.request.user
return user.accounts.all()

Lưu ý: Nếu serializer_class sử dụng trong chế độ xem chung mở rộng các mối quan hệ orm, dẫn đến
vấn đề n+1, bạn có thể tối ưu hóa bộ truy vấn của mình trong phương thức này bằng cách sử dụng
select_related và prefetch_related . Để biết thêm thông tin về vấn đề n+1 và trường hợp sử dụng của
các phương pháp được đề cập, hãy tham khảo phần liên quan trong tài liệu django .

get_object(self)

Trả về một phiên bản đối tượng nên được sử dụng để xem chi tiết. Mặc định sử dụng tham
lookup_field số để lọc bộ truy vấn cơ sở.

Có thể được ghi đè để cung cấp hành vi phức tạp hơn, chẳng hạn như tra cứu đối tượng dựa trên nhiều kwarg
URL.

Ví dụ:

def get_object(self):
queryset = self.get_queryset()
filter = {}
for field in self.multiple_lookup_fields:
filter[field] = self.kwargs[field]

obj = get_object_or_404(queryset, **filter)

self.check_object_permissions(self.request, obj)
return obj

Lưu ý rằng nếu API của bạn không bao gồm bất kỳ quyền cấp đối tượng nào, bạn có thể tùy ý loại trừ
self.check_object_permissions và chỉ cần trả về đối tượng từ get_object_or_404 tra cứu.

filter_queryset(self, queryset)

Đưa ra một bộ truy vấn, hãy lọc nó với bất kỳ phần phụ trợ bộ lọc nào đang được sử dụng, trả về một bộ truy
vấn mới.

Ví dụ:

def filter_queryset(self, queryset):

filter_backends = [CategoryFilter]

if 'geo_route' in self.request.query_params:
filter_backends = [GeoRouteFilter, CategoryFilter]
elif 'geo_point' in self.request.query_params:
filter_backends = [GeoPointFilter, CategoryFilter]

for backend in list(filter_backends):

 queryset = backend().filter_queryset(self.request, queryset, view=self)

return queryset

get_serializer_class(self)

Trả về lớp nên được sử dụng cho bộ tuần tự hóa. Mặc định trả về serializer_class thuộc tính.

Có thể được ghi đè để cung cấp hành vi động, chẳng hạn như sử dụng các bộ nối tiếp khác nhau cho các hoạt
động đọc và ghi hoặc cung cấp các bộ nối tiếp khác nhau cho các loại người dùng khác nhau.

Ví dụ:

def get_serializer_class(self):
if self.request.user.is_staff:
return FullAccountSerializer
return BasicAccountSerializer

Lưu và xóa hook :

Các phương thức sau đây được cung cấp bởi các lớp mixin và cung cấp khả năng ghi đè dễ dàng hành vi lưu
hoặc xóa đối tượng.

perform_create(self, serializer) - Được gọi CreateModelMixin khi lưu một thể hiện đối tượng
mới.
perform_update(self, serializer) - Được gọi UpdateModelMixin khi lưu một thể hiện đối tượng
hiện có.
perform_destroy(self, instance) - Được gọi DestroyModelMixin khi xóa một thể hiện đối tượng.

Những hook này đặc biệt hữu ích để thiết lập các thuộc tính tiềm ẩn trong yêu cầu nhưng không phải là một
phần của dữ liệu yêu cầu. Ví dụ: bạn có thể đặt thuộc tính trên đối tượng dựa trên người dùng yêu cầu hoặc
dựa trên đối số từ khóa URL.

def perform_create(self, serializer):

serializer.save(user=self.request.user)

Những điểm ghi đè này cũng đặc biệt hữu ích để thêm hành vi xảy ra trước hoặc sau khi lưu một đối tượng,
chẳng hạn như gửi email xác nhận hoặc ghi nhật ký cập nhật.

def perform_update(self, serializer):

instance = serializer.save()
send_email_confirmation(user=self.request.user, modified=instance)

Bạn cũng có thể sử dụng các hook này để cung cấp xác thực bổ sung bằng cách tăng ValidationError() .
Điều này có thể hữu ích nếu bạn cần một số logic xác thực để áp dụng tại thời điểm lưu cơ sở dữ liệu. Ví dụ:

def perform_create(self, serializer):

queryset = SignupRequest.objects.filter(user=self.request.user)
if queryset.exists():
 raise ValidationError('You have already signed up')
serializer.save(user=self.request.user)

Các phương pháp khác :

Thông thường, bạn sẽ không cần ghi đè các phương thức sau, mặc dù bạn có thể cần gọi chúng nếu bạn
đang viết các chế độ xem tùy chỉnh bằng cách sử dụng GenericAPIView .

get_serializer_context(self) - Trả về một từ điển chứa bất kỳ ngữ cảnh bổ sung nào cần được
cung cấp cho bộ nối tiếp. Mặc định bao gồm 'request' , 'view' và 'format' các phím.
get_serializer(self, instance=None, data=None, many=False, partial=False) - Trả về một
phiên bản serializer.
get_paginated_response(self, data) - Trả về một Response đối tượng kiểu phân trang.
paginate_queryset(self, queryset) - Phân trang một bộ truy vấn nếu được yêu cầu, trả về một đối
tượng trang hoặc None nếu phân trang không được định cấu hình cho chế độ xem này.
filter_queryset(self, queryset) - Đưa ra một bộ truy vấn, lọc nó với bất kỳ phần phụ trợ bộ lọc
nào đang được sử dụng, trả về một bộ truy vấn mới.

Mixin
Các lớp mixin cung cấp các hành động được sử dụng để cung cấp hành vi xem cơ bản. Lưu ý rằng các lớp
mixin cung cấp các phương thức hành động thay vì xác định trực tiếp các phương thức xử lý, chẳng hạn như
.get() và .post() . Điều này cho phép cấu thành hành vi linh hoạt hơn.

Các lớp mixin có thể được nhập từ các tệp rest_framework.mixins .

Danh sáchMô hìnhMixin

Cung cấp một .list(request, *args, **kwargs) phương thức thực hiện việc liệt kê một bộ truy vấn.

Nếu bộ truy vấn được điền, điều này sẽ trả về một 200 OK phản hồi, với phần trình bày được tuần tự hóa của
bộ truy vấn làm nội dung của phản hồi. Dữ liệu phản hồi có thể được phân trang tùy ý.

TạoModelMixin
Cung cấp một .create(request, *args, **kwargs) phương thức thực hiện việc tạo và lưu một phiên
bản mô hình mới.

Nếu một đối tượng được tạo, điều này sẽ trả về một 201 Created phản hồi, với một biểu diễn tuần tự của
đối tượng làm nội dung của phản hồi. Nếu biểu diễn chứa khóa có tên url , thì Location tiêu đề của phản
hồi sẽ được điền với giá trị đó.

Nếu dữ liệu yêu cầu được cung cấp để tạo đối tượng không hợp lệ thì phản 400 Bad Request hồi sẽ được
trả về, với chi tiết lỗi là nội dung của phản hồi.

Truy xuấtModelMixin
Cung cấp một .retrieve(request, *args, **kwargs) phương thức triển khai việc trả về một phiên bản
mô hình hiện có trong một phản hồi.
Nếu một đối tượng có thể được truy xuất thì điều này sẽ trả về một 200 OK phản hồi, với một biểu diễn tuần
tự của đối tượng làm nội dung của phản hồi. Nếu không, nó sẽ trả về a 404 Not Found .

Cập nhậtModelMixin
Cung cấp một .update(request, *args, **kwargs) phương thức thực hiện cập nhật và lưu một phiên
bản mô hình hiện có.

Cũng cung cấp một .partial_update(request, *args, **kwargs) phương thức tương tự như
update phương thức này, ngoại trừ tất cả các trường dành cho bản cập nhật sẽ là tùy chọn. Điều này cho
phép hỗ trợ PATCH các yêu cầu HTTP.

Nếu một đối tượng được cập nhật, điều này sẽ trả về một 200 OK phản hồi, với một biểu diễn tuần tự của đối
tượng làm nội dung của phản hồi.

Nếu dữ liệu yêu cầu được cung cấp để cập nhật đối tượng không hợp lệ thì phản 400 Bad Request hồi sẽ
được trả về, với chi tiết lỗi là nội dung của phản hồi.

Phá hủyMô hìnhMixin

Cung cấp một .destroy(request, *args, **kwargs) phương thức thực hiện việc xóa một phiên bản mô
hình hiện có.

Nếu một đối tượng bị xóa thì nó sẽ trả về một 204 No Content phản hồi, nếu không nó sẽ trả về một 404
Not Found .

Các lớp xem cụ thể

Các lớp sau đây là các khung nhìn chung cụ thể. Nếu bạn đang sử dụng chế độ xem chung thì đây thường là
cấp độ bạn sẽ làm việc trừ khi bạn cần hành vi được tùy chỉnh nhiều.

Các lớp xem có thể được nhập từ các tệp rest_framework.generics .

TạoAPIView
Được sử dụng cho các điểm cuối chỉ tạo .

Cung cấp một post trình xử lý phương thức.

Mở rộng: GenericAPIView , CreateModelMixin

Danh sáchAPIView
Được sử dụng cho các điểm cuối chỉ đọc để thể hiện một tập hợp các phiên bản mô hình .

Cung cấp một get trình xử lý phương thức.

Mở rộng: GenericAPIView , ListModelMixin

Truy xuấtAPIView
Được sử dụng cho các điểm cuối chỉ đọc để thể hiện một phiên bản mô hình duy nhất .
Cung cấp một get trình xử lý phương thức.

Mở rộng: GenericAPIView , RetrieveModelMixin

Phá hủy chế độ xem API

Được sử dụng cho các điểm cuối chỉ xóa đối với một phiên bản mô hình duy nhất .

Cung cấp một delete trình xử lý phương thức.

Mở rộng: GenericAPIView , DestroyModelMixin

Cập nhậtAPIView
Được sử dụng cho các điểm cuối chỉ cập nhật cho một phiên bản mô hình duy nhất .

Cung cấp put và patch xử lý phương thức.

Mở rộng: GenericAPIView , UpdateModelMixin

Danh sáchTạoAPIView
Được sử dụng cho các điểm cuối đọc-ghi để thể hiện một tập hợp các phiên bản mô hình .

Cung cấp get và post xử lý phương thức.

Mở rộng: GenericAPIView , ListModelMixin , CreateModelMixin

Truy xuấtUpdateAPIView
Được sử dụng để đọc hoặc cập nhật các điểm cuối nhằm thể hiện một phiên bản mô hình duy nhất .

Cung cấp get và put xử patch lý phương thức.

Mở rộng: GenericAPIView , RetrieveModelMixin , UpdateModelMixin

Truy xuấtTiêu hủyAPIView

Được sử dụng để đọc hoặc xóa các điểm cuối nhằm thể hiện một phiên bản mô hình duy nhất .

Cung cấp get và delete xử lý phương thức.

Mở rộng: GenericAPIView , RetrieveModelMixin , DestroyModelMixin

Truy xuấtCập nhậtTiêu hủyAPIView

Được sử dụng cho các điểm cuối đọc-ghi-xóa để thể hiện một phiên bản mô hình duy nhất .

Cung cấp các trình xử lý , và get phương put thức . patch delete

Mở rộng: GenericAPIView , RetrieveModelMixin , UpdateModelMixin , DestroyModelMixin

Tùy chỉnh chế độ xem chung

Thông thường, bạn sẽ muốn sử dụng các dạng xem chung hiện có nhưng sử dụng một số hành vi được tùy
chỉnh một chút. Nếu bạn thấy mình đang sử dụng lại một số hành vi tùy chỉnh ở nhiều nơi, bạn có thể muốn
cấu trúc lại hành vi đó thành một lớp chung mà sau đó bạn có thể áp dụng cho bất kỳ chế độ xem hoặc tập
hợp chế độ xem nào nếu cần.

Tạo mixin tùy chỉnh

Ví dụ: nếu bạn cần tra cứu các đối tượng dựa trên nhiều trường trong cấu hình URL, bạn có thể tạo một lớp
mixin như sau:

class MultipleFieldLookupMixin:
"""
Apply this mixin to any view or viewset to get multiple field filtering
based on a `lookup_fields` attribute, instead of the default single field filteri
"""
def get_object(self):
queryset = self.get_queryset() # Get the base queryset
queryset = self.filter_queryset(queryset) # Apply any filter backends
filter = {}
for field in self.lookup_fields:
if self.kwargs.get(field): # Ignore empty fields.
filter[field] = self.kwargs[field]
obj = get_object_or_404(queryset, **filter) # Lookup the object
self.check_object_permissions(self.request, obj)
return obj

Sau đó, bạn có thể chỉ cần áp dụng mixin này cho một chế độ xem hoặc tập hợp chế độ xem bất cứ lúc nào
bạn cần áp dụng hành vi tùy chỉnh.

class RetrieveUserView(MultipleFieldLookupMixin, generics.RetrieveAPIView):

queryset = User.objects.all()
serializer_class = UserSerializer
lookup_fields = ['account', 'username']

Sử dụng mixin tùy chỉnh là một lựa chọn tốt nếu bạn có hành vi tùy chỉnh cần được sử dụng.

Tạo các lớp cơ sở tùy chỉnh

Nếu bạn đang sử dụng một mixin trên nhiều chế độ xem, bạn có thể tiến thêm một bước nữa và tạo tập hợp
các chế độ xem cơ sở của riêng mình để sau đó có thể sử dụng trong suốt dự án của bạn. Ví dụ:

class BaseRetrieveView(MultipleFieldLookupMixin,
generics.RetrieveAPIView):
pass

class BaseRetrieveUpdateDestroyView(MultipleFieldLookupMixin,
 generics.RetrieveUpdateDestroyAPIView):
pass

Sử dụng các lớp cơ sở tùy chỉnh là một lựa chọn tốt nếu bạn có hành vi tùy chỉnh cần được lặp lại một cách
nhất quán trên một số lượng lớn chế độ xem trong suốt dự án của mình.

PUT khi tạo

Trước phiên bản 3.0, các mixin của khung REST được coi PUT là một thao tác cập nhật hoặc tạo, tùy thuộc
vào việc đối tượng đã tồn tại hay chưa.

Việc cho phép PUT các hoạt động tạo là có vấn đề, vì nó nhất thiết phải tiết lộ thông tin về sự tồn tại hoặc
không tồn tại của các đối tượng. Cũng không rõ ràng rằng việc cho phép tạo lại các phiên bản đã xóa trước
đó một cách minh bạch nhất thiết phải là một hành vi mặc định tốt hơn là chỉ trả về 404 các phản hồi.

Cả hai kiểu " PUT as 404" và " PUT as create" đều có thể hợp lệ trong các trường hợp khác nhau, nhưng từ
phiên bản 3.0 trở đi, giờ đây chúng tôi sử dụng hành vi 404 làm mặc định, do nó đơn giản và rõ ràng hơn.

Nếu bạn cần hành vi PUT-as-tạo chung, bạn có thể muốn bao gồm một cái gì đó giống như lớp
này AllowPUTAsCreateMixin dưới dạng hỗn hợp cho các chế độ xem của mình.

Gói của bên thứ ba

Các gói bên thứ ba sau đây cung cấp thêm các triển khai chế độ xem chung.

Django Rest Nhiều mô hình

Django Rest Multiple Models cung cấp chế độ xem chung (và mixin) để gửi nhiều mô hình và/hoặc bộ truy
vấn được tuần tự hóa thông qua một yêu cầu API duy nhất.

Tài liệu được xây dựng bằng MkDocs .