Django REST Framework 教程：序列化入门指南

前言

在构建Web API时，数据序列化是一个核心概念。本文将带你深入了解Django REST Framework中的序列化机制，通过构建一个简单的代码片段API，掌握序列化的基本原理和实践技巧。

环境准备

在开始之前，我们需要设置开发环境：

1. 创建并激活虚拟环境（推荐使用Python内置的venv模块）
2. 安装必要的依赖包：
   • Django：Web框架基础
   • Django REST Framework：构建RESTful API的核心工具
   • Pygments：代码高亮库（用于我们的代码片段功能）

项目初始化

1. 创建Django项目和应用：

   django-admin startproject tutorial
   cd tutorial
   python manage.py startapp snippets
   

2. 将应用添加到配置中： 修改settings.py文件，添加'rest_framework'和'snippets'到INSTALLED_APPS

数据模型设计

我们首先定义一个简单的代码片段模型：

from django.db import models
from pygments.lexers import get_all_lexers
from pygments.styles import get_all_styles

class Snippet(models.Model):
    created = models.DateTimeField(auto_now_add=True)
    title = models.CharField(max_length=100, blank=True, default='')
    code = models.TextField()
    linenos = models.BooleanField(default=False)
    language = models.CharField(max_length=100)
    style = models.CharField(max_length=100)
    
    class Meta:
        ordering = ['created']

这个模型包含：

• 创建时间（自动记录）
• 可选的标题
• 代码内容
• 是否显示行号
• 编程语言（从Pygments获取支持的语言列表）
• 代码高亮样式

创建并应用迁移：

python manage.py makemigrations snippets
python manage.py migrate

序列化器基础

序列化器是Django REST Framework的核心组件之一，它负责：

1. 将复杂数据类型（如模型实例）转换为Python原生数据类型
2. 将Python原生数据类型转换为复杂数据类型
3. 验证输入数据

基本序列化器

创建一个serializers.py文件，定义我们的第一个序列化器：

from rest_framework import serializers
from snippets.models import Snippet

class SnippetSerializer(serializers.Serializer):
    id = serializers.IntegerField(read_only=True)
    title = serializers.CharField(required=False, allow_blank=True, max_length=100)
    code = serializers.CharField(style={'base_template': 'textarea.html'})
    linenos = serializers.BooleanField(required=False)
    language = serializers.ChoiceField(choices=LANGUAGE_CHOICES, default='python')
    style = serializers.ChoiceField(choices=STYLE_CHOICES, default='friendly')

    def create(self, validated_data):
        return Snippet.objects.create(**validated_data)

    def update(self, instance, validated_data):
        # 更新各个字段
        instance.save()
        return instance

这个序列化器：

• 定义了与模型对应的字段
• 实现了create()和update()方法
• 包含字段验证逻辑
• 使用style参数控制表单显示方式

序列化器使用示例

在Django shell中体验序列化器：

from snippets.models import Snippet
from snippets.serializers import SnippetSerializer
from rest_framework.renderers import JSONRenderer
from rest_framework.parsers import JSONParser

# 创建并序列化一个代码片段
snippet = Snippet(code='print("Hello World")')
serializer = SnippetSerializer(snippet)
serializer.data  # 查看序列化后的数据

# 将数据渲染为JSON
content = JSONRenderer().render(serializer.data)

# 反序列化过程
stream = BytesIO(content)
data = JSONParser().parse(stream)
serializer = SnippetSerializer(data=data)
serializer.is_valid()  # 验证数据
serializer.save()  # 保存数据

模型序列化器简化

注意到我们的SnippetSerializer中很多代码与模型定义重复，DRF提供了ModelSerializer来简化这一过程：

class SnippetSerializer(serializers.ModelSerializer):
    class Meta:
        model = Snippet
        fields = ['id', 'title', 'code', 'linenos', 'language', 'style']

ModelSerializer会自动：

1. 根据模型生成对应字段
2. 生成默认的create()和update()实现
3. 包含默认的验证逻辑

创建API视图

现在我们使用序列化器创建基本的API视图：

from django.http import HttpResponse, JsonResponse
from django.views.decorators.csrf import csrf_exempt
from rest_framework.parsers import JSONParser
from snippets.models import Snippet
from snippets.serializers import SnippetSerializer

@csrf_exempt
def snippet_list(request):
    """
    列出所有代码片段或创建新片段
    """
    if request.method == 'GET':
        snippets = Snippet.objects.all()
        serializer = SnippetSerializer(snippets, many=True)
        return JsonResponse(serializer.data, safe=False)
    
    elif request.method == 'POST':
        data = JSONParser().parse(request)
        serializer = SnippetSerializer(data=data)
        if serializer.is_valid():
            serializer.save()
            return JsonResponse(serializer.data, status=201)
        return JsonResponse(serializer.errors, status=400)

@csrf_exempt
def snippet_detail(request, pk):
    """
    获取、更新或删除一个代码片段
    """
    try:
        snippet = Snippet.objects.get(pk=pk)
    except Snippet.DoesNotExist:
        return HttpResponse(status=404)

    if request.method == 'GET':
        serializer = SnippetSerializer(snippet)
        return JsonResponse(serializer.data)
    
    elif request.method == 'PUT':
        data = JSONParser().parse(request)
        serializer = SnippetSerializer(snippet, data=data)
        if serializer.is_valid():
            serializer.save()
            return JsonResponse(serializer.data)
        return JsonResponse(serializer.errors, status=400)
    
    elif request.method == 'DELETE':
        snippet.delete()
        return HttpResponse(status=204)

配置URL路由后，我们就可以通过HTTP请求与API交互了。

测试API

启动开发服务器后，可以使用curl或httpie等工具测试API：

获取所有片段：

http http://127.0.0.1:8000/snippets/

获取特定片段：

http http://127.0.0.1:8000/snippets/1/

创建新片段：

http POST http://127.0.0.1:8000/snippets/ code="print(123)"

总结

通过本教程，我们学习了：

1. 如何定义序列化器来转换模型数据
2. 使用ModelSerializer简化序列化器定义
3. 创建基本的API视图处理CRUD操作
4. 测试API端点

虽然这只是一个基础实现，但已经展示了Django REST Framework的核心概念。在后续教程中，我们将介绍更高级的功能，如视图集、路由器和认证等，以构建更加强大和安全的API。