使用 Django REST 框架开发 API

如果您了解所从事领域的基础知识，那么您就可以掌握任何技术，达到更高的开发水平，并创建更好的产品。在本文中，我们将逐步讨论如何构建 API 以及如何构建 API。我相信这对所有 Django 初学者来说都很有用，因为 REST API 在每个应用程序或软件中都用于连接后端和前端部分。如果您掌握了这些，您就可以构建各种产品。

为什么使用 Django REST 框架？

许多框架都允许您轻松构建博客应用程序的 API，但我们只使用其中一种——Django REST 框架。它在很多方面都很方便，并具有以下优势：

• 其可通过 Web 浏览的 API为您的开发人员带来了巨大的可用性优势。
• 身份验证策略包括OAuth1和OAuth2的包。
• 序列化支持ORM和非 ORM数据源。
• 它完全可自定义。如果您不需要更强大的功能，只需使用基于函数的常规视图即可。
• 它拥有丰富的文档和强大的社区支持。
• 它被Mozilla、Red Hat、Heroku和Eventbrite等国际知名公司使用和信任。

API 的分步指南

在本 Django REST 框架教程中，我们将详细介绍构建 API 的所有阶段。

设置开发环境

首先，你需要为你的操作系统安装Python 依赖项。如果你使用的是 Windows，你可以使用本手册或VirtualBox轻松安装 Linux 作为辅助操作系统。

首先，使用pyenv，一个简单而有效的 Python 管理工具。它是我们的得力助手。它允许我们更改全局 Python 版本、安装多个 Python 版本、设置项目特定的 Python 版本，以及管理虚拟 Python 环境。

如果您使用的是 Mac OS 或 Linux，则安装应该很容易：

$ git clone https://github.com/pyenv/pyenv.git ~/.pyenv

定义环境变量PYENV_ROOT以指向 pyenv repo 克隆的路径。然后，将其添加$PYENV_ROOT/bin到您的$PATHpyenv 命令行实用程序的访问路径中。

$ echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc
$ echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc

将 pyenv 单元添加到您的 shell 以启用 shims 和自动完成功能。

$ echo -e 'if command -v pyenv 1>/dev/null 2>&1; then\n  eval "$(pyenv init -)"\nfi' >> ~/.bashrc

重启 shell，使路径更改生效。现在，你可以开始使用 pyenv 了。

$ exec "$SHELL"

此时，安装最新稳定版本的 Python。现在这个……

$ pyenv install 3.7.4

...并为您的项目创建一个环境。

$ pyenv virtualenv 3.7.4 blog

创建 Django 项目

现在，我们将创建一个项目文件夹并导航到新创建的目录。

$ mkdir projects && cd projects

下一步是创建一个 Django 项目。有几种方法可以做到这一点。

就我个人而言，我更喜欢从模板开始项目，并使用我们Web 开发公司已经实现的Django Stars 后端框架。这是一个很棒的工具，因为……

• Django 项目根据 Django Stars 代码样式要求进行格式化，
• django-environ 帮助保存环境中的所有配置，
• psycopg2 是默认的数据库驱动程序，
• django-extensions/ipython/ipdb 用于调试目的，
• 提供 pytest 和 pylava 用于测试，并且
• 重新定义的 startapp 命令允许您根据Django Stars 代码样式要求创建应用程序。

以下命令可帮助您从模板启动项目：

$ curl https://be.skeletons.djangostars.com/startproject | bash

一开始，系统会提供几个 Python 版本供你使用。请选择 Python 3.7 版本。

将项目名称设置为django_blog。

由于我们将使用 Django Rest Framework，因此我们应该选择第三个选项：

如果您知道您的项目需要 Celery，您也可以选择第一个选项并按“确定”。

好了，我们刚才做的是从模板创建了一个项目。现在让我们导航到项目名称目录：

$ cd django_blog

我们的项目结构如下：

安装满足要求的软件包

要运行项目，我们需要安装一些包，这些包在requirements/dev.txt.
因此，我们安装本地开发所需的包。

导航到 API 目录：

$ cd api

并安装依赖项。

如果您需要添加任何其他包，只需将您的包添加到 dev.txt 文件以进行本地开发，或者添加到 common.txt（如果您需要将其安装在服务器上）。

接下来，我们需要添加 Pillow 包，它默认不包含在我们安装的软件包中。打开
requirements/common.txt文件，在末尾添加 Pillow==6.1.0。然后运行：

$ pip install -r requirements/dev.txt

该文件包含将要安装的所有软件包的列表。

引导数据库

我们的项目需要一个数据库。大多数 Django 开发者倾向于在所有环境（即开发、预发布和生产系统）中使用 PostgresQL。有些人在本地开发中使用 SQLite，在生产环境中使用 PostgreSQL。Django ORM 允许您同时处理这两个数据库。我强烈建议您尽可能保持开发环境和生产环境的相似性，并使用相同的数据库。

有几种方法可以引导数据库：

• 使用 SQLite

为了简化数据库引导，我们可以使用 SQLite。它是一个进程内库，实现了一个独立的、无服务器的、零配置的事务型 SQL 数据库引擎。

您需要做的就是打开 .env 文件并替换：

和

在这里，我们使用django-environ包，它允许你根据环境定义配置。你可以阅读《十二要素应用》一文，了解更多关于这种方法的信息。

• 使用 PostgreSQL

PostgreSQL 是一个功能强大的开源对象关系数据库系统。它使用并扩展了 SQL 语言，并拥有许多功能，可让您安全地存储和扩展最复杂的数据工作负载。该系统比 SQLite 略微复杂，因此您可能需要了解更多信息。

使用Docker安装 PostgreSQL 要容易得多。Docker是一个开源工具，可以自动在软件容器内部署应用程序。如果您还不熟悉 Docker，可以查看一些关于如何安装和使用docker-compose 的说明。

然后只需打开一个新选项卡并运行：

$ docker-compose -f build/docker-compose-dev.yml up

接下来，我们应该应用初始迁移：

$ python manage.py migrate

这会将所有以前未应用的迁移应用到 Django 安装附带的数据库。

https://github.com/olegkovalov/django_blog/commit/4f9b20bafc69fb686026d112592c549bd8b6e858

创建博客应用程序

至此，我们已经创建了一个 Django 项目，安装了所需的软件包，并启动了数据库。这意味着我们现在终于可以使用以下命令创建一个博客应用程序了：

$ python manage.py startapp blog

通过执行此操作，您还创建了一个新目录。它将在apps/blog.

现在，我们应该在中注册我们的应用程序‘INSTALLED_APPS’。

将“博客”添加到您的‘INSTALLED_APPS’设置中‘api/django_blog/settings/django.py’

API 的测试驱动开发 (TDD)

您可能已经了解，测试驱动开发 (TDD) 是一种专注于在开始实现应用程序业务逻辑之前编写测试的方法。编写测试首先需要您认真思考您希望从代码中得到什么。但除此之外，TDD 还有许多其他好处：

1. 反馈迅速，规范详细；
2. 减少返工时间和调试器所花的时间；
3. 可维护、灵活且易于扩展的代码；
4. 缩短上市开发时间；
5. 提高开发人员的工作效率；
6. SOLID 代码；以及
7. 干净的界面。

此外，TDD 还会告诉你上次的更改（或重构）是否破坏了之前正常工作的代码。此外，它还会强制彻底简化代码——你只需编写满足测试需求的代码即可。此外，你还被迫编写专注于一件事的小类。此外，它允许设计不断发展，并适应你对问题不断变化的理解。

生成的单元测试很简单，可以作为代码的文档。由于 TDD 用例是以测试的形式编写的，因此其他开发人员可以将测试视为代码预期工作方式的示例。

在为我们的 API 编写测试之前，让我们退一步看看 HTTP 以及它如何与 Django REST 框架交互。

超文本传输​​协议 (HTTP) 是一种用于分布式、协作式超媒体信息系统的应用协议。HTTP 定义了诸如 GET、POST、PUT、DELETE、OPTIONS 和 HEAD 之类的方法，用于指示应对您指定的资源执行的操作。这些方法可以根据安全性和幂等性的特性进行定义（您可以在此处了解更多信息）。根据协议，REST API 依赖于这些方法，因此您可以随意为每种类型的操作使用适当的 HTTP 方法。

让我们将其应用到资源“帖子”中。

如何编写测试

有了unittests框架，编写测试变得非常容易。

打开‘api/django_blog/apps/blog/tests/test_models.py’文件并添加以下代码：

打开‘api/django_blog/apps/blog/models/post.py’文件，并定义 Post 和 Tags 的模型：

我们的 Post 模型继承自‘CoreModel’，因此可以将中定义的字段和方法‘CoreModel’添加到‘Post’模型中。

现在，让我们对我们创建的模型运行第一个测试：

$ python manage.py test

这意味着测试已成功运行。

打开‘api/django_blog/apps/blog/tests/tests.py’并添加您的 API 测试：

序列化器

序列化器是一个框架，它允许将复杂数据（例如查询集和模型实例）转换为原生 Python 数据类型。然后，这些数据可以轻松地渲染为JSON、XML或其他内容类型。序列化器也以相反的方式工作——反序列化​​允许在验证传入数据后，将解析后的数据转换回复杂类型。REST 框架中的序列化器的工作方式类似于 Django 的 Form 和 ModelForm 类。

声明序列化器

打开‘api/django_blog/apps/blog/rest_api/serializers/post.py’并添加：

现在，我们可以使用PostSerializer来序列化一篇文章或者一串文章。

打开‘api/django_blog/apps/blog/rest_api/views/blog_views.py'并添加以下代码来定义API视图：

将端点的 URL 添加到

‘api/django_blog/apps/blog/rest_api/urls.py’这将是您的 API 可用的 URL。

打开‘api/urls.py’并包含博客的应用程序 URL：

运行测试

现在，您可以使用以下命令测试您的 API：

$ python manage.py test

瞧！测试已成功完成。

可浏览的API

API 可能代表应用程序编程接口 (API)，但人类也必须能够读取这些 API——总得有人进行编程。因此才有了可浏览的 API。使用 Django REST 框架，当请求 HTML 格式的资源时，您可以为每个资源生成人性化的 HTML 输出。这些页面允许您轻松浏览资源，并内置表单，以便使用 POST、PUT 和 DELETE 向资源提交数据。

让我们使用可浏览的 REST Framework 界面测试我们的 API。首先，启动开发服务器：

$ python manage.py runserver_plus

然后，打开您选择的浏览器并访问此网址：

创建一篇包含图片文件的新文章。填写“标题”和“正文”字段，在底部的表单中选择一个图片文件，然后点击“发布”。页面将重新加载新内容。

如果您想使用真实的帖子，请随时访问此页面。

版本控制

版本控制是 API 设计中至关重要的一部分，它允许您改进 API 资源的表示形式，并调整不同客户端之间的行为。REST 框架提供了许多不同的版本控制方案。版本控制由传入的客户端请求确定，可以基于请求 URL 或请求标头。

在这个例子中，我们使用 url 路径版本控制方法。

打开‘api/django_blog/settings/django.py’并添加：

如果响应已更改并且您决定定义不同的 API 版本，则可以按如下方式处理：

记录你的 API

REST 框架内置了生成 OpenAPI 模式的支持。这些模式可以与用于构建 API 文档的工具一起使用。

REST 框架提供的可浏览 API 使您的 API 完全可以自我描述。您只需在浏览器中访问 URL 即可获取每个 API 端点的文档。

不过，也有很多优秀的第三方文档包可用。例如，让我们尝试集成drf-yasg。它的目标是尽可能多地实现OpenAPI规范（嵌套模式、命名模型、响应主体、枚举/模式/最小/最大验证器、表单参数等），并生成可与代码生成工具一起使用的文档。

打开终端，输入：

$ pip install -U drf-yasg

打开‘api/django_blog/settings/django.py’并添加 INSTALLED_APPS‘drf_yasg’包：

此外，我们还应该包含生成的文档的 URL：

您可以在此文档中找到有关您的 API 的文档。

如果您想实现新功能或尝试一下，请随意克隆或分叉我的git hub repo。

现在，让我们看看为什么 Django REST 框架对于构建 API 如此实用。Django REST 框架 (DRF) 提供了大量功能：

• 使用通用视图轻松创建资源- 它们允许您快速构建与数据库模型紧密映射的 API 视图；
• 身份验证机制将传入请求与一组识别凭证相关联；
• 权限授予任何经过身份验证的用户访问，并拒绝任何未经身份验证的用户访问；
• 节流表示一种临时状态，用于控制客户端对 API 发出的请求速率；
• 通过 Django 提供的缓存实用程序进行缓存；
• 过滤允许您限制响应中返回的项目；
• 分页允许您选择如何将大结果集拆分为单独的数据页；
• 状态代码——REST 框架包含一组命名常量，您可以使用它们使您的代码更加透明和可读；
• 版本控制可以改变不同客户端之间的行为；
• 可浏览的 API使您能够读取 API。

如果您仍有疑问并希望了解更多信息，有很多优秀的 Django REST API 教程和资源可供您提升。以下是我们软件开发团队Django Stars 强烈推荐的阅读清单。如果您需要处理嵌套对象，这里有一个实用的库，或许能派上用场。此外，欢迎访问django_blog 仓库获取灵感和想法。正如我之前所说，如果您已经掌握了基础知识，就可以在此基础上继续学习。考虑到 API 的通用性，您将能够使用任何类型的产品，这将使您成为软件开发领域不可或缺的团队成员和万能战士。

本指南最初发布于 Django Stars 博客，介绍了如何使用 Django REST Framework 开发 API 。作者是Django Stars首席软件工程师 Oleg Kovalyov。