[Django-REST-framework教程][01]序列化

版权声明

本文出自 “ 幻冥极地 ” 博客 ,作者 小貘 采用 署名-非商业性使用-相同方式共享 协议。转载时请务必以超链接形式标明文章 原始出处 、作者信息和本声明。否则将追究法律责任。
https://www.moorehy.com/archives/299

介绍

本教程将覆盖创建一个简单的粘贴高亮代码的 WebAPI 。在这个过程中,我们将介绍编写REST框架应用所用到的各种组件,并让您深刻的理解到他们是如何一起工作的。

本教程相当的深入,所以在开始前,您可以拿出些饼干和一杯最喜欢的啤酒。如果您仅仅想快速预览下本框架,您可以前往查看 快览文档

注意

本教程的所有源码可以在Github上获取到 tomchristie/rest-framework-tutorial 。完整的实例也已作为一个测试用的沙盒版本上线, 点此前往

设置一个新的环境

在开始前,我们先使用 virtualenv 创建一个虚拟环境。这可以很好的确保我们的包(package)配置与其他的工作项目隔离。

现在我们已经处于一个虚拟环境下了,接下来安装我们需要的包(package)。

注意: 任何时候想退出虚拟环境,只需执行 deactivate 。更多信息科查看 virtualenv官方文档

开始

好,让我们准备开始编码。首先创建一个新的工程(project)。

紧接着创建一个用于实现简单 Web API 的应用(app)。

我们需要将我们新创建的 snippets 应用和 rest_framework 应用添加到 INSTALLED_APPS 中。编辑 tutorial/settings.py 文件:

如果您正使用的Django版本小于1.9,您需要将上面的 snippets.apps.SnippetsConfig 替换为 snippets

好了,我们准备好了。

创建数据模型

为了实现本教程的目的,我们开始创建一个简单的 Snippet 模型,用来存储代码片段。编辑 snippets/models.py 文件。 注意:好的变成习惯包括合理的注释。您可以在这个教程源码的版本库中看到他们,此处我们为了关注代码本身忽略了注释。

为我们的 snippet 模型创建初始化迁移(migration),然后首次同步数据库。

创建序列化类

开始编写 Web API 的第一件事是提供一个序列化&反序列化 snippet 实例为表现字串的方法,如: json 。我们可以通过声明序列化器(serializers)来实现该功能,其工作方式与 Django 的表单非常相似。在 snippets 路径下创建一个 serializers.py 文件,然后添加如下内容。

序列化器类(serializer)的第一部分定义了用于序列化/反序列化的属性(fields)。 create()update() 方法定义了当调用 serializer.save() 时如何完全合格的被创建和修改。

序列化器类与 Django Form 类非常相似,包括在各种属性(fields)上相似的验证器标志,如: requiredmax_lengthdefault

属性(field)标志也可以控制序列化器在特定的环境下如何被显示,例如渲染成 HTML 时。上面的 {'base_template': 'textarea.html'} 标志相当于在 Django Form 类中设置 widget=widgets.Textarea 。这在控制可浏览 API 如何显示时尤其有用,我们将在之后的教程中看到。

像我们之后看到的,实际上我们可以通过使用 ModelSerializer 类来节省自己一点时间,但是现在我们使用明确定义的序列化器。

使序列化器工作

再进一步讨论之前,我们将熟悉使用我们新创建的序列化器类。让我们进入 Django 的 shell 。

引入(imports)一些必要的包后,创建一些用于工作的代码片段(译者注:此处代码片段指用于代码高亮应用的业务)。

现在我们有了一些可以用于操作的代码片段实例。让我们看一下序列化后的实例。

此处,我们已经将模型实例翻译成了 Python 原生数据类型。为了完成序列化过程,我们将数据渲染成 json

反序列化是类似的。首先我们解析一个流到 Python 原生数据类型……

……然后存储这些原生数据类型到一个被完全填充的对象实例中。

注意 API 与表单工作的相似性。当我们开始编写使用该序列化器的视图(views)时,这种相似性会愈加明显。

我们也可以序列化查询结果集(querysets)而不是模型实例。我们可以通过添加 many=True 标志到序列化器参数中来实现。

使用模型序列化器

我们的 SnippetSerializer 类重复了很多已经包含在 Snippet 模型中的信息。如果我们可以是代码更简洁一些,那将是极好的。

与 Django 提供的 Form 类和 ModelForm 类同样的方式, REST 框架包含了 Serializer 类和 ModelSerialzer 类。

让我们使用 ModelSerializer 类重构下我们的序列化器。重新打开 snippets/serializers.py 文件,用下列代码实现替换 SnippetSerializer 类。

序列化器拥有的一个很棒的属性是,通过打印输出(representation),您可以查看序列化器实例中的所有属性(fields)。使用 python manage.py shell 打开 Django 的 shell ,然后操作如下:

重要的是记住 ModelSerializer 类不会做任何神奇的事情,他们只是创建序列化器类的简单快捷方式:

  • 自动定义属性(fields)集。
  • create()update() 方法的简单默认实现。

使用我们的序列化器编写标准的 Django 视图

让我们看下如何使用我们新的序列化器类编写 API 视图。当前我们不使用任何 REST 框架的其他特性,仅仅编写一个标准的 Django 视图。

编辑 snippets/views.py 文件,添加如下内容。

我们 API 的根节点将是一个的视图,其支持列出全部已存在代码片段,或创建一个新的代码片段。

注意因为我们打算从客户端 POST 到该视图,故我们需要使用 csrf_exempt 装饰器修饰该视图,从而提供 CSRF 令牌。这通常不是你想做的事, REST 框架视图实际上会使用比这更明智的行为,但是现在它符合我们的需求。

我们还需要一个视图,用来对单独的代码片段提供检索、更新、删除功能。

最后我们将这些视图连接上。创建 snippets/urls.py 文件:

我们还需要将其链接到 tutorial/urls.py 文件中的根 url 配置上,从而包含我们的代码片段(snippet)应用的 URLs 。

值得注意的是,目前我们还没有处理好几个边缘案例。如果我们发送了畸形的 json ,或者一个请求使用了视图未处理的方法,那么我们将收到 500 “server error” 响应。不过,现在这样足够了。

测试我们在 WebAPI 上的第一次尝试

现在我们可以开启一个示例服务器来服务于我们的代码片段应用(snippets)。

退出 shell……

……运行 Django 的开发服务器。

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

我们可以使用 curlhttpie 测试我们的 API 。 Httpie 是一个用 Python 实现的用户友好的 http 客户端。让我们安装它。

您可以使用 pip 安装 httpie:

最后,我们可以获取一个所有代码片段(snippets)的列表:

或者,我们可以通过引用它的 id 获取特定的代码片段(snippet):

相似的,您可以通过在 web 浏览器中访问这些 URLs 来获得相同的 json 响应内容。

我们现在在哪里

到目前为止,我们做得很好。我们得到了一个序列化的 API ,它与 Django 的表单 API 非常相似,和一些标准的 Django 视图。

这里我们的 API 视图除了提供 json 响应外没有做任何特别的事情,还有一些异常处理的工作需要做,但这只是一个功能性的 WebAPI 。

教程二 中,我们将学习如何进行改进。

One thought on “[Django-REST-framework教程][01]序列化

发表评论

电子邮件地址不会被公开。 必填项已用*标注