Django REST Framework 新手入门指南

什么是 Web API？为什么选择 Django REST Framework？
入门前的准备
环境搭建与安装
核心概念详解：
- Serializers（序列化器）
- Views（视图）
- URLs（路由）
- Request 和 Response 对象
构建第一个 DRF 应用：一个简单的待办事项 (Todo) API
- 创建 Django 项目和应用
- 定义模型 (Models)
- 创建序列化器 (Serializers)
- 编写视图 (Views)
- 配置路由 (URLs)
- 运行和测试
更进一步：认证、权限、分页（简单介绍）
总结与下一步

1. 什么是 Web API？为什么选择 Django REST Framework？

什么是 Web API？

API 的全称是 Application Programming Interface（应用程序编程接口）。Web API 特指通过 Web 技术（如 HTTP 协议）提供的应用程序接口。它允许不同的软件系统之间进行通信和数据交换。

想象一下，你的手机 App 需要获取最新的天气信息，或者一个前端网页需要展示用户的数据。这些场景都需要通过 API 向服务器发送请求，服务器处理请求后，通过 API 返回数据。这些数据通常采用 JSON 或 XML 等格式，易于机器解析。

REST (Representational State Transfer) 是一种流行的构建 Web API 的架构风格。REST API 通常遵循以下原则：

无状态 (Stateless): 服务器不保存客户端的状态信息。
客户端-服务器分离 (Client-Server): 客户端和服务器是独立的。
缓存 (Cacheable): 响应可以被客户端缓存。
分层系统 (Layered System): 可以在服务器和客户端之间插入中间层。
统一接口 (Uniform Interface): 通过标准的 HTTP 方法（GET, POST, PUT, DELETE 等）对资源进行操作。

为什么选择 Django REST Framework (DRF)？

Django 是一个用 Python 编写的高级 Web 框架，以其“快速开发，减少重复工作”的理念而闻名。它提供了构建 Web 应用所需的绝大多数功能，包括 ORM (对象关系映射)、URL 路由、模板系统、管理后台等。

然而，Django 本身主要是为了构建传统的、基于模板渲染的 Web 页面而设计的。虽然你可以用 Django 原生方式返回 JSON 数据，但构建一个完整的、符合 REST 规范的 API 会涉及大量重复性的工作，比如：

将数据库模型对象转换为 JSON/XML 格式（序列化）。
解析客户端发送的 JSON/XML 数据，并将其转换为 Python 对象或数据库模型（反序列化）。
处理不同的 HTTP 方法（GET, POST, PUT, DELETE）。
实现认证和权限控制。
处理请求和响应的格式。
提供统一的接口和规范。

Django REST Framework (DRF) 是一个强大且灵活的工具包，用于在 Django 的基础上构建 Web API。它极大地简化了构建 RESTful API 的过程，提供了许多开箱即用的功能：

序列化器 (Serializers): 轻松将 Django 模型或其他数据类型序列化为 JSON/XML，并支持反序列化和数据验证。
多种视图类型 (Views): 提供了各种基于类的视图，用于处理 API 请求，包括功能强大的通用视图 (Generic API Views) 和视图集 (ViewSets)。
认证和权限 (Authentication & Permissions): 内置多种认证方式（如 Token、Session、Basic）和权限控制机制。
限流 (Throttling): 控制用户或 IP 的访问频率。
分页 (Pagination): 方便地处理大量数据的分页返回。
过滤和搜索 (Filtering & Searching): 提供了简单的方式实现数据过滤和搜索。
可浏览的 API (Browsable API): DRF 会自动生成一个友好的网页界面，方便开发者和测试人员与 API 进行交互。
强大的定制性: 几乎所有组件都可以根据需求进行定制或扩展。

总之，如果你需要使用 Django 构建 Web API，DRF 几乎是你的不二之选。它可以让你用更少的代码、更规范的方式构建出功能完善、易于维护的 API。

2. 入门前的准备

在开始学习 DRF 之前，你需要具备以下基础知识：

Python 编程基础: 了解 Python 的语法、数据类型、函数、类等。
Django 基础: 了解 Django 的基本工作原理，包括：
- 项目 (Project) 和应用 (App) 的概念。
- 模型 (Models) 的定义和使用 (Django ORM)。
- 视图 (Views) 的基本概念。
- URL 路由 (URLs)。
- 数据库迁移 (Migrations)。
HTTP 协议基础: 了解 HTTP 请求方法 (GET, POST, PUT, DELETE)、状态码等。
JSON 格式基础: 了解 JSON (JavaScript Object Notation) 的基本结构。

如果你还不熟悉 Django，建议先学习官方的 Django 教程或者其他入门资源。

3. 环境搭建与安装

首先，确保你的系统已经安装了 Python 3。

创建并激活虚拟环境 (强烈推荐):
虚拟环境可以隔离不同项目的依赖库，避免版本冲突。

“`bash

创建虚拟环境 (venv 是虚拟环境的目录名，你可以换成别的)

python -m venv venv

激活虚拟环境

Windows

.\venv\Scripts\activate

macOS/Linux

source venv/bin/activate
`` 激活后，你的终端提示符前会显示(venv)` 字样。
安装 Django 和 Django REST Framework:

bash pip install Django djangorestframework
将 DRF 添加到 Django 项目的 INSTALLED_APPS 中:
在你的 Django 项目的 settings.py 文件中，找到 INSTALLED_APPS 列表，添加 'rest_framework'。

“`python

myproject/settings.py

INSTALLED_APPS = [
# … 其他应用
‘django.contrib.admin’,
‘django.contrib.auth’,
‘django.contrib.contenttypes’,
‘django.contrib.sessions’,
‘django.contrib.messages’,
‘django.contrib.staticfiles’,
‘rest_framework’, # 添加这一行
# … 你自己的应用
]

… 其他设置

“`

至此，你已经成功安装并配置了 DRF。

4. 核心概念详解

DRF 的强大之处在于其提供的抽象层，帮助我们更方便地处理 API 开发中的常见任务。理解以下几个核心概念是掌握 DRF 的关键。

4.1 Serializers (序列化器)

作用: Serializers 是 DRF 中最核心的概念之一。它们负责数据的 序列化 (将复杂的 Python 数据类型，如 Django 模型实例、QuerySet，转换为易于传输和解析的格式，如 JSON、XML) 和 反序列化 (将接收到的格式化数据，如 JSON，转换回 Python 数据类型，如模型实例)。同时，Serializers 还负责对反序列化后的数据进行验证。

为什么需要序列化器？
Django 模型实例是 Python 对象，包含着与数据库表对应的属性。但 HTTP 协议传输的是文本数据，比如 JSON 字符串。你需要一种方式将这些 Python 对象“扁平化”并结构化成文本格式，这就是序列化。
反之，当客户端发送 POST 或 PUT 请求携带 JSON 数据时，你需要将这些 JSON 数据解析出来，并验证其有效性，然后才能用来创建或更新数据库对象，这就是反序列化。

常见的序列化器类型:

Serializer: 最基础的序列化器类，你需要手动定义每个字段及其类型。
ModelSerializer: 这是最常用的序列化器。它可以自动根据 Django 模型生成相应的字段，极大地简化了代码。它还提供了对模型实例的创建 (.create()) 和更新 (.update()) 方法。

ModelSerializer 示例:

假设你有一个 Django 模型 Product:

“`python

myapp/models.py

from django.db import models

class Product(models.Model):
name = models.CharField(max_length=100)
description = models.TextField(blank=True, null=True)
price = models.DecimalField(max_digits=10, decimal_places=2)
in_stock = models.BooleanField(default=True)
created_at = models.DateTimeField(auto_now_add=True)

def __str__(self):
    return self.name

“`

你可以创建一个 ProductSerializer：

“`python

myapp/serializers.py

from rest_framework import serializers
from .models import Product

class ProductSerializer(serializers.ModelSerializer):
class Meta:
model = Product
# 指定需要序列化/反序列化的字段
fields = [‘id’, ‘name’, ‘price’, ‘in_stock’, ‘created_at’]
# 或者使用 ‘all‘ 包含所有字段 (不推荐，最好明确列出)
# fields = ‘all‘
# 或者排除某些字段
# exclude = [‘description’]
“`

如何使用序列化器？

序列化单个对象:

“`python

在 Django shell 或视图中

from myapp.models import Product
from myapp.serializers import ProductSerializer

product = Product.objects.get(id=1)
serializer = ProductSerializer(product)
print(serializer.data) # 输出 OrderedDict 类似的数据，可以渲染为 JSON

例如: {‘id’: 1, ‘name’: ‘Laptop’, ‘price’: ‘1200.00’, ‘in_stock’: True, ‘created_at’: ‘2023-10-27T10:00:00Z’}

“`
序列化多个对象 (QuerySet):

“`python
products = Product.objects.all()

many=True 参数告诉序列化器处理一个列表或 QuerySet

serializer = ProductSerializer(products, many=True)
print(serializer.data) # 输出 OrderedDict 的列表
“`
反序列化 (创建对象):

“`python

假设接收到以下 JSON 数据

data = {‘name’: ‘Tablet’, ‘price’: ‘300.00’, ‘in_stock’: True}

serializer = ProductSerializer(data=data)

验证数据是否有效

if serializer.is_valid():
# 保存数据，创建新的 Product 实例
product = serializer.save()
print(“新产品创建成功:”, product)
# 返回序列化后的新对象数据作为响应
print(serializer.data)
else:
# 数据无效，打印错误信息
print(serializer.errors) # 输出字典，包含字段错误信息
“`
反序列化 (更新对象):

“`python

假设要更新 id=1 的产品

product_to_update = Product.objects.get(id=1)

假设接收到更新数据 (只需要包含要修改的字段)

update_data = {‘price’: ‘1300.00’, ‘in_stock’: False}

serializer = ProductSerializer(product_to_update, data=update_data, partial=True) # partial=True 允许部分更新
if serializer.is_valid():
# 保存数据，更新现有 Product 实例
serializer.save()
print(“产品更新成功:”, product_to_update)
print(serializer.data) # 返回更新后的产品数据
else:
print(serializer.errors)
“`

4.2 Views (视图)

作用: DRF 中的视图是处理 API 请求的核心。它们接收请求，调用序列化器进行数据处理（验证、保存），并返回响应。DRF 提供了多种视图类型，帮助你编写更简洁的 API 逻辑。

常见的视图类型:

APIView: DRF 提供的最基础的视图类，继承自 Django 的 View。它增强了 Request 和 Response 对象，并处理认证、权限、限流等策略。你需要自己实现 get(), post(), put(), delete() 等方法来处理不同的 HTTP 请求。

“`python

myapp/views.py

from rest_framework.views import APIView
from rest_framework.response import Response
from rest_framework import status
from .models import Product
from .serializers import ProductSerializer

class ProductListAPIView(APIView):
def get(self, request, format=None):
“””
处理 GET 请求，返回所有产品列表
“””
products = Product.objects.all()
serializer = ProductSerializer(products, many=True)
return Response(serializer.data) # 使用 DRF 的 Response 对象

def post(self, request, format=None):
    """
    处理 POST 请求，创建新产品
    """
    # request.data 是 DRF 增强的请求对象，包含解析后的请求体数据 (如 JSON)
    serializer = ProductSerializer(data=request.data)
    if serializer.is_valid():
        serializer.save() # 调用 serializer 的 create() 方法
        # 返回新创建的对象数据和 201 Created 状态码
        return Response(serializer.data, status=status.HTTP_201_CREATED)
    # 数据无效，返回错误信息和 400 Bad Request 状态码
    return Response(serializer.errors, status=status.HTTP_400_BAD_REQUEST)

class ProductDetailAPIView(APIView):
def get_object(self, pk):
try:
return Product.objects.get(pk=pk)
except Product.DoesNotExist:
from django.http import Http404
raise Http404 # 或者使用 DRF 的 exceptions.NotFound

 def get(self, request, pk, format=None):
    """
    处理 GET 请求，返回单个产品详情
    """
    product = self.get_object(pk)
    serializer = ProductSerializer(product)
    return Response(serializer.data)

 def put(self, request, pk, format=None):
     """
     处理 PUT 请求，更新单个产品
     """
     product = self.get_object(pk)
     serializer = ProductSerializer(product, data=request.data)
     if serializer.is_valid():
         serializer.save() # 调用 serializer 的 update() 方法
         return Response(serializer.data)
     return Response(serializer.errors, status=status.HTTP_400_BAD_REQUEST)

 def delete(self, request, pk, format=None):
     """
     处理 DELETE 请求，删除单个产品
     """
     product = self.get_object(pk)
     product.delete()
     # 返回 204 No Content 表示成功删除且没有返回内容
     return Response(status=status.HTTP_204_NO_CONTENT)

“`

通用视图 (Generic API Views): DRF 提供了一系列预先写好的通用视图，用于处理常见的 API 模式，如列表、创建、详情、更新、删除。它们通常与 Mixins 结合使用，以提供更具体的功能。
- Mixins: ListModelMixin, CreateModelMixin, RetrieveModelMixin, UpdateModelMixin, DestroyModelMixin 等，它们提供了处理列表、创建、获取单个、更新、删除对象的核心逻辑。
- 组合视图: DRF 提供了常用的组合视图，将 GenericAPIView 和 Mixins 组合在一起：
  - ListCreateAPIView = GenericAPIView + ListModelMixin + CreateModelMixin (用于处理列表和创建)
  - RetrieveUpdateDestroyAPIView = GenericAPIView + RetrieveModelMixin + UpdateModelMixin + DestroyModelMixin (用于处理获取、更新、删除单个对象)
  - RetrieveAPIView (获取单个对象)
  - ListAPIView (获取列表)
  - CreateAPIView (创建对象)
  - 等等…
使用通用视图可以极大地减少代码量：

“`python

myapp/views.py (使用通用视图重写上面的例子)

from rest_framework import generics
from .models import Product
from .serializers import ProductSerializer

class ProductListCreateAPIView(generics.ListCreateAPIView):
# 指定要操作的模型集合 (QuerySet)
queryset = Product.objects.all()
# 指定用于序列化和反序列化的序列化器类
serializer_class = ProductSerializer
# ListCreateAPIView 自动处理 GET (列表) 和 POST (创建) 请求

class ProductRetrieveUpdateDestroyAPIView(generics.RetrieveUpdateDestroyAPIView):
queryset = Product.objects.all()
serializer_class = ProductSerializer
# 需要根据 URL 中的 pk 参数来查找特定对象
# RetrieveUpdateDestroyAPIView 自动处理 GET (详情), PUT (更新), DELETE (删除) 请求
“`
可以看到，使用通用视图后代码变得非常简洁。
视图集 (ViewSets): ViewSets 将一组相关的视图逻辑（如列表、创建、获取详情、更新、删除）组合到一个类中。它们不直接提供 get, post 等方法，而是提供 list, create, retrieve, update, partial_update, destroy 等方法。ViewSets 通常与 Routers (路由器) 结合使用，自动生成 URL 配置。
- ViewSet：基础 ViewSet，需要手动实现各种方法。
- GenericViewSet：继承自 GenericAPIView 和 ViewSet，可以配合 Mixins 使用。
- ModelViewSet：继承自 GenericViewSet 并包含了所有常用的 Mixins (List, Create, Retrieve, Update, Destroy)，是处理模型对象的 CRUD 操作最方便的 ViewSet。
使用 ModelViewSet 的示例：

“`python

myapp/views.py (使用 ModelViewSet)

from rest_framework import viewsets
from .models import Product
from .serializers import ProductSerializer

class ProductViewSet(viewsets.ModelViewSet):
queryset = Product.objects.all()
serializer_class = ProductSerializer
# ModelViewSet 自动提供 list, create, retrieve, update, partial_update, destroy 方法
“`
ViewSets 的路由配置需要使用 Routers，这将在 URL 部分讲解。

对于初学者，推荐的学习路径是先理解 APIView 的工作原理，然后重点学习并使用 Generic API Views + Mixins，最后再学习 ViewSets + Routers。Generic API Views 是非常常用且强大的工具。

4.3 URLs (路由)

作用: 将 URL 请求映射到相应的 DRF 视图。这与 Django 原生的 URL 配置类似，但 DRF 的 ViewSets 通常与 DRF 的 Routers 结合使用，可以自动化生成 URL 配置。

配置 APIView 或 Generic API View 的 URL:

这与 Django 原生配置类似，在应用的 urls.py 中使用 path 或 re_path：

“`python

myapp/urls.py

from django.urls import path
from . import views

urlpatterns = [
# 对于 ProductListCreateAPIView (处理 /items/ GET和POST)
path(‘items/’, views.ProductListCreateAPIView.as_view(), name=’item-list-create’),
# 对于 ProductRetrieveUpdateDestroyAPIView (处理 /items/pk/ GET, PUT, DELETE)
path(‘items//’, views.ProductRetrieveUpdateDestroyAPIView.as_view(), name=’item-detail-update-delete’),
]
`` 注意，基于类的视图（APIView和Generic API Views）需要在 URL 配置中使用.as_view()` 方法。

然后，在项目的 urls.py 中包含应用的 URL：

“`python

myproject/urls.py

from django.contrib import admin
from django.urls import path, include

urlpatterns = [
path(‘admin/’, admin.site.urls),
# 将 DRF 的可浏览 API 登录/退出 URL 包含进来
path(‘api-auth/’, include(‘rest_framework.urls’, namespace=’rest_framework’)),
# 包含应用的 API URL
path(‘api/’, include(‘myapp.urls’)),
]
“`

配置 ViewSets 的 URL (使用 Routers):

DRF 提供了 DefaultRouter 和 SimpleRouter 来自动生成 ViewSets 的 URL 配置。DefaultRouter 包含了默认的根视图，并会自动创建 <basename>-list 和 <basename>-detail 两种 URL 模式。

“`python

myapp/urls.py

from django.urls import path, include
from rest_framework.routers import DefaultRouter
from . import views

创建一个 Router 实例

router = DefaultRouter()

注册 ViewSet，第一个参数是 URL 前缀，第二个参数是 ViewSet 类

basename 是用于生成 URL 名称和反向解析时的前缀，如果 ViewSet 中定义了 .queryset 属性，DRF 会尝试从模型名称自动生成 basename

但通常推荐明确指定 basename

router.register(r’items’, views.ProductViewSet, basename=’item’)

router.urls 会自动生成对应的 URL patterns

urlpatterns = [
# 将 router 生成的 URL patterns 包含进来
path(”, include(router.urls)),
]
`` 这样配置后，DefaultRouter会为ProductViewSet` 自动生成以下 URL：

/items/ (对应 list 和 create 方法)
/items/{pk}/ (对应 retrieve, update, partial_update, destroy 方法)

在项目的 urls.py 中包含应用的 URL 方式不变。

使用 Routers + ViewSets 是 DRF 中组织 API URL 的推荐方式，特别是在构建大型 API 时。

4.4 Request 和 Response 对象

DRF 增强了 Django 原生的 HttpRequest 和 HttpResponse 对象，提供了更适合 API 开发的功能。

Request 对象:
- request.data: 这是最重要的增强。它包含了解析后的请求体数据，例如 JSON、XML 表单数据等。DRF 会根据请求的 Content-Type 自动解析数据，你无需手动处理 JSON 解析等。
- request.query_params: 包含了 URL 中的查询参数（即 ? 后面的部分）。
- request.parsers: 当前请求可用的解析器列表。
- request.negotiator: 处理内容协商的对象。
Response 对象:
- Response 对象接收序列化后的数据和 HTTP 状态码作为参数。
- 它负责根据客户端的 Accept 头部进行内容协商，决定返回数据的格式（默认是 JSON）。
- 它会自动设置正确的 Content-Type 头部。

示例中我们已经多次使用了 Response(serializer.data, status=...)。

5. 构建第一个 DRF 应用：一个简单的待办事项 (Todo) API

我们将创建一个简单的 API，支持查看待办事项列表、创建新的待办事项、查看、更新和删除单个待办事项。

假设项目名称为 todo_project，应用名称为 todo_app。

创建 Django 项目和应用:

“`bash

确保在虚拟环境内

django-admin startproject todo_project . # 注意末尾的点，在当前目录创建项目
cd todo_project
python manage.py startapp todo_app
“`
将应用添加到 INSTALLED_APPS:
编辑 todo_project/settings.py，在 INSTALLED_APPS 中添加 'todo_app' 和 'rest_framework'。

“`python

todo_project/settings.py

INSTALLED_APPS = [
# … 其他应用
‘django.contrib.admin’,
‘django.contrib.auth’,
‘django.contrib.contenttypes’,
‘django.contrib.sessions’,
‘django.contrib.messages’,
‘django.contrib.staticfiles’,
‘rest_framework’, # 添加这一行
‘todo_app’, # 添加这一行
]

… 其他设置

“`
定义模型 (Models):
编辑 todo_app/models.py，定义一个简单的 TodoItem 模型。

“`python

todo_app/models.py

from django.db import models

class TodoItem(models.Model):
title = models.CharField(max_length=200)
description = models.TextField(blank=True, null=True)
completed = models.BooleanField(default=False)
created_at = models.DateTimeField(auto_now_add=True)
updated_at = models.DateTimeField(auto_now=True)
```
def __str__(self):
    return self.title

class Meta:
    ordering = ['-created_at'] # 默认按创建时间倒序
```
“`
运行数据库迁移命令：

bash python manage.py makemigrations python manage.py migrate
创建序列化器 (Serializers):
在 todo_app 目录下创建一个新的文件 serializers.py，并定义 TodoItemSerializer。

“`python

todo_app/serializers.py

from rest_framework import serializers
from .models import TodoItem

class TodoItemSerializer(serializers.ModelSerializer):
class Meta:
model = TodoItem
# 指定所有字段
fields = ‘all‘
# 或者明确指定字段列表
# fields = [‘id’, ‘title’, ‘description’, ‘completed’, ‘created_at’, ‘updated_at’]
# 设置某些字段为只读（例如，创建时间和更新时间通常由服务器设置）
read_only_fields = [‘created_at’, ‘updated_at’]

“`
编写视图 (Views):
编辑 todo_app/views.py。我们将使用 Generic API Views + Mixins 来简化代码。

“`python

todo_app/views.py

from rest_framework import generics
from .models import TodoItem
from .serializers import TodoItemSerializer

视图用于处理待办事项列表和创建

class TodoItemListCreateView(generics.ListCreateAPIView):
queryset = TodoItem.objects.all() # 指定数据源
serializer_class = TodoItemSerializer # 指定序列化器
# GET 请求会返回所有 TodoItem 的列表 (由 ListModelMixin 提供)
# POST 请求会根据请求数据创建新的 TodoItem (由 CreateModelMixin 提供)

视图用于处理单个待办事项的获取、更新和删除

class TodoItemDetailView(generics.RetrieveUpdateDestroyAPIView):
queryset = TodoItem.objects.all() # 指定数据源 (用于查找特定对象)
serializer_class = TodoItemSerializer # 指定序列化器
# GET 请求会返回指定 pk 的 TodoItem 详情 (由 RetrieveModelMixin 提供)
# PUT 请求会更新指定 pk 的 TodoItem (由 UpdateModelMixin 提供)
# PATCH 请求会部分更新指定 pk 的 TodoItem (由 UpdateModelMixin 提供)
# DELETE 请求会删除指定 pk 的 TodoItem (由 DestroyModelMixin 提供)
# 注意: GenericAPIView 会根据 URL 中的 pk 参数自动过滤 queryset 获取对象

“`
配置路由 (URLs):
在 todo_app 目录下创建 urls.py 文件，并配置视图路由。

“`python

todo_app/urls.py

from django.urls import path
from . import views

urlpatterns = [
# 映射 /todos/ 到 TodoItemListCreateView
path(‘todos/’, views.TodoItemListCreateView.as_view(), name=’todo-list-create’),
# 映射 /todos// 到 TodoItemDetailView
path(‘todos//’, views.TodoItemDetailView.as_view(), name=’todo-detail-update-delete’),
]
`` 然后在项目的urls.py` 中包含应用的 URL 和 DRF 的认证 URL（用于可浏览 API 的登录）。

“`python

todo_project/urls.py

from django.contrib import admin
from django.urls import path, include

urlpatterns = [
path(‘admin/’, admin.site.urls),
# DRF 可浏览 API 的登录/退出 URL
path(‘api-auth/’, include(‘rest_framework.urls’, namespace=’rest_framework’)),
# 包含 todo_app 的 API URL，给一个前缀如 ‘api/’
path(‘api/’, include(‘todo_app.urls’)),
]
“`
运行和测试:
- 运行开发服务器：
  bash python manage.py runserver
- 使用可浏览的 API (浏览器):
  打开浏览器，访问 http://127.0.0.1:8000/api/todos/。
  如果一切顺利，你会看到一个由 DRF 自动生成的、非常友好的网页界面。
  - 你可以看到当前的待办事项列表（目前是空的）。
  - 页面下方有一个表单，用于通过 POST 请求创建新的待办事项。输入 JSON 数据（例如 {"title": "学习 DRF", "description": "完成入门指南", "completed": false}）或表单数据，点击 POST 按钮即可创建。
  - 创建成功后，页面会显示新创建的待办事项，并且列表也会更新。
  - 点击列表中某个待办事项的 URL (http://127.0.0.1:8000/api/todos/1/)，你会进入该待办事项的详情页。
  - 在详情页，你可以看到待办事项的详细信息，下方有 PUT、PATCH、DELETE 请求的表单/按钮。
- 使用 curl (终端):
  你可以使用 curl 命令来测试 API。
  
  “`bash
  
  获取所有待办事项 (GET 请求)
  
  curl http://127.0.0.1:8000/api/todos/
  
  创建新的待办事项 (POST 请求)
  
  curl -X POST -H “Content-Type: application/json” -d ‘{“title”: “购买食材”, “completed”: false}’ http://127.0.0.1:8000/api/todos/
  
  获取某个待办事项详情 (GET 请求，假设ID为1)
  
  curl http://127.0.0.1:8000/api/todos/1/
  
  更新某个待办事项 (PUT 请求，更新ID为1的事项)
  
  curl -X PUT -H “Content-Type: application/json” -d ‘{“title”: “购买食材”, “description”: “周末聚餐”, “completed”: true}’ http://127.0.0.1:8000/api/todos/1/
  
  部分更新某个待办事项 (PATCH 请求，只更新ID为1的事项的 completed 状态)
  
  curl -X PATCH -H “Content-Type: application/json” -d ‘{“completed”: true}’ http://127.0.0.1:8000/api/todos/1/
  
  删除某个待办事项 (DELETE 请求，删除ID为1的事项)
  
  curl -X DELETE http://127.0.0.1:8000/api/todos/1/ -I # -I 参数只显示响应头
  `` 通过curl` 命令可以更好地理解 API 的请求和响应。

恭喜你！你已经成功构建了第一个使用 Django REST Framework 的 API。

6. 更进一步：认证、权限、分页（简单介绍）

构建一个完整的、实用的 API 通常还需要考虑认证、权限和分页等问题。DRF 为这些功能提供了强大的支持。

认证 (Authentication): 确定是谁发出了请求。DRF 支持多种认证方式，如：
- SessionAuthentication: 基于 Django session 的认证，常用于与 Django 前端结合。
- TokenAuthentication: 基于 Token 的认证，适用于移动应用或第三方服务调用。
- BasicAuthentication: HTTP Basic Auth。
- OAuth1, OAuth2 等。
  你可以在 settings.py 中设置默认认证类，或在视图类中通过 authentication_classes 指定。
权限 (Permissions): 确定发出请求的用户是否有权执行请求的操作。DRF 提供了多种权限类，如：
- AllowAny: 允许所有用户访问 (默认)。
- IsAuthenticated: 只允许认证用户访问。
- IsAdminUser: 只允许管理员用户访问。
- IsAuthenticatedOrReadOnly: 认证用户可以修改，未认证用户只能读取。
- DjangoModelPermissions: 基于 Django 模型权限。
  你也可以自定义权限类。在视图类中通过 permission_classes 指定。
分页 (Pagination): 当数据量很大时，一次性返回所有数据会影响性能和用户体验。分页可以将大量数据分成小块返回。DRF 提供了多种分页器，如：
- PageNumberPagination: 基于页码的分页。
- LimitOffsetPagination: 基于限制和偏移量的分页。
- CursorPagination: 基于游标的分页，更适合大型数据集和需要稳定排序的场景。
  你可以在 settings.py 中设置默认分页类，或在视图类中通过 pagination_class 指定。

这些高级特性是构建健壮 API 的重要组成部分，建议在掌握了基础后深入学习。

7. 总结与下一步

通过本指南，你了解了：

Web API 和 RESTful 风格的基本概念。
Django REST Framework 的作用和优势。
如何安装和配置 DRF。
DRF 的核心概念：Serializers, Views, URLs, Request/Response。
如何使用 Serializers 进行数据的序列化、反序列化和验证。
如何使用 APIView、Generic API Views（特别是 ListCreateAPIView 和 RetrieveUpdateDestroyAPIView）编写 API 视图。
如何配置 URL 路由，包括使用 path 和 Routers。
如何构建一个简单的待办事项 API 并进行测试。

你现在已经具备了使用 DRF 构建基本 Web API 的能力。

下一步的学习方向：

深入学习 Serializers 的更多用法，如嵌套序列化、自定义字段、自定义验证等。
深入学习 ModelViewSet 和 Routers 的用法，它们能进一步提高开发效率。
学习如何实现用户认证和权限控制，保护你的 API。
学习如何使用分页、过滤和搜索功能，处理更复杂的数据查询需求。
学习如何编写测试用例来测试你的 API。
了解 DRF 的其他高级功能，如版本控制、限流、自定义渲染器和解析器等。
查阅 DRF 官方文档 (非常详细和全面)。

Django REST Framework 是一个非常成熟和强大的框架，社区活跃，文档完善。持续实践和学习将帮助你成为一名更高效的 API 开发者。

祝你学习愉快！

Django REST Framework 新手入门指南

目录

1. 什么是 Web API？为什么选择 Django REST Framework？

什么是 Web API？

为什么选择 Django REST Framework (DRF)？

2. 入门前的准备

3. 环境搭建与安装

创建虚拟环境 (venv 是虚拟环境的目录名，你可以换成别的)

激活虚拟环境

Windows

macOS/Linux

myproject/settings.py

… 其他设置

4. 核心概念详解

4.1 Serializers (序列化器)

myapp/models.py

myapp/serializers.py

在 Django shell 或视图中

例如: {‘id’: 1, ‘name’: ‘Laptop’, ‘price’: ‘1200.00’, ‘in_stock’: True, ‘created_at’: ‘2023-10-27T10:00:00Z’}

many=True 参数告诉序列化器处理一个列表或 QuerySet

假设接收到以下 JSON 数据

验证数据是否有效

假设要更新 id=1 的产品

假设接收到更新数据 (只需要包含要修改的字段)

4.2 Views (视图)

myapp/views.py

myapp/views.py (使用通用视图重写上面的例子)

myapp/views.py (使用 ModelViewSet)

4.3 URLs (路由)

myapp/urls.py

myproject/urls.py

myapp/urls.py

创建一个 Router 实例

注册 ViewSet，第一个参数是 URL 前缀，第二个参数是 ViewSet 类

basename 是用于生成 URL 名称和反向解析时的前缀，如果 ViewSet 中定义了 .queryset 属性，DRF 会尝试从模型名称自动生成 basename

但通常推荐明确指定 basename

router.urls 会自动生成对应的 URL patterns

4.4 Request 和 Response 对象

5. 构建第一个 DRF 应用：一个简单的待办事项 (Todo) API

确保在虚拟环境内

todo_project/settings.py

… 其他设置

todo_app/models.py

todo_app/serializers.py

todo_app/views.py

视图用于处理待办事项列表和创建

视图用于处理单个待办事项的获取、更新和删除

todo_app/urls.py

todo_project/urls.py

获取所有待办事项 (GET 请求)

创建新的待办事项 (POST 请求)

获取某个待办事项详情 (GET 请求，假设ID为1)

更新某个待办事项 (PUT 请求，更新ID为1的事项)

部分更新某个待办事项 (PATCH 请求，只更新ID为1的事项的 completed 状态)

删除某个待办事项 (DELETE 请求，删除ID为1的事项)

6. 更进一步：认证、权限、分页（简单介绍）

7. 总结与下一步

发表评论 取消回复

发表评论取消回复