编写你的第一个 Django 应用,第 1 部分¶
让我们通过示例来学习。
通过这个教程,我们将带着你创建一个基本的投票应用程序。
它将由两部分组成:
一个让人们查看和投票的公共站点。
一个让你能添加、修改和删除投票的管理站点。
我们假定你已经阅读了 安装 Django。你能知道 Django 已被安装,且安装的是哪个版本,通过在命令提示行输入命令(由 $ 前缀)。
$ python -m django --version
...\> py -m django --version
如果这行命令输出了一个版本号,证明你已经安装了此版本的 Django;如果你得到的是一个“No module named django”的错误提示,则表明你还未安装。
本教程适用于 Django 5.1,支持 Python 3.10 及更高版本。如果 Django 版本不匹配,您可以使用本页面右下角的版本切换器查看适用于您 Django 版本的教程,或者将 Django 更新到最新版本。如果您使用的是较旧版本的 Python,请查看 我应该使用哪个版本的 Python 来配合 Django? 以找到与之兼容的 Django 版本。
你可以查看文档 如何安装 Django 来获得关于移除旧版本,安装新版本的流程和建议。
从哪里获得帮助:
如果你在阅读本教程的过程中有任何疑问,可以前往 FAQ 的 获取帮助 的版块。
创建项目¶
如果这是你第一次使用 Django 的话,你需要一些初始化设置。也就是说,你需要用一些自动生成的代码配置一个 Django project —— 即一个 Django 项目实例需要的设置项集合,包括数据库配置、Django 配置和应用程序配置。
From the command line, cd
into a directory where you'd like to store your
code and create a new directory named djangotutorial
. (This directory name
doesn't matter to Django; you can rename it to anything you like.)
$ mkdir djangotutorial
...\> mkdir djangotutorial
Then, run the following command to bootstrap a new Django project:
$ django-admin startproject mysite djangotutorial
...\> django-admin startproject mysite djangotutorial
This will create a project called mysite
inside the djangotutorial
directory. If it didn't work, see 运行 django-admin 时遇到的问题.
Note
你得避免使用 Python 或 Django 的内部保留字来命名你的项目。具体地说,你得避免使用像 django
(会和 Django 自己产生冲突)或 test
(会和 Python 的内置组件产生冲突)这样的名字。
让我们看看 startproject
创建了些什么:
djangotutorial/
manage.py
mysite/
__init__.py
settings.py
urls.py
asgi.py
wsgi.py
这些目录和文件的用处是:
manage.py
: 一个让你用各种方式管理 Django 项目的命令行工具。你可以阅读 django-admin 和 manage.py 获取所有manage.py
的细节。mysite/
: A directory that is the actual Python package for your project. Its name is the Python package name you'll need to use to import anything inside it (e.g.mysite.urls
).mysite/__init__.py
:一个空文件,告诉 Python 这个目录应该被认为是一个 Python 包。如果你是 Python 初学者,阅读官方文档中的 更多关于包的知识。mysite/settings.py
:Django 项目的配置文件。如果你想知道这个文件是如何工作的,请查看 Django 配置 了解细节。mysite/urls.py
:Django 项目的 URL 声明,就像你网站的“目录”。阅读 URL调度器 文档来获取更多关于 URL 的内容。mysite/asgi.py
:作为你的项目的运行在 ASGI 兼容的 Web 服务器上的入口。阅读 如何使用 ASGI 来部署 了解更多细节。mysite/wsgi.py
:作为你的项目的运行在 WSGI 兼容的Web服务器上的入口。阅读 如何使用 WSGI 进行部署 了解更多细节。
用于开发的简易服务器¶
Let's verify your Django project works. Change into the djangotutorial
directory, if you haven't already, and run the following commands:
$ python manage.py runserver
...\> py manage.py runserver
你应该会看到如下输出:
Performing system checks... System check identified no issues (0 silenced). You have unapplied migrations; your app may not work properly until they are applied. Run 'python manage.py migrate' to apply them. 十一月 19, 2024 - 15:50:53 Django version 5.1, using settings 'mysite.settings' Starting development server at http://127.0.0.1:8000/ Quit the server with CONTROL-C.
Note
忽略有关未应用最新数据库迁移的警告,稍后我们处理数据库。
服务器现在正在运行,通过浏览器访问 http://127.0.0.1:8000/ 。你将看到一个“祝贺”页面,有一只火箭正在发射。你成功了!
你已经启动了 Django 开发服务器,这是一个用纯 Python 编写的轻量级网络服务器。我们在 Django 中包含了这个服务器,所以你可以快速开发,而不需要处理配置生产服务器的问题 -- 比如 Apache -- 直到你准备好用于生产。
现在是个提醒你的好时机:千万不要 将这个服务器用于和生产环境相关的任何地方。这个服务器只是为了开发而设计的。(我们在网络框架方面是专家,在网络服务器方面并不是。)
(若要在一个不同的端口上提供网站服务,请参阅 runserver
参考。)
会自动重新加载的服务器 runserver
用于开发的服务器在需要的情况下会对每一次的访问请求重新载入一遍 Python 代码。所以你不需要为了让修改的代码生效而频繁的重新启动服务器。然而,一些动作,比如添加新文件,将不会触发自动重新加载,这时你得自己手动重启服务器。
创建投票应用¶
现在你的开发环境——这个“项目” ——已经配置好了,你可以开始干活了。
在 Django 中,每一个应用都是一个 Python 包,并且遵循着相同的约定。Django 自带一个工具,可以帮你生成应用的基础目录结构,这样你就能专心写代码,而不是创建目录了。
项目 VS 应用
项目和应用有什么区别?应用是一个专门做某件事的网络应用程序——比如博客系统,或者公共记录的数据库,或者小型的投票程序。项目则是一个网站使用的配置和应用的集合。项目可以包含很多个应用。应用可以被很多个项目使用。
Your apps can live anywhere in your Python path. In
this tutorial, we'll create our poll app inside the djangotutorial
folder.
请确定你现在处于 manage.py
所在的目录下,然后运行这行命令来创建一个应用:
$ python manage.py startapp polls
...\> py manage.py startapp polls
这将创建一个名为 polls
的目录,其布局如下:
polls/
__init__.py
admin.py
apps.py
migrations/
__init__.py
models.py
tests.py
views.py
这个目录结构包括了投票应用的全部内容。
编写第一个视图¶
让我们开始编写第一个视图吧。打开 polls/views.py
,把下面这些 Python 代码输入进去:
from django.http import HttpResponse
def index(request):
return HttpResponse("Hello, world. You're at the polls index.")
这是在 Django 中最基本的视图。要在浏览器中访问它,我们需要将其映射到一个 URL——为此我们需要定义一个 URL 配置,简称为 "URLconf"。这些 URL 配置是在每个 Django 应用程序内部定义的,它们是名为 urls.py
的 Python 文件。
要为 polls
应用定义一个 URLconf,创建一个名为 polls/urls.py
的文件,并包含以下内容:
from django.urls import path
from . import views
urlpatterns = [
path("", views.index, name="index"),
]
你的应用目录现在应该如下所示:
polls/
__init__.py
admin.py
apps.py
migrations/
__init__.py
models.py
tests.py
urls.py
views.py
下一步是在 mysite
项目中配置全局 URLconf,以包含在 polls.urls
中定义的 URLconf。为此,在 mysite/urls.py
中添加对 django.urls.include
的导入,并在 urlpatterns
列表中插入一个 include()
,如下所示:
from django.contrib import admin
from django.urls import include, path
urlpatterns = [
path("polls/", include("polls.urls")),
path("admin/", admin.site.urls),
]
The path()
function expects at least two arguments:
route
and view
.
The include()
function allows referencing other URLconfs.
Whenever Django encounters include()
, it chops off whatever
part of the URL matched up to that point and sends the remaining string to the
included URLconf for further processing.
我们设计 include()
的理念是使其可以即插即用。因为投票应用有它自己的 URLconf( polls/urls.py
),他们能够被放在 "/polls/" , "/fun_polls/" ,"/content/polls/",或者其他任何路径下,这个应用都能够正常工作。
何时使用 include()
You should always use include()
when you include other URL patterns.
The only exception is admin.site.urls
, which is a pre-built URLconf
provided by Django for the default admin site.
你现在把 index
视图添加进了 URLconf。通过以下命令验证是否正常工作:
$ python manage.py runserver
...\> py manage.py runserver
用你的浏览器访问 http://localhost:8000/polls/,你应该能够看见 "Hello, world. You're at the polls index." ,这是你在 index
视图中定义的。
没有找到页面?
如果你在这里得到了一个错误页面,检查一下你是不是正访问着http://localhost:8000/polls/ 而不应该是 http://localhost:8000/。
当你了解了基本的请求和响应流程后,请阅读 教程的第 2 部分 开始使用数据库.