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: 对常见模式(如列表、详情、创建、更新、删除)进行了封装,提供了更简洁的代码。你需要指定 querysetserializer_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 不能满足需求时,如何使用 GenericAPIViewAPIView 编写更灵活的视图。
  • 测试: 如何为你的 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 提供的方便的浏览器内测试工具。

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

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


发表评论

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

滚动至顶部