Django REST Framework 入门教程：从零开始构建API

前言：API 时代的基石

在当今互联互通的世界里，应用程序之间的数据交换变得前所未有的重要。无论是移动应用、前端网页框架（如 React, Vue, Angular）还是物联网设备，它们都需要通过接口（API – Application Programming Interface）与后端服务进行通信，获取或提交数据。RESTful API 因其简洁、高效和标准化的特性，成为了构建 Web 服务的主流选择。

Django 作为 Python 领域最流行的 Web 框架之一，以其“开箱即用”和“约定优于配置”的理念，极大地提升了开发效率。然而，原生 Django 更侧重于渲染 HTML 页面。为了让 Django 也能轻松构建强大的 RESTful API，Django REST Framework (DRF) 应运而生。

DRF 是一个强大且灵活的工具包，用于快速构建 RESTful API。它在 Django 的基础上提供了序列化器、视图类、认证、权限、限流等一系列功能，极大地简化了 API 的开发过程。

本教程目标：
本教程将带领你从零开始，使用 Django REST Framework 构建一个简单的博客文章管理API。你将学习到：
* Django 项目和应用的创建
* DRF 的安装与配置
* 模型（Model）的定义
* 序列化器（Serializer）的使用
* 视图（View）的编写（函数视图、类视图、通用视图、视图集）
* URL 路由的配置
* 认证（Authentication）与权限（Permissions）的实现
* API 文档的生成（使用 drf-yasg）

适合人群：
* 对 Django 有基本了解的开发者。
* 希望学习如何构建 RESTful API 的开发者。
* 对后端开发感兴趣的初学者。

准备工作：
在开始之前，请确保你的系统已安装：
* Python 3.8+
* pip (Python 包管理器)
* 对命令行操作有基本了解

第一章：环境搭建与Django项目初始化

我们将从创建一个独立的 Python 虚拟环境开始，以避免项目依赖冲突。

1.1 创建并激活虚拟环境

“`bash

创建一个名为 venv 的虚拟环境

python -m venv venv

激活虚拟环境 (macOS/Linux)

source venv/bin/activate

激活虚拟环境 (Windows)

venv\Scripts\activate

`` 激活后，你的命令行提示符前会显示(venv)`，表示你已在虚拟环境中。

1.2 安装 Django 和 Django REST Framework

现在，在激活的虚拟环境中安装所需的库：

bash pip install Django djangorestframework

1.3 创建 Django 项目和应用

我们将创建一个名为 drf_blog_project 的 Django 项目，并在其中创建一个名为 blog_api 的应用。

“`bash

创建项目 (注意最后的点表示在当前目录创建项目结构)

django-admin startproject drf_blog_project .

创建应用

python manage.py startapp blog_api
“`

现在，你的项目结构应该类似这样：

drf_blog_project/ ├── blog_api/ │ ├── migrations/ │ ├── __init__.py │ ├── admin.py │ ├── apps.py │ ├── models.py │ ├── tests.py │ └── views.py ├── drf_blog_project/ │ ├── __init__.py │ ├── asgi.py │ ├── settings.py │ ├── urls.py │ └── wsgi.py ├── manage.py └── venv/

1.4 配置 Django 项目

打开 drf_blog_project/settings.py 文件，在 INSTALLED_APPS 列表中添加我们创建的应用和 DRF：

“`python

drf_blog_project/settings.py

INSTALLED_APPS = [
‘django.contrib.admin’,
‘django.contrib.auth’,
‘django.contrib.contenttypes’,
‘django.contrib.sessions’,
‘django.contrib.messages’,
‘django.contrib.staticfiles’,

# 我们自己的应用
'blog_api',

# Django REST Framework
'rest_framework',

]

… 其他设置 …

“`

保存 settings.py 文件。

1.5 运行初始迁移

在项目根目录运行迁移命令，为 Django 默认的用户和会话等功能创建数据库表：

bash python manage.py migrate

1.6 创建超级用户 (可选但推荐)

创建超级用户可以让你访问 Django 后台管理界面，方便后续数据的添加和查看。

bash python manage.py createsuperuser
按照提示输入用户名、邮箱和密码。

第二章：定义模型（Models）

在 blog_api 应用中，我们将定义两个简单的模型：Author (作者) 和 Post (文章)。

2.1 编写 `models.py`

打开 blog_api/models.py 文件，添加以下代码：

“`python

blog_api/models.py

from django.db import models
from django.contrib.auth.models import User

作者模型

class Author(models.Model):
name = models.CharField(max_length=100, unique=True, verbose_name=”作者姓名”)
bio = models.TextField(blank=True, null=True, verbose_name=”个人简介”)

class Meta:
    verbose_name = "作者"
    verbose_name_plural = "作者"
    ordering = ['name'] # 按姓名排序

def __str__(self):
    return self.name

文章模型

class Post(models.Model):
STATUS_CHOICES = (
(‘draft’, ‘草稿’),
(‘published’, ‘已发布’),
)

title = models.CharField(max_length=200, verbose_name="标题")
content = models.TextField(verbose_name="内容")
author = models.ForeignKey(Author, on_delete=models.CASCADE, related_name='posts', verbose_name="作者")
created_at = models.DateTimeField(auto_now_add=True, verbose_name="创建时间")
updated_at = models.DateTimeField(auto_now=True, verbose_name="更新时间")
status = models.CharField(max_length=10, choices=STATUS_CHOICES, default='draft', verbose_name="状态")

class Meta:
    verbose_name = "文章"
    verbose_name_plural = "文章"
    ordering = ['-created_at'] # 按创建时间倒序

def __str__(self):
    return self.title

`` **解释：** *Author模型包含name(姓名) 和bio(简介)。 *Post模型包含title(标题)、content(内容)、author(外键关联Author模型)、created_at(创建时间)、updated_at(更新时间) 和status(状态)。 *ForeignKey定义了Post和Author之间的一对多关系：一个作者可以有多篇文章，一篇文章只能有一个作者。 *related_name=’posts’允许我们通过author.posts.all()访问某个作者的所有文章。 *str` 方法返回对象的字符串表示，这在 Django Admin 中非常有用。

2.2 注册模型到 Admin 后台 (可选)

为了方便通过 Django Admin 管理数据，我们将这些模型注册到 admin.py。
打开 blog_api/admin.py，添加以下代码：

“`python

blog_api/admin.py

from django.contrib import admin
from .models import Author, Post

admin.site.register(Author)
admin.site.register(Post)
“`

2.3 生成并执行数据库迁移

每次修改模型后，都需要执行以下两步：

“`bash

生成迁移文件 (将模型的改变记录下来)

python manage.py makemigrations blog_api

执行迁移 (将改变应用到数据库)

python manage.py migrate
“`

现在，你可以运行开发服务器并访问管理后台 (http://127.0.0.1:8000/admin/)，使用之前创建的超级用户登录，然后添加一些作者和文章数据，以便后续测试 API。

bash python manage.py runserver

第三章：序列化器（Serializers）的使用

序列化器是 DRF 的核心概念之一。它负责将模型实例（或查询集）转换为 Python 字典，再进一步渲染成 JSON、XML 等格式，以便通过 API 传输；反之，它也能将传入的数据解析回 Python 字典，并可用于更新或创建模型实例。

3.1 创建 `serializers.py`

在 blog_api 目录下创建 serializers.py 文件：

bash touch blog_api/serializers.py

3.2 编写 `serializers.py`

打开 blog_api/serializers.py，添加以下代码：

“`python

blog_api/serializers.py

from rest_framework import serializers
from .models import Author, Post

作者序列化器

class AuthorSerializer(serializers.ModelSerializer):
class Meta:
model = Author
fields = ‘all‘ # 序列化所有字段
# 或者指定字段: fields = [‘id’, ‘name’, ‘bio’]

文章序列化器

class PostSerializer(serializers.ModelSerializer):
# 如果想在文章列表中显示作者的名字而不是ID，可以这么做
author_name = serializers.ReadOnlyField(source=’author.name’)

class Meta:
    model = Post
    fields = '__all__' # 序列化所有字段
    # 或者指定字段: fields = ['id', 'title', 'content', 'author', 'author_name', 'created_at', 'updated_at', 'status']
    read_only_fields = ['created_at', 'updated_at'] # 这些字段只读，不能通过API修改

`` **解释：** *serializers.ModelSerializer是 DRF 提供的一个便捷类，它会自动推断模型字段，并为模型创建相应的序列化器字段。它还自动支持创建和更新模型实例。 *class Meta用于配置序列化器： *model = Author/Post: 指定要序列化的模型。 *fields = ‘all‘：表示序列化模型中的所有字段。你也可以传入一个字段名列表，只序列化指定的字段。 *read_only_fields: 这是一个元组或列表，包含在序列化时只读的字段。这些字段在更新或创建时不会被修改。 *author_name = serializers.ReadOnlyField(source=’author.name’): 这是一个额外的只读字段。source=’author.name’表示这个字段的值来自于关联的author对象的name` 属性。这在显示文章列表时非常有用，可以直接看到作者名称而不需要额外的查询。

第四章：视图（Views）的编写

视图是处理传入 HTTP 请求并返回响应的地方。DRF 提供了多种编写视图的方式，从最基本的函数视图到强大的视图集。我们将逐步了解它们。

4.1 函数视图（Function-Based Views）

这是最基础的视图形式，使用 @api_view 装饰器来包裹普通的 Django 函数。

打开 blog_api/views.py，添加以下代码：

“`python

blog_api/views.py

from rest_framework.decorators import api_view
from rest_framework.response import Response
from rest_framework import status

from .models import Author, Post
from .serializers import AuthorSerializer, PostSerializer

Authors API – 函数视图示例

@api_view([‘GET’, ‘POST’])
def author_list_create(request):
“””
列出所有作者或创建一个新作者。
“””
if request.method == ‘GET’:
authors = Author.objects.all()
serializer = AuthorSerializer(authors, many=True) # many=True 表示序列化一个查询集
return Response(serializer.data)

elif request.method == 'POST':
    serializer = AuthorSerializer(data=request.data)
    if serializer.is_valid():
        serializer.save()
        return Response(serializer.data, status=status.HTTP_201_CREATED)
    return Response(serializer.errors, status=status.HTTP_400_BAD_REQUEST)

@api_view([‘GET’, ‘PUT’, ‘DELETE’])
def author_detail(request, pk):
“””
检索、更新或删除一个作者实例。
“””
try:
author = Author.objects.get(pk=pk)
except Author.DoesNotExist:
return Response(status=status.HTTP_404_NOT_FOUND)

if request.method == 'GET':
    serializer = AuthorSerializer(author)
    return Response(serializer.data)

elif request.method == 'PUT':
    serializer = AuthorSerializer(author, data=request.data)
    if serializer.is_valid():
        serializer.save()
        return Response(serializer.data)
    return Response(serializer.errors, status=status.HTTP_400_BAD_REQUEST)

elif request.method == 'DELETE':
    author.delete()
    return Response(status=status.HTTP_204_NO_CONTENT)

“`

解释：
* @api_view(['GET', 'POST'])：装饰器，声明此视图函数支持哪些 HTTP 方法。
* request.data：DRF 提供的 Request 对象，可以智能处理 JSON、表单等不同内容类型的请求体。
* Response(data, status)：DRF 提供的 Response 对象，可以接受任意 Python 数据，并自动渲染为 JSON 等格式。
* serializer.is_valid()：验证传入的数据是否符合序列化器定义的规则。
* serializer.save()：如果数据有效，此方法将调用模型上的 create() 或 update() 方法来保存数据。
* status：DRF 提供了一系列方便的 HTTP 状态码常量。

4.2 类视图（Class-Based Views – `APIView`）

APIView 是 DRF 提供的最基础的类视图，它提供了 APIView 的所有功能，如认证、权限等，并且结构化了 HTTP 方法的处理。

在 blog_api/views.py 中，我们可以将上述函数视图改写为 APIView：

“`python

blog_api/views.py (在现有代码基础上追加或替换)

from rest_framework.views import APIView # 导入 APIView

… 其他导入 …

Posts API – 类视图 (APIView) 示例

class PostList(APIView):
“””
列出所有文章或创建一个新文章。
“””
def get(self, request, format=None):
posts = Post.objects.all()
serializer = PostSerializer(posts, many=True)
return Response(serializer.data)

def post(self, request, format=None):
    serializer = PostSerializer(data=request.data)
    if serializer.is_valid():
        serializer.save()
        return Response(serializer.data, status=status.HTTP_201_CREATED)
    return Response(serializer.errors, status=status.HTTP_400_BAD_REQUEST)

class PostDetail(APIView):
“””
检索、更新或删除一个文章实例。
“””
def get_object(self, pk):
try:
return Post.objects.get(pk=pk)
except Post.DoesNotExist:
raise status.HTTP_404_NOT_FOUND # 或者直接返回Response(status=…)

def get(self, request, pk, format=None):
    post = self.get_object(pk)
    serializer = PostSerializer(post)
    return Response(serializer.data)

def put(self, request, pk, format=None):
    post = self.get_object(pk)
    serializer = PostSerializer(post, data=request.data)
    if serializer.is_valid():
        serializer.save()
        return Response(serializer.data)
    return Response(serializer.errors, status=status.HTTP_400_BAD_REQUEST)

def delete(self, request, pk, format=None):
    post = self.get_object(pk)
    post.delete()
    return Response(status=status.HTTP_204_NO_CONTENT)

`` **解释：** * HTTP 方法（get(),post(),put(),delete()）直接作为类的方法定义。 *get_object()是一个辅助方法，用于获取单个实例，减少重复代码。 *format=None是 DRF 的一个约定，用于内容协商，在 URL 中可以指定.json或.api`等后缀来请求不同格式的响应。

4.3 通用视图（Generic Views）

Generic Views 是 DRF 为常见 API 模式提供的预构建视图。它们是 APIView 的子类，通过混合（Mixins）机制，进一步简化了代码。它们会自动处理查询集、序列化器和 HTTP 方法映射。

现在，我们将 Post 的视图使用通用视图进行重写，你会发现代码量大大减少：

“`python

blog_api/views.py (替换 PostList 和 PostDetail 为以下通用视图)

from rest_framework import generics # 导入 generics

… 其他导入 …

Posts API – 通用视图 (Generic Views) 示例

class PostListCreateView(generics.ListCreateAPIView):
“””
List all posts, or create a new post.
“””
queryset = Post.objects.all() # 指定查询集
serializer_class = PostSerializer # 指定序列化器

class PostRetrieveUpdateDestroyView(generics.RetrieveUpdateDestroyAPIView):
“””
Retrieve, update or delete a post instance.
“””
queryset = Post.objects.all() # 指定查询集
serializer_class = PostSerializer # 指定序列化器
`` **解释：** *ListCreateAPIView结合了ListModelMixin和CreateModelMixin，用于处理 GET (列表) 和 POST (创建) 请求。你只需要指定queryset和serializer_class。 *RetrieveUpdateDestroyAPIView结合了RetrieveModelMixin,UpdateModelMixin,DestroyModelMixin，用于处理 GET (详情)、PUT/PATCH (更新) 和 DELETE (删除) 请求。同样，只需指定queryset和serializer_class`。
* 通用视图是构建 API 的常用且高效的方式。

4.4 视图集（ViewSets）和路由器（Routers）

ViewSets 是 DRF 提供的最高级的抽象，它将一组相关的视图逻辑（如列表、详情、创建、更新、删除）打包到一个类中。结合 Routers，可以极大地简化 URL 配置。

我们将 Author 和 Post 都改写成 ViewSet。

“`python

blog_api/views.py (替换 author_list_create, author_detail, PostListCreateView, PostRetrieveUpdateDestroyView 为以下视图集)

from rest_framework import viewsets # 导入 viewsets

… 其他导入 …

作者视图集

class AuthorViewSet(viewsets.ModelViewSet):
“””
提供作者的列表、创建、检索、更新和删除操作。
“””
queryset = Author.objects.all()
serializer_class = AuthorSerializer

文章视图集

class PostViewSet(viewsets.ModelViewSet):
“””
提供文章的列表、创建、检索、更新和删除操作。
“””
queryset = Post.objects.all()
serializer_class = PostSerializer
`` **解释：** *ModelViewSet是最常用的视图集，它提供了list(),retrieve(),create(),update(),partial_update(),destroy()等方法，自动对应 CRUD 操作。 * 它同样只需要queryset和serializer_class` 属性。

第五章：URL 路由配置

URL 路由负责将 API 端点映射到相应的视图。

5.1 为 `blog_api` 应用创建 `urls.py`

在 blog_api 目录下创建 urls.py 文件：

bash touch blog_api/urls.py

5.2 配置应用级 URL (使用 ViewSets 和 Routers)

打开 blog_api/urls.py，添加以下代码：

“`python

blog_api/urls.py

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

创建一个路由器实例

router = DefaultRouter()

注册视图集，第一个参数是URL前缀，第二个是视图集类，第三个是basename（用于反向解析）

router.register(r’authors’, AuthorViewSet)
router.register(r’posts’, PostViewSet)

urlpatterns = [
# 将路由器生成的URL包含进来
path(”, include(router.urls)),
]
`` **解释：** *DefaultRouter会自动为AuthorViewSet和PostViewSet生成一整套的 URL 模式，包括列表和详情页面的路径。 *router.urls包含了一个 URL 模式的列表，可以直接通过include()` 引入。

5.3 配置项目级 URL

打开 drf_blog_project/urls.py 文件，包含 blog_api 的 URL 模式，并添加 DRF 的登录/退出 URL（用于在浏览器可访问的 API 根页面中显示登录/退出按钮）。

“`python

drf_blog_project/urls.py

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

urlpatterns = [
path(‘admin/’, admin.site.urls),

# 包含 blog_api 应用的 URL
path('api/', include('blog_api.urls')),

# DRF 提供的登录/退出 URL，用于浏览器可浏览的API
path('api-auth/', include('rest_framework.urls')),

]
“`

现在，运行 python manage.py runserver，并访问 http://127.0.0.1:8000/api/，你将看到 DRF 提供的浏览器可浏览 API 界面，其中列出了 authors 和 posts 两个端点。点击进入后，你可以进行 GET 请求，并查看添加、更新、删除等操作的表单。

第六章：认证（Authentication）与权限（Permissions）

认证是识别用户身份的过程，权限是决定用户是否有权执行某个操作的过程。DRF 提供了多种认证和权限机制。

6.1 配置认证类

最常用的认证方式之一是 TokenAuthentication (令牌认证) 和 SessionAuthentication (会话认证)。我们会同时使用它们，会话认证方便浏览器可浏览 API，而令牌认证适用于第三方客户端（如移动应用）。

首先，我们需要安装 djangorestframework-authtoken 应用：

bash pip install djangorestframework-authtoken

然后，在 settings.py 中添加到 INSTALLED_APPS 并配置默认认证和权限类：

“`python

drf_blog_project/settings.py

INSTALLED_APPS = [
# … 其他应用 …
‘rest_framework’,
‘rest_framework.authtoken’, # 添加此行
]

REST_FRAMEWORK = {
‘DEFAULT_AUTHENTICATION_CLASSES’: [
‘rest_framework.authentication.SessionAuthentication’, # 浏览器登录后使用会话认证
‘rest_framework.authentication.TokenAuthentication’, # 用于API客户端的令牌认证
],
‘DEFAULT_PERMISSION_CLASSES’: [
‘rest_framework.permissions.IsAuthenticatedOrReadOnly’, # 默认权限：已认证用户可读写，未认证用户只读
]
}
“`

运行迁移以创建 authtoken 相关的数据库表：

bash python manage.py migrate

6.2 为用户生成 Token

TokenAuthentication 需要为每个用户生成一个唯一的 Token。你可以通过 Django Admin 为用户手动生成，或者通过 DRF 提供的管理命令生成。

“`bash

生成指定用户的Token (假设你有一个用户名为 admin 的超级用户)

python manage.py drf_create_token admin

你会看到类似这样的输出：

Token: 9944061a96752765365e921d7b38d4a6e033e079

“`
请记住这个 Token，后续我们将用它来访问 API。

6.3 在视图中应用权限

我们已经在 settings.py 中设置了默认的 IsAuthenticatedOrReadOnly 权限，这意味着未认证的用户只能执行 GET 请求（读取数据），而 POST、PUT、DELETE 等修改操作则需要认证。

如果你的某个视图需要更严格的权限（例如，只有管理员才能修改），可以在视图类中单独指定：

“`python

blog_api/views.py (在 AuthorViewSet 和 PostViewSet 中添加)

from rest_framework import permissions # 导入 permissions

class AuthorViewSet(viewsets.ModelViewSet):
queryset = Author.objects.all()
serializer_class = AuthorSerializer
# permission_classes = [permissions.IsAdminUser] # 只有管理员才能对作者进行任何操作
# permission_classes = [permissions.IsAuthenticated] # 只有登录用户才能操作

class PostViewSet(viewsets.ModelViewSet):
queryset = Post.objects.all()
serializer_class = PostSerializer
# 默认使用 settings.py 中的 IsAuthenticatedOrReadOnly
# 如果想更宽松，可以设置为 permissions.AllowAny （任何人都可以访问和修改）
# permission_classes = [permissions.AllowAny]
`` **常用权限类：** *AllowAny: 允许任何用户访问。 *IsAuthenticated: 仅限已认证用户。 *IsAdminUser: 仅限管理员用户。 *IsAuthenticatedOrReadOnly`: 已认证用户可读写，未认证用户只读。

现在，重启开发服务器。当你访问 /api/authors/ 或 /api/posts/ 并尝试进行 POST/PUT/DELETE 操作时，如果未登录或未提供有效 Token，你将收到 403 Forbidden 错误。

如何使用 Token 访问 API：
在进行请求时，将 Token 放在 HTTP 请求头的 Authorization 字段中，格式为 Token <你的Token>。

例如，使用 curl：

“`bash

获取文章列表 (未认证，可以访问)

curl -X GET http://127.0.0.1:8000/api/posts/

创建文章 (需要认证，这里使用你生成的 Token)

curl -X POST http://127.0.0.1:8000/api/posts/ \
-H “Content-Type: application/json” \
-H “Authorization: Token YOUR_AUTH_TOKEN_HERE” \
-d ‘{“title”: “我的第一篇文章”, “content”: “这是文章内容。”, “author”: 1, “status”: “published”}’
`` 请将YOUR_AUTH_TOKEN_HERE替换为你在步骤 6.2 中生成的实际 Token。“author”: 1` 假设你的数据库中存在 ID 为 1 的作者。

第七章：API 文档生成（使用 drf-yasg）

为 API 生成交互式文档对于开发和测试都非常重要。drf-yasg 是一个流行的库，可以根据你的 DRF 视图自动生成 Swagger/OpenAPI 文档。

7.1 安装 drf-yasg

bash pip install drf-yasg

7.2 配置 `settings.py`

在 INSTALLED_APPS 中添加 drf_yasg：

“`python

drf_blog_project/settings.py

INSTALLED_APPS = [
# …
‘drf_yasg’, # 添加此行
]
“`

7.3 配置项目 `urls.py`

在 drf_blog_project/urls.py 中添加 drf-yasg 相关的 URL 模式：

“`python

drf_blog_project/urls.py

from django.contrib import admin
from django.urls import path, include, re_path # 导入 re_path
from rest_framework import permissions # 导入 permissions
from drf_yasg.views import get_schema_view # 导入 get_schema_view
from drf_yasg import openapi # 导入 openapi

配置 Swagger/OpenAPI 文档视图

schema_view = get_schema_view(
openapi.Info(
title=”DRF 博客API”,
default_version=’v1′,
description=”Django REST Framework 入门教程示例API”,
terms_of_service=”https://www.google.com/policies/terms/”,
contact=openapi.Contact(email=”[email protected]”),
license=openapi.License(name=”BSD License”),
),
public=True, # 是否允许匿名访问
permission_classes=[permissions.AllowAny], # 允许任何人访问文档
)

urlpatterns = [
path(‘admin/’, admin.site.urls),
path(‘api/’, include(‘blog_api.urls’)),
path(‘api-auth/’, include(‘rest_framework.urls’)),

# Swagger UI 和 ReDoc 文档页面
re_path(r'^swagger(?P<format>\.json|\.yaml)$', schema_view.without_ui(cache_timeout=0), name='schema-json'),
re_path(r'^swagger/$', schema_view.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'),
re_path(r'^redoc/$', schema_view.with_ui('redoc', cache_timeout=0), name='schema-redoc'),

]
`` **解释：** *get_schema_view用于生成 API 模式。 *openapi.Info包含了 API 的元数据，如标题、版本、描述等。 *re_path用于定义正则表达式匹配的 URL。 *swagger/路径提供交互式的 Swagger UI 界面。 *redoc/` 路径提供更简洁的 ReDoc 界面。

现在，重启开发服务器，访问 http://127.0.0.1:8000/swagger/ 或 http://127.0.0.1:8000/redoc/，你将看到一个漂亮且交互式的 API 文档页面，所有你定义的 API 端点都会在这里清晰地列出，并且可以直接进行测试！

第八章：总结与展望

恭喜你！你已经成功地从零开始构建了一个基本的 Django REST Framework API，并涵盖了以下核心概念：

项目设置与环境搭建： 使用虚拟环境，安装 Django 和 DRF。
模型定义： 创建 Author 和 Post 模型，并建立外键关系。
序列化器： 使用 ModelSerializer 将模型数据转换为 JSON，并支持数据验证。
视图： 逐步学习了函数视图、APIView 类视图、Generic Views 通用视图，以及最高级的 ViewSets 视图集。
URL 路由： 利用 DefaultRouter 简化了 ViewSets 的 URL 配置。
认证与权限： 配置了 SessionAuthentication 和 TokenAuthentication，并使用 IsAuthenticatedOrReadOnly 权限保护 API。
API 文档： 使用 drf-yasg 自动生成了交互式 Swagger/ReDoc 文档。

这个教程为你构建了一个坚实的基础，但 DRF 的功能远不止于此。

下一步可以学习和探索的方向：

自定义序列化器： 学习如何手动定义 serializers.Serializer，实现更复杂的字段验证和数据转换逻辑。
嵌套序列化器： 如何在序列化器中包含关联模型的数据（例如，在文章详情中直接包含作者的所有信息）。
过滤器（Filtering）： 允许客户端通过查询参数过滤数据（例如，/api/posts/?author=1）。DRF 提供了 django-filter 库来简化此过程。
分页（Pagination）： 控制 API 返回数据的数量，避免一次性返回大量数据。
限流（Throttling）： 限制用户或IP地址在一定时间内可以发出的请求数量，防止滥用。
解析器（Parsers）和渲染器（Renderers）： 了解 DRF 如何处理不同的请求数据格式（JSON, XML, 表单）和响应数据格式。
自定义权限： 编写自定义权限类，实现更精细的权限控制，例如“只有文章作者才能修改自己的文章”。
JWT 认证： JSON Web Token (JWT) 是一种流行的无状态认证方式，适合跨域和微服务架构。可以使用 djangorestframework-simplejwt。
测试 API： 学习如何使用 Django 的测试框架或 pytest 来自动化测试你的 API 端点。
部署： 将你的 Django DRF 应用部署到生产环境，例如 Heroku, AWS, DigitalOcean 等。

通过本教程，你已经掌握了使用 Django REST Framework 从零构建 API 的核心技能。持续实践和探索，你将能够构建出任何复杂度的 RESTful 服务！祝你编码愉快！

Django REST Framework 入门教程：从零开始构建API

前言：API 时代的基石

第一章：环境搭建与Django项目初始化

1.1 创建并激活虚拟环境

创建一个名为 venv 的虚拟环境

激活虚拟环境 (macOS/Linux)

激活虚拟环境 (Windows)

venv\Scripts\activate

1.2 安装 Django 和 Django REST Framework

1.3 创建 Django 项目和应用

创建项目 (注意最后的点表示在当前目录创建项目结构)

创建应用

1.4 配置 Django 项目

drf_blog_project/settings.py

… 其他设置 …

1.5 运行初始迁移

1.6 创建超级用户 (可选但推荐)

第二章：定义模型（Models）

2.1 编写 models.py

blog_api/models.py

作者模型

文章模型

2.2 注册模型到 Admin 后台 (可选)

blog_api/admin.py

2.3 生成并执行数据库迁移

生成迁移文件 (将模型的改变记录下来)

执行迁移 (将改变应用到数据库)

第三章：序列化器（Serializers）的使用

3.1 创建 serializers.py

3.2 编写 serializers.py

blog_api/serializers.py

作者序列化器

文章序列化器

第四章：视图（Views）的编写

4.1 函数视图（Function-Based Views）

blog_api/views.py

Authors API – 函数视图示例

4.2 类视图（Class-Based Views – APIView）

blog_api/views.py (在现有代码基础上追加或替换)

… 其他导入 …

Posts API – 类视图 (APIView) 示例

4.3 通用视图（Generic Views）

blog_api/views.py (替换 PostList 和 PostDetail 为以下通用视图)

… 其他导入 …

Posts API – 通用视图 (Generic Views) 示例

4.4 视图集（ViewSets）和路由器（Routers）

blog_api/views.py (替换 author_list_create, author_detail, PostListCreateView, PostRetrieveUpdateDestroyView 为以下视图集)

… 其他导入 …

作者视图集

文章视图集

第五章：URL 路由配置

5.1 为 blog_api 应用创建 urls.py

5.2 配置应用级 URL (使用 ViewSets 和 Routers)

blog_api/urls.py

创建一个路由器实例

注册视图集，第一个参数是URL前缀，第二个是视图集类，第三个是basename（用于反向解析）

5.3 配置项目级 URL

drf_blog_project/urls.py

第六章：认证（Authentication）与权限（Permissions）

6.1 配置认证类

drf_blog_project/settings.py

6.2 为用户生成 Token

生成指定用户的Token (假设你有一个用户名为 admin 的超级用户)

你会看到类似这样的输出：

Token: 9944061a96752765365e921d7b38d4a6e033e079

6.3 在视图中应用权限

blog_api/views.py (在 AuthorViewSet 和 PostViewSet 中添加)

获取文章列表 (未认证，可以访问)

创建文章 (需要认证，这里使用你生成的 Token)

第七章：API 文档生成（使用 drf-yasg）

7.1 安装 drf-yasg

7.2 配置 settings.py

drf_blog_project/settings.py

7.3 配置项目 urls.py

drf_blog_project/urls.py

配置 Swagger/OpenAPI 文档视图

第八章：总结与展望

发表评论 取消回复

2.1 编写 `models.py`

3.1 创建 `serializers.py`

3.2 编写 `serializers.py`

4.2 类视图（Class-Based Views – `APIView`）

5.1 为 `blog_api` 应用创建 `urls.py`

7.2 配置 `settings.py`

7.3 配置项目 `urls.py`

发表评论取消回复