编写你的第一个 Django 应用，第 2 部分

本教程从 教程1 结束的地方开始。我们将设置数据库，创建第一个模型，并快速介绍 Django 自动生成的后台界面。

从哪里获得帮助：

如果你在阅读本教程的过程中有任何疑问，可以前往 FAQ 的 获取帮助 的版块。

数据库配置

现在，打开 mysite/settings.py 。这是个包含了 Django 项目设置的 Python 模块。

通常，这个配置文件使用 SQLite 作为默认数据库。如果你不熟悉数据库，或者只是想尝试下 Django，这是最简单的选择。Python 内置 SQLite，所以你无需安装额外东西来使用它。当你开始一个真正的项目时，你可能更倾向使用一个更具扩展性的数据库，例如 PostgreSQL，避免中途切换数据库这个令人头疼的问题。

如果你想使用其他数据库，你需要安装合适的 database bindings ，然后改变设置文件中 DATABASES 'default' 项目中的一些键值：

  • ENGINE — 可选值有 'django.db.backends.sqlite3'，'django.db.backends.postgresql'，'django.db.backends.mysql'，或 'django.db.backends.oracle'。其它 可用后端。
  • NAME — 数据库的名称。如果你使用 SQLite，数据库将是你电脑上的一个文件，在这种情况下，NAME 应该是此文件完整的绝对路径，包括文件名。默认值 BASE_DIR / 'db.sqlite3' 将把数据库文件储存在项目的根目录。

如果你不使用 SQLite，则必须添加一些额外设置，比如 USER 、 PASSWORD 、 HOST 等等。想了解更多数据库设置方面的内容，请看文档：DATABASES 。

SQLite 以外的其它数据库

如果你使用了 SQLite 以外的数据库，请确认在使用前已经创建了数据库。你可以通过在你的数据库交互式命令行中使用 “CREATE DATABASE database_name;“ 命令来完成这件事。

另外，还要确保该数据库用户中提供 mysite/settings.py 具有 “create database” 权限。这使得自动创建的 test database 能被以后的教程使用。

如果你使用 SQLite，那么你不需要在使用前做任何事——数据库会在需要的时候自动创建。

编辑 mysite/settings.py 文件前，先设置 TIME_ZONE 为你自己时区。

此外，关注一下文件头部的 INSTALLED_APPS 设置项。这里包括了会在你项目中启用的所有 Django 应用。应用能在多个项目中使用，你也可以打包并且发布应用，让别人使用它们。

通常， INSTALLED_APPS 默认包括了以下 Django 的自带应用：

这些应用被默认启用是为了给常规项目提供方便。

默认开启的某些应用需要至少一个数据表，所以，在使用他们之前需要在数据库中创建一些表。请执行以下命令：

Linux/MacOS     Windows

  1. $ python manage.py migrate
  1. ...\> py manage.py migrate

这个 migrate 命令查看 INSTALLED_APPS 配置，并根据 mysite/settings.py 文件中的数据库配置和随应用提供的数据库迁移文件（我们将在后面介绍这些），创建任何必要的数据库表。你会看到它应用的每一个迁移都有一个消息。如果你有兴趣，运行你的数据库的命令行客户端，输入 \dt （PostgreSQL）， SHOW TABLES; （MariaDB，MySQL）， .tables （SQLite）或 SELECT TABLE_NAME FROM USER_TABLES; （Oracle）来显示 Django 创建的表。

写给极简主义者

就像之前说的，为了方便大多数项目，我们默认激活了一些应用，但并不是每个人都需要它们。如果你不需要某个或某些应用，你可以在运行 migrate 前毫无顾虑地从 INSTALLED_APPS 里注释或者删除掉它们。 migrate 命令只会为在 INSTALLED_APPS 里声明了的应用进行数据库迁移。

创建模型

在 Django 里写一个数据库驱动的 Web 应用的第一步是定义模型 - 也就是数据库结构设计和附加的其它元数据。

设计哲学

一个模型就是单个定义你的数据的信息源。模型中包含了不可缺少的数据区域和你存储数据的行为。Django 遵循 DRY 原则。目的就是定义你的数据模型要在一位置上，而且自动从该位置推导一些事情。

来介绍一下迁移 - 举个例子，不像 Ruby On Rails，Django 的迁移代码是由你的模型文件自动生成的，它本质上是个历史记录，Django 可以用它来进行数据库的滚动更新，通过这种方式使其能够和当前的模型匹配。

在这个投票应用中，需要创建两个模型：问题 Question 和选项 Choice。Question 模型包括问题描述和发布时间。Choice 模型有两个字段，选项描述和当前得票数。每个选项属于一个问题。

这些概念可以通过一个 Python 类来描述。按照下面的例子来编辑 polls/models.py 文件：

polls/models.py

  1. from django.db import models
  4. class Question(models.Model):
  5.     question_text = models.CharField(max_length=200)
  6.     pub_date = models.DateTimeField('date published')
  9. class Choice(models.Model):
  10.     question = models.ForeignKey(Question, on_delete=models.CASCADE)
  11.     choice_text = models.CharField(max_length=200)
  12.     votes = models.IntegerField(default=0)

每个模型被表示为 django.db.models.Model 类的子类。每个模型有许多类变量，它们都表示模型里的一个数据库字段。

每个字段都是 Field 类的实例 - 比如，字符字段被表示为 CharField ，日期时间字段被表示为 DateTimeField 。这将告诉 Django 每个字段要处理的数据类型。

每个 Field 类实例变量的名字（例如 question_text 或 pub_date ）也是字段名，所以最好使用对机器友好的格式。你将会在 Python 代码里使用它们，而数据库会将它们作为列名。

你可以使用可选的选项来为 Field 定义一个人类可读的名字。这个功能在很多 Django 内部组成部分中都被使用了，而且作为文档的一部分。如果某个字段没有提供此名称，Django 将会使用对机器友好的名称，也就是变量名。在上面的例子中，我们只为 Question.pub_date 定义了对人类友好的名字。对于模型内的其它字段，它们的机器友好名也会被作为人类友好名使用。

定义某些 Field 类实例需要参数。例如 CharField 需要一个 max_length 参数。这个参数的用处不止于用来定义数据库结构，也用于验证数据，我们稍后将会看到这方面的内容。

Field 也能够接收多个可选参数；在上面的例子中：我们将 votes 的 default 也就是默认值，设为0。

注意在最后，我们使用 ForeignKey 定义了一个关系。这将告诉 Django，每个 Choice 对象都关联到一个 Question 对象。Django 支持所有常用的数据库关系：多对一、多对多和一对一。

激活模型

上面的一小段用于创建模型的代码给了 Django 很多信息，通过这些信息，Django 可以：

  • 为这个应用创建数据库 schema（生成 CREATE TABLE 语句）。
  • 创建可以与 Question 和 Choice 对象进行交互的 Python 数据库 API。

但是首先得把 polls 应用安装到我们的项目里。

设计哲学

Django 应用是“可插拔”的。你可以在多个项目中使用同一个应用。除此之外，你还可以发布自己的应用，因为它们并不会被绑定到当前安装的 Django 上。

为了在我们的工程中包含这个应用，我们需要在配置类 INSTALLED_APPS 中添加设置。因为 PollsConfig 类写在文件 polls/apps.py 中，所以它的点式路径是 'polls.apps.PollsConfig'。在文件 mysite/settings.py 中 INSTALLED_APPS 子项添加点式路径后，它看起来像这样：

mysite/settings.py

  1. INSTALLED_APPS = [
  2.     'polls.apps.PollsConfig',
  3.     'django.contrib.admin',
  4.     'django.contrib.auth',
  5.     'django.contrib.contenttypes',
  6.     'django.contrib.sessions',
  7.     'django.contrib.messages',
  8.     'django.contrib.staticfiles',
  9. ]

现在你的 Django 项目会包含 polls 应用。接着运行下面的命令：

Linux/MacOS     Windows

  1. $ python manage.py makemigrations polls
  1. ...\> py manage.py makemigrations polls

你将会看到类似于下面这样的输出：

  1. Migrations for 'polls':
  2.   polls/migrations/0001_initial.py
  3.     - Create model Question
  4.     - Create model Choice

通过运行 makemigrations 命令，Django 会检测你对模型文件的修改（在这种情况下，你已经取得了新的），并且把修改的部分储存为一次 迁移。

迁移是 Django 对于模型定义（也就是你的数据库结构）的变化的储存形式 - 它们其实也只是一些你磁盘上的文件。如果你想的话，你可以阅读一下你模型的迁移数据，它被储存在 polls/migrations/0001_initial.py 里。别担心，你不需要每次都阅读迁移文件，但是它们被设计成人类可读的形式，这是为了便于你手动调整 Django 的修改方式。

Django 有一个自动执行数据库迁移并同步管理你的数据库结构的命令 - 这个命令是 migrate，我们马上就会接触它 - 但是首先，让我们看看迁移命令会执行哪些 SQL 语句。sqlmigrate 命令接收一个迁移的名称，然后返回对应的 SQL：

Linux/MacOS     Windows

  1. $ python manage.py sqlmigrate polls 0001
  1. ...\> py manage.py sqlmigrate polls 0001

你将会看到类似下面这样的输出（我把输出重组成了人类可读的格式）：

  1. BEGIN;
  2. --
  3. -- Create model Question
  4. --
  5. CREATE TABLE "polls_question" (
  6.     "id" serial NOT NULL PRIMARY KEY,
  7.     "question_text" varchar(200) NOT NULL,
  8.     "pub_date" timestamp with time zone NOT NULL
  9. );
  10. --
  11. -- Create model Choice
  12. --
  13. CREATE TABLE "polls_choice" (
  14.     "id" serial NOT NULL PRIMARY KEY,
  15.     "choice_text" varchar(200) NOT NULL,
  16.     "votes" integer NOT NULL,
  17.     "question_id" integer NOT NULL
  18. );
  19. ALTER TABLE "polls_choice"
  20.   ADD CONSTRAINT "polls_choice_question_id_c5b4b260_fk_polls_question_id"
  21.     FOREIGN KEY ("question_id")
  22.     REFERENCES "polls_question" ("id")
  23.     DEFERRABLE INITIALLY DEFERRED;
  24. CREATE INDEX "polls_choice_question_id_c5b4b260" ON "polls_choice" ("question_id");
  26. COMMIT;

请注意以下几点：

  • 输出的内容和你使用的数据库有关，上面的输出示例使用的是 PostgreSQL。
  • 数据库的表名是由应用名(polls)和模型名的小写形式( question 和 choice)连接而来。（如果需要，你可以自定义此行为。）
  • 主键(IDs)会被自动创建。(当然，你也可以自定义。)
  • 默认的，Django 会在外键字段名后追加字符串 "_id" 。（同样，这也可以自定义。）
  • 外键关系由 FOREIGN KEY 生成。你不用关心 DEFERRABLE 部分，它只是告诉 PostgreSQL，请在事务全都执行完之后再创建外键关系。
  • 生成的 SQL 语句是为你所用的数据库定制的，所以那些和数据库有关的字段类型，比如 auto_increment (MySQL)、 serial (PostgreSQL)和 integer primary key autoincrement (SQLite)，Django 会帮你自动处理。那些和引号相关的事情 - 例如，是使用单引号还是双引号 - 也一样会被自动处理。
  • 这个 sqlmigrate 命令并没有真正在你的数据库中的执行迁移 - 相反，它只是把命令输出到屏幕上，让你看看 Django 认为需要执行哪些 SQL 语句。这在你想看看 Django 到底准备做什么，或者当你是数据库管理员，需要写脚本来批量处理数据库时会很有用。

如果你感兴趣，你也可以试试运行 python manage.py check ;这个命令帮助你检查项目中的问题，并且在检查过程中不会对数据库进行任何操作。

现在，再次运行 migrate 命令，在数据库里创建新定义的模型的数据表：

Linux/MacOS     Windows

  1. $ python manage.py migrate
  2. Operations to perform:
  3.   Apply all migrations: admin, auth, contenttypes, polls, sessions
  4. Running migrations:
  5.   Rendering model states... DONE
  6.   Applying polls.0001_initial... OK
  1. ...\> py manage.py migrate
  2. Operations to perform:
  3.   Apply all migrations: admin, auth, contenttypes, polls, sessions
  4. Running migrations:
  5.   Rendering model states... DONE
  6.   Applying polls.0001_initial... OK

这个 migrate 命令选中所有还没有执行过的迁移（Django 通过在数据库中创建一个特殊的表 django_migrations 来跟踪执行过哪些迁移）并应用在数据库上 - 也就是将你对模型的更改同步到数据库结构上。

迁移是非常强大的功能，它能让你在开发过程中持续的改变数据库结构而不需要重新删除和创建表 - 它专注于使数据库平滑升级而不会丢失数据。我们会在后面的教程中更加深入的学习这部分内容，现在，你只需要记住，改变模型需要这三步：

数据库迁移被分解成生成和应用两个命令是为了让你能够在代码控制系统上提交迁移数据并使其能在多个应用里使用；这不仅仅会让开发更加简单，也给别的开发者和生产环境中的使用带来方便。

通过阅读文档 Django 后台文档 ，你可以获得关于 manage.py 工具的更多信息。

初试 API

现在让我们进入交互式 Python 命令行，尝试一下 Django 为你创建的各种 API。通过以下命令打开 Python 命令行：

Linux/MacOS     Windows

  1. $ python manage.py shell
  1. ...\> py manage.py shell

我们使用这个命令而不是简单的使用“python”是因为 manage.py 会设置 DJANGO_SETTINGS_MODULE 环境变量，这个变量会让 Django 根据 mysite/settings.py 文件来设置 Python 包的导入路径。

当你成功进入命令行后，来试试 数据库 API 吧：

  1. >>> from polls.models import Choice, Question  # Import the model classes we just wrote.
  3. # No questions are in the system yet.
  4. >>> Question.objects.all()
  5. <QuerySet []>
  7. # Create a new Question.
  8. # Support for time zones is enabled in the default settings file, so
  9. # Django expects a datetime with tzinfo for pub_date. Use timezone.now()
  10. # instead of datetime.datetime.now() and it will do the right thing.
  11. >>> from django.utils import timezone
  12. >>> q = Question(question_text="What's new?", pub_date=timezone.now())
  14. # Save the object into the database. You have to call save() explicitly.
  15. >>> q.save()
  17. # Now it has an ID.
  18. >>> q.id
  19. 1
  21. # Access model field values via Python attributes.
  22. >>> q.question_text
  23. "What's new?"
  24. >>> q.pub_date
  25. datetime.datetime(2012, 2, 26, 13, 0, 0, 775217, tzinfo=<UTC>)
  27. # Change values by changing the attributes, then calling save().
  28. >>> q.question_text = "What's up?"
  29. >>> q.save()
  31. # objects.all() displays all the questions in the database.
  32. >>> Question.objects.all()
  33. <QuerySet [<Question: Question object (1)>]>

等等。<Question: Question object (1)> 对于我们了解这个对象的细节没什么帮助。让我们通过编辑 Question 模型的代码（位于 polls/models.py 中）来修复这个问题。给 Question 和 Choice 增加 __str__() 方法。

polls/models.py

  1. from django.db import models
  3. class Question(models.Model):
  4.     # ...
  5.     def __str__(self):
  6.         return self.question_text
  8. class Choice(models.Model):
  9.     # ...
  10.     def __str__(self):
  11.         return self.choice_text

给模型增加 __str__() 方法是很重要的，这不仅仅能给你在命令行里使用带来方便，Django 自动生成的 admin 里也使用这个方法来表示对象。

让我们再为此模型添加一个自定义方法：

polls/models.py

  1. import datetime
  3. from django.db import models
  4. from django.utils import timezone
  7. class Question(models.Model):
  8.     # ...
  9.     def was_published_recently(self):
  10.         return self.pub_date >= timezone.now() - datetime.timedelta(days=1)

新加入的 import datetime 和 from django.utils import timezone 分别导入了 Python 的标准 datetime 模块和 Django 中和时区相关的 django.utils.timezone 工具模块。如果你不太熟悉 Python 中的时区处理，看看 时区支持文档 吧。

保存文件然后通过 python manage.py shell 命令再次打开 Python 交互式命令行：

  1. >>> from polls.models import Choice, Question
  3. # Make sure our __str__() addition worked.
  4. >>> Question.objects.all()
  5. <QuerySet [<Question: What's up?>]>
  7. # Django provides a rich database lookup API that's entirely driven by
  8. # keyword arguments.
  9. >>> Question.objects.filter(id=1)
  10. <QuerySet [<Question: What's up?>]>
  11. >>> Question.objects.filter(question_text__startswith='What')
  12. <QuerySet [<Question: What's up?>]>
  14. # Get the question that was published this year.
  15. >>> from django.utils import timezone
  16. >>> current_year = timezone.now().year
  17. >>> Question.objects.get(pub_date__year=current_year)
  18. <Question: What's up?>
  20. # Request an ID that doesn't exist, this will raise an exception.
  21. >>> Question.objects.get(id=2)
  22. Traceback (most recent call last):
  23.     ...
  24. DoesNotExist: Question matching query does not exist.
  26. # Lookup by a primary key is the most common case, so Django provides a
  27. # shortcut for primary-key exact lookups.
  28. # The following is identical to Question.objects.get(id=1).
  29. >>> Question.objects.get(pk=1)
  30. <Question: What's up?>
  32. # Make sure our custom method worked.
  33. >>> q = Question.objects.get(pk=1)
  34. >>> q.was_published_recently()
  35. True
  37. # Give the Question a couple of Choices. The create call constructs a new
  38. # Choice object, does the INSERT statement, adds the choice to the set
  39. # of available choices and returns the new Choice object. Django creates
  40. # a set to hold the "other side" of a ForeignKey relation
  41. # (e.g. a question's choice) which can be accessed via the API.
  42. >>> q = Question.objects.get(pk=1)
  44. # Display any choices from the related object set -- none so far.
  45. >>> q.choice_set.all()
  46. <QuerySet []>
  48. # Create three choices.
  49. >>> q.choice_set.create(choice_text='Not much', votes=0)
  50. <Choice: Not much>
  51. >>> q.choice_set.create(choice_text='The sky', votes=0)
  52. <Choice: The sky>
  53. >>> c = q.choice_set.create(choice_text='Just hacking again', votes=0)
  55. # Choice objects have API access to their related Question objects.
  56. >>> c.question
  57. <Question: What's up?>
  59. # And vice versa: Question objects get access to Choice objects.
  60. >>> q.choice_set.all()
  61. <QuerySet [<Choice: Not much>, <Choice: The sky>, <Choice: Just hacking again>]>
  62. >>> q.choice_set.count()
  63. 3
  65. # The API automatically follows relationships as far as you need.
  66. # Use double underscores to separate relationships.
  67. # This works as many levels deep as you want; there's no limit.
  68. # Find all Choices for any question whose pub_date is in this year
  69. # (reusing the 'current_year' variable we created above).
  70. >>> Choice.objects.filter(question__pub_date__year=current_year)
  71. <QuerySet [<Choice: Not much>, <Choice: The sky>, <Choice: Just hacking again>]>
  73. # Let's delete one of the choices. Use delete() for that.
  74. >>> c = q.choice_set.filter(choice_text__startswith='Just hacking')
  75. >>> c.delete()

阅读 访问关系对象 文档可以获取关于数据库关系的更多内容。想知道关于双下划线的更多用法，参见 查找字段 文档。数据库 API 的所有细节可以在 数据库 API 参考 文档中找到。

介绍 Django 管理页面

设计哲学

为你的员工或客户生成一个用户添加，修改和删除内容的后台是一项缺乏创造性和乏味的工作。因此，Django 全自动地根据模型创建后台界面。

Django 产生于一个公众页面和内容发布者页面完全分离的新闻类站点的开发过程中。站点管理人员使用管理系统来添加新闻、事件和体育时讯等，这些添加的内容被显示在公众页面上。Django 通过为站点管理人员创建统一的内容编辑界面解决了这个问题。

管理界面不是为了网站的访问者，而是为管理者准备的。

创建一个管理员账号

首先，我们得创建一个能登录管理页面的用户。请运行下面的命令：

Linux/MacOS     Windows

  1. $ python manage.py createsuperuser
  1. ...\> py manage.py createsuperuser

键入你想要使用的用户名，然后按下回车键：

  1. Username: admin

然后提示你输入想要使用的邮件地址：

  1. Email address: admin@example.com

最后一步是输入密码。你会被要求输入两次密码，第二次的目的是为了确认第一次输入的确实是你想要的密码。

  1. Password: **********
  2. Password (again): *********
  3. Superuser created successfully.

启动开发服务器

Django 的管理界面默认就是启用的。让我们启动开发服务器，看看它到底是什么样的。

如果开发服务器未启动，用以下命令启动它：

Linux/MacOS     Windows

  1. $ python manage.py runserver
  1. ...\> py manage.py runserver

现在，打开浏览器，转到你本地域名的 “/admin/” 目录， — 比如 http://127.0.0.1:8000/admin/ 。你应该会看见管理员登录界面：

Django 管理员登录界面

因为 翻译 功能默认是开启的，如果你设置了 LANGUAGE_CODE，登录界面将显示你设置的语言（如果 Django 有相应的翻译）。

进入管理站点页面

现在，试着使用你在上一步中创建的超级用户来登录。然后你将会看到 Django 管理页面的索引页：

Django admin index page

你将会看到几种可编辑的内容：组和用户。它们是由 django.contrib.auth 提供的，这是 Django 开发的认证框架。

向管理页面中加入投票应用

但是我们的投票应用在哪呢？它没在索引页面里显示。

只需要再做一件事：我们得告诉管理，问题 Question 对象需要一个后台接口。打开 polls/admin.py 文件，把它编辑成下面这样：

polls/admin.py

  1. from django.contrib import admin
  3. from .models import Question
  5. admin.site.register(Question)

体验便捷的管理功能

现在我们向管理页面注册了问题 Question 类。Django 知道它应该被显示在索引页里：

Django admin index page, now with polls displayed

点击 “Questions” 。现在看到是问题 “Questions” 对象的列表 “change list” 。这个界面会显示所有数据库里的问题 Question 对象，你可以选择一个来修改。这里现在有我们在上一部分中创建的 “What’s up?” 问题。

Polls change list page

点击 “What’s up?” 来编辑这个问题（Question）对象：

Editing form for question object

注意事项：

  • 这个表单是从问题 Question 模型中自动生成的
  • 不同的字段类型（日期时间字段 DateTimeField 、字符字段 CharField）会生成对应的 HTML 输入控件。每个类型的字段都知道它们该如何在管理页面里显示自己。
  • 每个日期时间字段 DateTimeField 都有 JavaScript 写的快捷按钮。日期有转到今天（Today）的快捷按钮和一个弹出式日历界面。时间有设为现在（Now）的快捷按钮和一个列出常用时间的方便的弹出式列表。

页面的底部提供了几个选项：

  • 保存（Save） - 保存改变，然后返回对象列表。
  • 保存并继续编辑（Save and continue editing） - 保存改变，然后重新载入当前对象的修改界面。
  • 保存并新增（Save and add another） - 保存改变，然后添加一个新的空对象并载入修改界面。
  • 删除（Delete） - 显示一个确认删除页面。

如果显示的 “发布日期(Date Published)” 和你在 教程 1 里创建它们的时间不一致，这意味着你可能没有正确的设置 TIME_ZONE 。改变设置，然后重新载入页面看看是否显示了正确的值。

通过点击 “今天(Today)” 和 “现在(Now)” 按钮改变 “发布日期(Date Published)”。然后点击 “保存并继续编辑(Save and add another)”按钮。然后点击右上角的 “历史(History)”按钮。你会看到一个列出了所有通过 Django 管理页面对当前对象进行的改变的页面，其中列出了时间戳和进行修改操作的用户名：

History page for question object

当你熟悉了数据库 API 之后，你就可以开始阅读 教程第 3 部分 ，下一部分我们将会学习如何为投票应用添加更多视图。