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 吧!