教程1：序列化

爱被打了一巴掌 2023-07-25 12:35 3阅读 0赞

> 作者：[Bright Xu][]

### 文章目录 ###

*   *  介绍
     *  设置新环境
     *  入门
     *  创建要使用的模型
     *  创建一个序列化器类 Serializer
     *  使用序列化器 Serializer
     *  使用ModelSerializer
     *  使用我们的序列化器编写常规Django视图
     *  测试我们第一次尝试使用Web API
     *  我们现在学到哪了

## 介绍 ##

本教程将介绍如何创建突出显示`Web API`的简单`pastebin`代码。在此过程中，它将介绍组成`REST framework`的各种组件，并让您全面了解所有内容如何组合在一起。

本教程相当深入，因此在开始之前，您可能应该先获得饼干和一杯自己喜欢的啤酒。如果您只想快速浏览一下，则应该转到[快速入门][Link 1]文档。

--------------------

**注意**：本教程的代码可在GitHub上的[encode / rest-framework-tutorial][encode _ rest-framework-tutorial]存储库中找到。完整的实施也可以作为沙盒版本进行在线测试，[可在此处获得][Link 2]。

--------------------

## 设置新环境 ##

在执行其他任何操作之前，我们将使用[venv][]创建一个新的虚拟环境。这将确保我们的程序包配置与我们正在处理的任何其他项目保持良好的隔离。

python3 -m venv env
    
    # Linux系统启动虚拟环境
    source env/bin/activate
    
    # Windows系统启动虚拟环境
    env\Scripts\activate

现在我们处于虚拟环境中，我们可以安装软件包要求。

pip install django
    pip install djangorestframework
    pip install pygments  # 我们将用它来高亮显示代码

**注意：** 要随时退出虚拟环境，只需键入`deactivate`。有关更多信息，请参阅[venv文档][venv]。

## 入门 ##

好的，我们已经准备好进行编码。首先，让我们创建一个要使用的新项目。

cd ~
    django-admin startproject tutorial
    cd tutorial

完成后，我们可以创建一个应用程序，用它来创建一个简单的Web API。

python manage.py startapp snippets

我们需要将我们的新`snippets`应用程序和该`rest_framework`应用程序添加到中`INSTALLED_APPS`。让我们编辑`tutorial/settings.py`文件：

INSTALLED_APPS = [
        ...
        'rest_framework',
        'snippets.apps.SnippetsConfig',
    ]

好的，我们准备开始了。

## 创建要使用的模型 ##

在本教程中，我们将从创建一个`Snippet`用于存储代码段的简单模型开始。继续编辑`snippets/models.py`文件。注意：良好的编程习惯包括注释。尽管您可以在本教程代码的存储库版本中找到它们，但在此我们省略了它们，仅关注代码本身。

from django.db import models
    from pygments.lexers import get_all_lexers
    from pygments.styles import get_all_styles
    
    LEXERS = [item for item in get_all_lexers() if item[1]]
    LANGUAGE_CHOICES = sorted([(item[1][0], item[0]) for item in LEXERS])
    STYLE_CHOICES = sorted([(item, item) for item in 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(choices=LANGUAGE_CHOICES, default='python', max_length=100)
        style = models.CharField(choices=STYLE_CHOICES, default='friendly', max_length=100)
    
        class Meta:
            ordering = ['created']

我们还需要为代码段模型创建初始迁移，并首次同步数据库。

python manage.py makemigrations snippets
    python manage.py migrate

## 创建一个序列化器类 Serializer ##

我们需要开始使用Web API的第一件事是提供一种将片段实例序列化和反序列化为诸如的表示形式的方法`json`。我们可以通过声明与Django形式非常相似的序列化器来做到这一点。在`snippets`名为目录的目录中创建一个文件，`serializers.py`然后添加以下内容。

from rest_framework import serializers
    from snippets.models import Snippet, LANGUAGE_CHOICES, STYLE_CHOICES
    
    
    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):
            """ Create and return a new `Snippet` instance, given the validated data. """
            return Snippet.objects.create(**validated_data)
    
        def update(self, instance, validated_data):
            """ Update and return an existing `Snippet` instance, given the validated data. """
            instance.title = validated_data.get('title', instance.title)
            instance.code = validated_data.get('code', instance.code)
            instance.linenos = validated_data.get('linenos', instance.linenos)
            instance.language = validated_data.get('language', instance.language)
            instance.style = validated_data.get('style', instance.style)
            instance.save()
            return instance

序列化程序类的第一部分定义了要进行序列化/反序列化的字段。该`create()`和`update()`方法定义实例如何完全成熟的创建或修改时调用`serializer.save()`

串行类非常类似于一个Django `Form`类，并且包括关于各个字段类似的验证标记，如`required`，`max_length`和`default`。

字段标志还可以控制在某些情况下（例如，呈现为HTML时）应如何显示序列化程序。`{'base_template': 'textarea.html'}`上面的标志等效于`widget=widgets.Textarea`在Django `Form`类上使用。这对于控制应如何显示可浏览的API尤其有用，我们将在本教程的后面部分看到。

实际上，我们也可以使用`ModelSerializer`该类节省一些时间，我们将在后面看到，但是现在我们将使序列化程序定义保持明确。

## 使用序列化器 Serializer ##

在继续之前，我们将使我们熟悉使用新的Serializer类。让我们进入Django shell。

python manage.py 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='foo = "bar"\n')
    snippet.save()
    
    snippet = Snippet(code='print("hello, world")\n')
    snippet.save()

现在，我们可以使用一些片段实例。让我们看一下序列化这些实例之一。

serializer = SnippetSerializer(snippet)
    serializer.data
    # {'id': 2, 'title': '', 'code': 'print("hello, world")\n', 'linenos': False, 'language': 'python', 'style': 'friendly'}

至此，我们已经将模型实例转换为Python本机数据类型。为了完成序列化过程，我们将数据渲染到中`json`。

content = JSONRenderer().render(serializer.data)
    content
    # b'{"id": 2, "title": "", "code": "print(\\"hello, world\\")\\n", "linenos": false, "language": "python", "style": "friendly"}'

反序列化是相似的。首先，我们将流解析为Python本地数据类型…

import io
    
    stream = io.BytesIO(content)
    data = JSONParser().parse(stream)

…然后将这些本机数据类型还原到完全填充的对象实例中。

serializer = SnippetSerializer(data=data)
    serializer.is_valid()
    # True
    serializer.validated_data
    # OrderedDict([('title', ''), ('code', 'print("hello, world")\n'), ('linenos', False), ('language', 'python'), ('style', 'friendly')])
    serializer.save()
    # <Snippet: Snippet object>

请注意，API与处理表单的相似程度。当我们开始编写使用序列化程序的视图时，相似性应该变得更加明显。

我们还可以序列化查询集而不是模型实例。为此，我们只需`many=True`在序列化器参数中添加一个标志即可。

serializer = SnippetSerializer(Snippet.objects.all(), many=True)
    serializer.data
    # [OrderedDict([('id', 1), ('title', ''), ('code', 'foo = "bar"\n'), ('linenos', False), ('language', 'python'), ('style', 'friendly')]), OrderedDict([('id', 2), ('title', ''), ('code', 'print("hello, world")\n'), ('linenos', False), ('language', 'python'), ('style', 'friendly')]), OrderedDict([('id', 3), ('title', ''), ('code', 'print("hello, world")'), ('linenos', False), ('language', 'python'), ('style', 'friendly')])]

## 使用ModelSerializer ##

我们的`SnippetSerializer`类复制了`Snippet`模型中的许多信息。如果我们可以使代码更简洁，那将是很好的。

就像Django提供`Form`类和`ModelForm`类一样，REST框架同时包含`Serializer`类和`ModelSerializer`类。

让我们看看使用`ModelSerializer`该类重构序列化器。再次打开`snippets/serializers.py`文件，并用`SnippetSerializer`以下内容替换该类。

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

序列化程序具有的一个不错的属性是，您可以通过打印序列化程序的表示形式来检查序列化程序实例中的所有字段。使用打开Django shell `python manage.py shell`，然后尝试以下操作：

from snippets.serializers import SnippetSerializer
    serializer = SnippetSerializer()
    print(repr(serializer))
    # SnippetSerializer():
    # id = IntegerField(label='ID', read_only=True)
    # title = CharField(allow_blank=True, max_length=100, required=False)
    # code = CharField(style={'base_template': 'textarea.html'})
    # linenos = BooleanField(required=False)
    # language = ChoiceField(choices=[('Clipper', 'FoxPro'), ('Cucumber', 'Gherkin'), ('RobotFramework', 'RobotFramework'), ('abap', 'ABAP'), ('ada', 'Ada')...
    # style = ChoiceField(choices=[('autumn', 'autumn'), ('borland', 'borland'), ('bw', 'bw'), ('colorful', 'colorful')...

重要的是要记住，`ModelSerializer`类并没有做任何特别神奇的事情，它们只是创建序列化器类的捷径：

*  自动确定的一组字段。
 *  `create()`和`update()`方法的简单默认实现。

## 使用我们的序列化器编写常规Django视图 ##

让我们看看如何使用新的Serializer类编写一些API视图。目前，我们将不使用REST框架的任何其他功能，而只是将视图编写为常规Django视图。

编辑`snippets/views.py`文件，然后添加以下内容。

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

API的根源将是一个视图，该视图支持列出所有现有的代码片段或创建新的代码片段。

@csrf_exempt
    def snippet_list(request):
        """ List all code snippets, or create a new snippet. """
        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令牌的客户端发布到该视图，因此需要将该视图标记为`csrf_exempt`。这通常不是您要做的，并且REST框架视图实际上比这更明智的行为，但是现在出于我们的目的。

我们还将需要一个与单个代码段相对应的视图，该视图可用于检索，更新或删除该代码段。

@csrf_exempt
    def snippet_detail(request, pk):
        """ Retrieve, update or delete a code snippet. """
        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)

最后，我们需要将这些视图联系起来。创建`snippets/urls.py`文件：

from django.urls import path
    from snippets import views
    
    urlpatterns = [
        path('snippets/', views.snippet_list),
        path('snippets/<int:pk>/', views.snippet_detail),
    ]

我们还需要连接`tutorial/urls.py`文件中的根urlconf ，以包含代码段应用程序的URL。

from django.urls import path, include
    
    urlpatterns = [
        path('', include('snippets.urls')),
    ]

值得注意的是，目前有一些边缘案例我们无法正确处理。如果我们发送格式错误的`json`，或者使用该视图无法处理的方法发出请求，那么最终将收到500个“服务器错误”响应。不过，这将暂时执行。

## 测试我们第一次尝试使用Web API ##

现在，我们可以启动一个提供摘要的示例服务器。

退出`Django shell`：

quit()

并启动Django的开发服务器。

python manage.py runserver
    
    Validating models...
    
    0 errors found
    Django version 1.11, using settings 'tutorial.settings'
    Development server is running at http://127.0.0.1:8000/
    Quit the server with CONTROL-C.

在另一个终端窗口中，我们可以测试服务器。

我们可以使用[curl][]或[httpie][]测试我们的API 。Httpie是使用Python编写的用户友好型HTTP客户端。让我们安装它。

可以使用pip安装httpie：

pip install httpie

最后，我们可以获得所有代码段的列表：

http http://127.0.0.1:8000/snippets/
    
    HTTP/1.1 200 OK
    ...
    [
      { 
        "id": 1,
        "title": "",
        "code": "foo = \"bar\"\n",
        "linenos": false,
        "language": "python",
        "style": "friendly"
      },
      { 
        "id": 2,
        "title": "",
        "code": "print(\"hello, world\")\n",
        "linenos": false,
        "language": "python",
        "style": "friendly"
      }
    ]

或者，我们可以通过引用其ID来获取特定的代码段：

http http://127.0.0.1:8000/snippets/2/
    
    HTTP/1.1 200 OK
    ...
    { 
      "id": 2,
      "title": "",
      "code": "print(\"hello, world\")\n",
      "linenos": false,
      "language": "python",
      "style": "friendly"
    }

同样，通过在Web浏览器中访问这些URL，可以显示相同的json。

## 我们现在学到哪了 ##

到目前为止，我们做的还不错，我们有一个序列化API，感觉与Django的Forms API非常相似，并且提供了一些常规的Django视图。

除了提供`json`响应外，我们的API视图目前并没有做任何特别的事情，并且我们仍然希望清理一些错误处理的极端情况，但这是一个正常运行的Web API。

在[本教程的第2部分中，][2]我们将看到如何开始改进。

[Bright Xu]: https://blog.csdn.net/weixin_44129085
[Link 1]: https://blog.csdn.net/weixin_44129085/article/details/105494993
[encode _ rest-framework-tutorial]: https://github.com/encode/rest-framework-tutorial
[Link 2]: https://restframework.herokuapp.com/
[venv]: https://docs.python.org/3/library/venv.html
[curl]: https://curl.haxx.se/
[httpie]: https://github.com/jakubroztocil/httpie#installation
[2]: https://www.django-rest-framework.org/tutorial/2-requests-and-responses/