如何利用 Django 进行 API 开发

2022 年 6 月 03 日
本文字数：7226 字
阅读完需：约 24 分钟

Django REST Framework 与 Django Web 框架协同工作以创建 Web API。我们不能仅使用 Django Rest Framework 来构建 Web API 。在安装和配置 Django 本身之后，必须始终将其添加到项目中。

在本章中，我们将回顾传统 Django 和 Django REST Framework 之间的异同。最重要的一点是，Django 创建的网站包含网页，而 Django REST Framework 创建的 Web API 是 URL 端点的集合，这些 URL 端点包含返回 JSON 的可用 HTTP 动词。

为了说明这些概念，我们将使用传统的 Django 建立一个基本的 Library 网站，然后使用 Django REST Framework 将其扩展为 Web API 。

Django 快速开发

首先，我们需要在计算机上有一个专用目录来存储代码。它可以放置在任何地方，但为了方便起见，如果您使用的是 Mac，我们可以将其放在“桌面”文件夹中。

$ cd ~/Desktop$ mkdir code && cd code

复制代码

该代码文件夹将成为本书所有代码的位置。下一步是为我们的库站点创建一个专用目录，通过 Pipenv 安装 Django ，然后使用 shell 命令进入虚拟环境。您应该始终为每个新的 Python 项目使用专用的虚拟环境。

$ mkdir library && cd library$ pipenv install django==2.2.6$ pipenv shell(library) $

复制代码

Pipenv 在当前目录中创建一个 Pipfile 和一个 Pipfile.lock 。命令行前括号中的（library）表明我们的虚拟环境处于活动状态。

传统的 Django 网站由一个项目 project 和一个（或多个）代表不同功能的应用 apps 组成。让我们使用 startproject 命令创建一个新项目。别忘了加上句号。最后将代码安装在当前目录中。如果不包括句点，则 Django 默认会创建一个附加目录。

(library)$ django-admin startproject library_project .

复制代码

Django 会自动为我们生成一个新项目，我们可以使用 tree 命令看到它。（注意：如果在 Mac 上无法使用 tree ，请使用 Homebrew ：brew install tree 安装。）

(library) $ tree .├── Pipfile├── Pipfile.lock├── library_project│ ├── __init__.py│ ├── settings.py│ ├── urls.py│ └── wsgi.py└── manage.py

复制代码

这些文件具有以下定义：

__init__.py是将目录视为软件包的 Python 方法；它是空的
settings.py包含我们项目的所有配置
urls.py控制顶级 URL 路由
wsgi.py代表 Web 服务器网关界面，可帮助 Django 服务于最终网页
manage.py执行各种 Django 命令，例如运行本地 Web 服务器或创建新应用。

运行 migrate 将数据库与 Django 的默认设置同步，然后启动本地 Django Web 服务器。

(library) $ python manage.py migrate(library) $ python manage.py runserver

复制代码

打开 Web 浏览器，访问 http://127.0.0.1:8000/ 以确认我们的项目已成功安装。

第一个 app

典型的下一步是开始添加代表功能不同区域的应用程序。一个 Django 项目可以支持多个应用程序。

通过键入 Control + c 停止本地服务器，然后创建一个 books 应用程序。

(library) $ python manage.py startapp books

复制代码

现在再查看一下 Django 生成了什么文件。

.├── Pipfile├── Pipfile.lock├── books│   ├── __init__.py│   ├── admin.py│   ├── apps.py│   ├── migrations│   │   └── __init__.py│   ├── models.py│   ├── tests.py│   └── views.py├── db.sqlite3├── library_project│   ├── __init__.py│   ├── settings.py│   ├── urls.py│   └── wsgi.py└── manage.py

复制代码

每个应用程序都有一个 __init__.py 文件，将其标识为 Python 软件包。创建了 6 个新文件：

admin.py 是内置 Django Admin 应用程序的配置文件
apps.py 是应用程序本身的配置文件
migrations/ 目录存储用于数据库更改的迁移文件
models.py 是我们定义数据库模型的地方
tests.py 用于我们的应用程序特定测试
views.py 是我们处理 Web 应用程序的请求/响应逻辑的地方

通常，开发人员还会在每个应用程序内创建一个 urls.py 文件进行路由。

让我们构建文件，以便我们的图书馆项目列出首页上的所有书籍。将您选择的文本编辑器打开到 settings.py 文件。第一步是将新应用添加到我们的 INSTALLED_APPS 配置中。我们总是在底部添加新应用，因为 Django 会按顺序读取它们，并且我们希望内置的核心 Django 应用（例如 admin 和 auth ）在加载我们的应用之前已经被加载。

# library_project/settings.pyINSTALLED_APPS = [     'django.contrib.admin',     'django.contrib.auth',     'django.contrib.contenttypes',     'django.contrib.sessions',     'django.contrib.messages',     'django.contrib.staticfiles',        # Local    'books.apps.BooksConfig', # new]

复制代码

然后运行迁移以使我们的数据库与更改同步。

(library) $ python manage.py migrate

复制代码

传统 Django 中的每个网页都需要多个文件：视图，URL 和模板。但是首先我们需要一个数据库模型，所以让我们从这里开始。

Models

在您的文本编辑器中，打开文件 book/models.py 并进行如下更新：

# books/models.pyfrom django.db import models
class Book(models.Model):    title = models.CharField(max_length=250)    subtitle = models.CharField(max_length=250)     author = models.CharField(max_length=100)     isbn = models.CharField(max_length=13)        def __str__(self):         return self.title

复制代码

这是一个基本的 Django 模型，我们在最上面一行从 Django 导入模型，然后创建一个扩展它的 Book 类。有四个字段：标题，副标题，作者和 isbn 。我们还包括 __str__ 方法，以便稍后在管理员中显示书名。

请注意，ISBN 是分配给每本出版书籍的唯一的 13 个字符的标识符。

由于我们创建了一个新的数据库模型，因此我们需要创建一个迁移文件来进行处理。指定应用名称是可选的，但建议在此处使用。我们可以只键入 python manage.py makemigrations，但是如果有多个应用程序进行了数据库更改，那么这两个应用程序都将被添加到迁移文件中，这使得将来的调试更加困难。保持您的迁移文件尽可能具体。

然后运行迁移以更新我们的数据库。

(library) $ python manage.py makemigrations books (library) $ python manage.py migrate

复制代码

到目前为止，一切都很好。

Admin

我们可以开始通过内置的 Django 应用将数据输入到我们的新模型中。但是我们必须首先做两件事：

创建一个超级用户帐户并更新 admin.py ，以便显示 books 应用程序。从超级用户帐户开始。在命令行上运行以下命令：

(library) $ python manage.py createsuperuser

复制代码

按照提示输入用户名，电子邮件和密码。请注意，出于安全原因，输入密码时屏幕上不会显示文本。

现在更新我们的图书应用的 admin.py 文件。

# books/admin.pyfrom django.contrib import admin from .models import Book

admin.site.register(Book)

复制代码

这就是我们所需要的！再次启动本地服务器。

(library) $ python manage.py runserver

复制代码

导航到 http://127.0.0.1:8000/admin 并登录。

您将被重定向到管理员主页。

单击书籍的链接。

然后点击右上角的“添加图书+”按钮。

我已经输入了 Django 初学者书籍的详细信息。您可以在此处输入任何文本。纯粹是出于演示目的。单击“保存”按钮后，我们将重定向到列出所有当前条目的“书籍”页面。

我们传统的 Django 项目现在有数据，但是我们需要一种将其公开为网页的方法。这意味着创建视图，URL 和模板文件。现在开始吧。

Views

views.py 文件控制如何显示数据库模型内容。由于我们要列出所有书籍，因此可以使用内置的通用类 ListView。更新 books/views.py 文件。

# books/views.pyfrom django.views.generic import ListView
from .models import Book
class BookListView(ListView):     model = Book    template_name = 'book_list.html'

复制代码

首先，我们导入了 ListView 和 Book 模型。然后，我们创建一个 BookListView 类，该类指定要使用的模型和模板（尚未创建）。

在拥有一个正常工作的网页之前，需要执行两个步骤：制作模板并配置 URL 。让我们从 URL 开始。

URLs

我们需要同时设置项目级别的 urls.py 文件，然后在 books 应用程序中设置一个。用户访问我们的网站时，他们将首先与 library_project/urls.py文件进行交互，因此，请先对其进行配置。

# library_project/urls.pyfrom django.contrib import adminfrom django.urls import path, include # new
urlpatterns = [    path('admin/', admin.site.urls),     path('', include('books.urls')), # new]

复制代码

前两行会导入内置的管理应用程序，路线的路径，并包括将与我们的图书应用程序一起使用的内容。如果用户转到 /admin/，他们将被重定向到 admin 应用。我们在图书应用路由中使用空字符串 ' '，这意味着首页上的用户将直接重定向到图书应用。

现在，我们可以配置我们的 books/urls.py 文件。但是，糟糕！ Django 由于某种原因在应用程序中默认不包含 urls.py 文件，因此我们需要自己创建它。

(library) $ touch books/urls.py

复制代码

现在，在文本编辑器中更新新文件。

# books/urls.pyfrom django.urls import pathfrom .views import BookListView
urlpatterns = [    path('', BookListView.as_view(), name='home'),]

复制代码

我们导入视图文件，在空字符串''处配置 BookListView ，并添加命名 URL 主页作为最佳实践。

Django 的工作方式，现在，当用户转到我们网站的主页时，他们将首先点击 library_project/urls.py 文件，然后将其重定向到使用 BookListView 指定的 books/urls.py。在此视图文件中，Book 模型与 ListView 一起使用以列出所有书籍。

最后一步是创建我们的模板文件，以控制实际网页上的布局。我们已经在视图中将其名称指定为book_list.html。其位置有两个选项：默认情况下，Django 模板加载器将在以下位置的 books 应用程序内查找模板：books/templates/books/book_list.html。我们也可以改为创建一个单独的项目级模板目录，然后更新 settings.py 文件以指向该目录。

首先在 books 应用中创建一个新的模板文件夹，然后在其中创建一个 books 文件夹，最后是一个book_list.html 文件。

(library) $ mkdir books/templates(library) $ mkdir books/templates/books(library) $ touch books/templates/books/book_list.html

复制代码

然后更新 template 文件，

<!-- books/templates/books/book_list.html --><h1>All books</h1>{% for book in object_list %}    <ul>        <li>Title: {{ book.title }}</li>        <li>Subtitle: {{ book.subtitle }}</li>        <li>Author: {{ book.author }}</li>        <li>ISBN: {{ book.isbn }}</li>    </ul>{% endfor %}

复制代码

Django 内置了允许基本逻辑的模板语言。在这里，我们使用 for 标签来遍历所有可用的书。模板标签必须包含在左/右括号和括号内。因此，格式始终为{％for ...％}，然后我们必须稍后使用{％endfor％}关闭循环。

我们要遍历的是对象，其中包含 ListView 提供的所有可用书籍。该对象的名称为 object_list 。因此，为了遍历每本书，我们在{% for book in object_list ％}。然后显示模型中的每个字段。

网页

现在，我们可以启动本地 Django 服务器并查看我们的网页。

(library) $ python manage.py runserver

复制代码

导航至位于 http://127.0.0.1:8000/ 的主页。

如果我们在管理员中添加其他图书，则它们也都将出现在此处。

这是对传统 Django 网站的快速浏览。现在，向其中添加一个 API ！

Django REST 框架

就像其他任何第三方应用程序一样，添加了 Django REST Framework。如果本地服务器 Control + c 仍在运行，请确保退出它。然后在命令行上键入以下内容。

(library) $ pipenv install djangorestframework==3.10.3

复制代码

在我们的 settings.py 文件中，将 rest_framework 添加到 INSTALLED_APPS 配置中。我喜欢在第三方应用程序和本地应用程序之间做出如下区分，因为在大多数项目中，应用程序的数量迅速增长。

最终，我们的 API 将公开一个端点，该端点列出 JSON 中的所有书籍。因此，我们将需要一个新的 URL 路由，一个新的视图以及一个新的序列化器文件（稍后将对此进行更多介绍）。

我们可以用多种方法来组织这些文件，但是我的首选方法是创建一个专用的 api 应用程序。这样，即使将来我们增加更多应用程序，每个应用程序都可以包含专用网页所需的模型，视图，模板和 url，但是整个项目的所有 API 专用文件都将驻留在专用 api 应用程序中。

让我们新建一个 api 应用程序。

(library) $ python manage.py startapp api

复制代码

然后增加到 INSTALLED_APPS

# library_project/settings.pyINSTALLED_APPS = [    'django.contrib.admin',    'django.contrib.auth',    'django.contrib.contenttypes',    'django.contrib.sessions',    'django.contrib.messages',    'django.contrib.staticfiles',
    # 3rd party    'rest_framework',
    # Local Apps    'books.apps.BooksConfig',    'api.apps.ApiConfig', # new]

复制代码

api 应用程序将没有自己的数据库模型，因此无需像通常那样创建迁移文件和更新数据库。

URLs

从 URL 配置开始。添加 API 端点就像配置传统 Django 应用的路由一样。首先，在项目级别，我们需要包括 api 应用程序并配置其 URL 路由，即 api/。

from django.contrib import adminfrom django.urls import path, include
urlpatterns = [    path('admin/', admin.site.urls),    path('', include('books.urls')),    path('api/', include('api.urls')), # new]

复制代码

然后在 api 应用程序中创建 urls.py 文件。

(library) $ touch api/urls.py

复制代码

然后更新这个文件，如下：

# api/urls.pyfrom django.urls import path

from .views import BookAPIView

urlpatterns = [    path('', BookAPIView.as_view()),]

复制代码

一切准备就绪。

Views

接下来是我们的 views.py 文件，该文件依赖 Django REST Framework 的内置通用类视图。这些是故意模仿传统 Django 基于类的通用视图的格式，但它们不是一回事。

为避免混淆，某些开发人员将调用 API 视图文件 apiviews.py 或 api.py。就个人而言，在专用的 api 应用程序中工作时，我发现仅调用 Django REST 框架视图文件 views.py 并不会造成混淆，但是在这一点上意见不一。

在我们的 views.py 文件中，将其更新为如下所示：

# api/views.py
from rest_framework import generics
from books.models import Bookfrom .serializers import BookSerializer

class BookAPIView(generics.ListAPIView):    queryset = Book.objects.all()    serializer_class = BookSerializer

复制代码

在最上面的几行中，我们导入 Django REST Framework 的通用类视图，我们的 Books 应用中的模型以及 api 应用中的序列化器（我们将在下一个序列化器中导入）。

然后，我们创建一个 BookAPIView ，它使用 ListAPIView 为所有书籍实例创建一个只读端点。有许多通用的视图，我们将在后面的章节中进一步探讨它们。

在我们的视图中，仅需执行两个步骤，即指定所有可用书籍的 queryset ，然后指定将成为 BookSerializer 的 serializer_class。

Serializers

序列化器将数据转换为易于在 Internet 上使用的格式（通常为 JSON ），并显示在 API 端点上。在接下来的章节中，我们还将更深入地介绍序列化器和 JSON 。现在，我想演示使用 Django REST Framework创建序列化器以将 Django 模型转换为 JSON 是多么容易。

在 api 应用中创建一个 serializers.py 文件:

(library) $ touch api/serializers.py

复制代码

然后在文本编辑器中更新为如下所示：

# api/serializers.pyfrom rest_framework import serializers
from books.models import Book

class BookSerializer(serializers.ModelSerializer):    class Meta:        model = Book        fields = ('title', 'subtitle', 'author', 'isbn')

复制代码

首先，我们从 Books 应用程序中导入 Django REST Framework 的序列化器类和 Book 模型。我们将 Django REST Framework 的 ModelSerializer 扩展到 BookSerializer 类中，该类指定我们的数据库模型 Book 和我们希望公开的数据库字段：标题，副标题，作者和 isbn 。

大概就是这样！完成了

cURL

我们想看看我们的 API 端点是什么样子。我们知道它应该在 URL http://127.0.0.1:8000/api/ 返回 JSON 。确保我们的本地 Django 服务器正在运行：

(library) $ python manage.py runserver

复制代码

现在打开一个新的第二个命令行控制台。我们将使用它来访问在现有命令行控制台中运行的 API。

我们可以使用流行的 cURL 程序通过命令行执行 HTTP 请求。我们需要一个基本的 GET 请求，以指定curl和我们要调用的 URL。


$ curl http://127.0.0.1:8000/api/ [  {    "title":"Django for Beginners",    "subtitle":"Build websites with Python and Django",           "author":"William S. Vincent",     "isbn":"978-198317266"  } ]

复制代码

数据全部以 JSON 格式存在，但格式不正确且难以理解。幸运的是，Django REST Framework 给我们带来了另一个惊喜：API 端点的强大可视模式。

Browsable API

在本地服务器仍在第一个命令行控制台中运行的情况下，在 Web 浏览器中的 http://127.0.0.1:8000/api/上导航到我们的 API 端点。

哇，看看！ Django REST Framework 默认情况下提供此可视化。此页面中内置了许多功能，我们将在整本书中进行探讨。现在，我希望您将此页面与原始 JSON 端点进行比较。单击“获取”按钮，然后从下拉菜单中选择“ json”。

这就是来自 API 端点的原始 JSON 的样子。我认为我们可以同意 Django REST Framework 版本更具吸引力。

总结

在本章中，我们讨论了很多内容，因此请不要担心现在是否会感到困惑。首先，我们创建了一个传统的 Django 图书馆网站。然后，我们添加了 Django REST Framework ，并能够以最少的代码添加 API 端点。

发布于: 刚刚阅读数: 5

原文链接:【http://xie.infoq.cn/article/72336aac121f9886d0d2f5eea】。文章转载请联系作者。

宇宙之一粟

关注

宇宙古今无有穷期，一生不过须臾，当思奋争 2020.05.07 加入

🏆InfoQ写作平台-第二季签约作者 🏆 混迹于江湖，江湖却没有我的影子热爱技术，专注于后端全栈，轻易不换岗拒绝内卷，工作于软件工程师，弹性不加班热衷分享，执着于阅读写作，佛系不水文

发布

暂无评论

创作场景

如何利用 Django 进行 API 开发

Django 快速开发

第一个 app

Models

Admin

Views

URLs

网页

Django REST 框架

URLs

Views

Serializers

cURL

Browsable API

总结

宇宙之一粟

评论