DRF 基础入门教程：快速上手 – wiki基地

作者： /

DRF 基础入门教程：快速上手 – 构建你的第一个RESTful API

欢迎来到 Django REST Framework (DRF) 的世界！如果你已经熟悉 Django 并希望为你的项目构建强大的 RESTful API，那么 DRF 绝对是你的不二之选。它建立在 Django 的坚实基础之上，提供了丰富的功能和工具，让 API 开发变得高效而愉快。

本教程的目标是帮助你快速上手，用最少的时间构建一个功能完善的、基于 Viewset 的简单 API。我们将跳过一些高级细节，聚焦于构建一个能够进行增删改查 (CRUD) 的产品 API。

我们将要构建的 API 功能：
1. 获取产品列表
2. 创建新产品
3. 获取单个产品详情
4. 更新产品信息
5. 删除产品

准备好了吗？让我们开始吧！

1. 环境准备与项目设置

首先，确保你已经安装了 Python 和 pip。接下来，我们需要安装 Django 和 DRF。

bash
pip install Django djangorestframework

安装完成后，创建一个新的 Django 项目：

bash
django-admin startproject myapi
cd myapi

然后，在项目中创建一个新的 Django 应用，用于存放我们的产品 API 代码：

bash
python manage.py startapp products

现在，打开 myapi/settings.py 文件，将新创建的 products 应用和 rest_framework 加入到 INSTALLED_APPS 列表中：

“`python

myapi/settings.py

INSTALLED_APPS = [
# … 其他已有的应用
‘rest_framework’,
‘products’,
]

… 其他设置

“`

运行数据库迁移，这会创建 DRF 自身需要的数据库表：

bash
python manage.py migrate

至此，我们的基础环境已经搭建完毕。

2. 定义数据模型 (Model)

我们的 API 需要处理产品数据，所以第一步是定义一个简单的 Django Model 来代表产品。

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

“`python

products/models.py

from django.db import models

class Product(models.Model):
name = models.CharField(max_length=100)
description = models.TextField()
price = models.DecimalField(max_digits=10, decimal_places=2)
created_at = models.DateTimeField(auto_now_add=True)
updated_at = models.DateTimeField(auto_now=True)

def __str__(self):
    return self.name

“`

这是一个非常简单的产品模型，包含名称、描述、价格和创建/更新时间。

定义好模型后，别忘了生成并应用数据库迁移：

bash
python manage.py makemigrations products
python manage.py migrate

3. 创建序列化器 (Serializer)

在 API 中，我们需要将 Django Model 实例（Python 对象）转换为可以在网络上传输的数据格式（如 JSON），反之亦然（将接收到的 JSON 数据转换为 Python 对象）。这个转换过程就是由 Serializer 完成的。

DRF 提供了 serializers.ModelSerializer，它可以根据你的 Django Model 自动生成序列化器字段，非常方便。

在 products 应用目录下创建一个新文件 serializers.py，并添加以下代码：

“`python

products/serializers.py

from rest_framework import serializers
from .models import Product

class ProductSerializer(serializers.ModelSerializer):
class Meta:
model = Product
fields = ‘all‘ # 表示序列化/反序列化Model中的所有字段
# 如果只想包含部分字段，可以写成 tuple: fields = (‘id’, ‘name’, ‘price’)
# 如果想排除部分字段，可以使用 exclude: exclude = (‘created_at’, ‘updated_at’)
“`

ProductSerializer 继承自 serializers.ModelSerializer。在内部的 Meta 类中，我们指定了它对应的 Model (Product) 以及要序列化/反序列化的字段 (__all__ 表示所有字段)。

这个序列化器现在知道如何将 Product 对象转换为 JSON，以及如何将 JSON 数据验证并转换回 Product 对象（用于创建和更新）。

4. 编写视图 (View)

视图 (View) 负责接收请求、调用序列化器进行数据处理、并返回响应。DRF 提供了多种编写视图的方式：

  • APIView: 最基础的视图类，类似于 Django 的 View，但提供了更好的请求和响应处理、认证、权限等功能。你需要手动处理请求方法 (GET, POST, PUT 等)。
  • Generic API Views: 对常见模式（如列表、详情、创建、更新、删除）进行了封装，提供了更简洁的代码。你需要指定 queryset 和 serializer_class。
  • Viewsets: 将一组相关的视图（如列表、详情、创建、更新、删除）组合到一个类中，通常与 Routers 配合使用，可以自动生成 URL。这是快速构建 CRUD API 的最佳选择。

为了快速上手并构建完整的 CRUD 功能，我们将使用 Viewsets。

打开 products/views.py 文件，添加以下代码：

“`python

products/views.py

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

class ProductViewSet(viewsets.ModelViewSet):
“””
A simple ViewSet for viewing and editing products.
“””
queryset = Product.objects.all()
serializer_class = ProductSerializer
“`

就是这么简单！viewsets.ModelViewSet 自动提供了 list (GET /products/)、create (POST /products/)、retrieve (GET /products/{id}/)、update (PUT/PATCH /products/{id}/)、destroy (DELETE /products/{id}/) 等多种动作。我们只需要指定 queryset (获取所有产品对象) 和 serializer_class (使用我们之前创建的序列化器)。

5. 配置 URL 路由 (URL Routing)

最后一步是将我们的 Viewset 映射到 URL。DRF 的 Viewsets 与 Routers 配合使用非常方便，Routers 可以自动生成符合 RESTful 规范的 URL 模式。

打开 products/urls.py 文件（如果不存在，就创建一个），添加以下代码：

“`python

products/urls.py

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

创建一个 DefaultRouter 实例

router = DefaultRouter()

注册 ProductViewSet 到路由，base_name 是 URL 的前缀

router.register(r’products’, ProductViewSet)

router 会自动生成对应的 URL patterns，例如:

/products/ (GET, POST) -> list, create

/products/{id}/ (GET, PUT, PATCH, DELETE) -> retrieve, update, destroy

urlpatterns = [
# 将 router 生成的 URL patterns 包含进来
path(”, include(router.urls)),
]
“`

DefaultRouter 会自动检测 ProductViewSet 中可用的动作，并生成对应的 URL 模式。router.register() 的第一个参数是 URL 的前缀（例如 ‘products’），第二个参数是 Viewset 类。

接着，我们需要在项目的总 URL 配置中包含 products 应用的 URL。打开 myapi/urls.py 文件，修改如下：

“`python

myapi/urls.py

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

urlpatterns = [
path(‘admin/’, admin.site.urls),
# 将 products 应用的 URLS 包含到 /api/ 路径下
path(‘api/’, include(‘products.urls’)),
# 包含 DRF 提供的登录/登出 URLS，用于 browsable API
path(‘api-auth/’, include(‘rest_framework.urls’)),
]
“`

我们将产品 API 的所有 URL 都放在了 /api/ 路径下。path('api-auth/', include('rest_framework.urls')) 是为了启用 DRF 提供的可浏览 API (Browsable API) 的登录/登出功能，这对于测试非常方便。

6. 运行服务器并测试 API (Browsable API)

至此，我们的第一个 DRF API 已经基本构建完成！现在可以运行 Django 开发服务器来测试它了。

bash
python manage.py runserver

打开你的浏览器，访问 http://127.0.0.1:8000/api/products/。你应该会看到 DRF 提供的可浏览 API (Browsable API) 界面。这是一个非常有用的工具，让你可以在浏览器中直接查看和与你的 API 进行交互。

  • 查看产品列表: 在 /api/products/ 页面，如果数据库中没有产品，会显示一个空列表。页面下方有一个 POST 表单。
  • 创建产品: 使用 /api/products/ 页面下方的 POST 表单，填写 name, description, price (注意数据格式，price 应该是数字)，然后点击 POST 按钮。如果成功，会返回新创建产品的详情。
  • 查看单个产品: 在产品列表或创建成功后返回的详情中，找到产品的 url 或根据 ID 构造 URL (例如 http://127.0.0.1:8000/api/products/1/) 访问。你会看到该产品的详情页。
  • 更新产品: 在单个产品详情页 (例如 /api/products/1/)，页面下方有 PUT 和 PATCH 表单。填写要更新的字段并提交。
  • 删除产品: 在单个产品详情页 (例如 /api/products/1/)，页面下方有 DELETE 按钮。点击即可删除产品。

你可以通过这个可浏览 API 界面直观地测试我们刚刚用 Viewset 构建的 CRUD 功能。

除了可浏览 API，你也可以使用其他工具来测试，比如 curl 命令、Postman、Insomnia 等 API 测试客户端。

例如，使用 curl 创建一个产品：

bash
curl -X POST -H "Content-Type: application/json" -d '{"name": "示例产品", "description": "这是第一个示例产品", "price": 19.99}' http://127.0.0.1:8000/api/products/

使用 curl 获取产品列表：

bash
curl http://127.0.0.1:8000/api/products/

7. 进阶方向 (Next Steps)

恭喜你！你已经成功地使用 DRF 构建了一个基本的 RESTful API。这只是 DRF 功能的冰山一角。接下来，你可以继续探索以下内容：

  • 认证 (Authentication): 如何验证 API 请求是由合法用户发出的（如 Token 认证、Session 认证等）。
  • 权限 (Permissions): 如何控制用户对不同资源的访问权限（如只有管理员才能删除产品）。
  • 限流 (Throttling): 如何限制用户或 IP 地址在一定时间内可以发出的请求数量。
  • 分页 (Pagination): 如何处理大量数据，将结果分页返回给客户端。
  • 过滤和搜索 (Filtering & Searching): 如何允许客户端通过查询参数过滤或搜索数据。
  • 自定义 Serializer 字段: 如何处理更复杂的数据结构，或者定制字段的输出格式。
  • 自定义 ViewSet 或 View: 当 ModelViewSet 不能满足需求时，如何使用 GenericAPIView 或 APIView 编写更灵活的视图。
  • 测试: 如何为你的 API 编写自动化测试。
  • 部署: 如何将你的 Django + DRF 项目部署到生产环境。

DRF 官方文档是学习这些高级功能的最佳资源。

总结

在本教程中，我们从零开始，使用 Django REST Framework 快速构建了一个简单的产品 API。我们学习了以下核心概念：

  • Model: 定义数据结构。
  • Serializer: 在 Python 对象和数据格式（如 JSON）之间进行转换。ModelSerializer 提供快速方法。
  • View/Viewset: 处理请求和返回响应。ModelViewSet 提供了便捷的 CRUD 实现。
  • URL Routing: 将 URL 映射到视图。DefaultRouter 配合 Viewset 自动生成 URL。
  • Browsable API: DRF 提供的方便的浏览器内测试工具。

通过使用 ModelSerializer 和 ModelViewSet 配合 DefaultRouter，我们可以以极高的效率构建出符合 RESTful 规范的基础 CRUD API。这正是 DRF 强大的魅力所在——让你能够快速启动，同时又提供了足够的灵活性来处理更复杂的场景。

希望这篇教程能帮助你迈出 DRF 学习的第一步！动手实践是掌握新技术的最好方式，继续探索 DRF 的更多功能，构建更强大的 API 吧！

发表评论

您的邮箱地址不会被公开。 必填项已用 * 标注

滚动至顶部