Django 官网最新 Tutorial 渣翻 - Part 1

用意:为了提高英文水平, 硬着头皮翻译一下, 而且纵观搜索引擎, 好像还没有基于Django 2.0的官网Tutorial翻译.

版本: Django 2.0.6

手写第一个Django应用, 第一部分

让我们开始通过例子学习, 通过本教程, 我们将帮助您创建一个基本的投票应用程序, 它包含两部分:

• 一个公开的网站，可以让人们查看投票结果以及让他们投票.
• 一个 admin 页面( 后台管理页面 ), 可以让你添加, 更改, 以及删除投票.

我们确信你已经安装了Django( 笔者注: 通过pip install django 安装), 你可以在命令行输入以下命令查看Django是否安装以及他的版本.

(DjangoOfficialTutorial) ➜  DjangoOfficialTutorial python -m django --version

2.0.6

(上述是在笔者的环境下运行的, 因为笔者电脑因项目需求全局的Django版本为1.9, 所以是在虚拟环境下运行的. 关于如何使用虚拟环境参考我的另一篇博客虚拟环境使用方法)

如果已经装了Django, 你将会看到你装的版本, 否则, 会得到一个警告输出: " No module named django" (没有模块叫django)

这个教程是基于Django 2.0, 支持 Python 3.4 以及后续版本, 如果Django 版本不匹配, 可以通过当前页面右下角的版本转换器查看适用于你所使用的版本的Django教程，或者把Django升级到最新的版本。 如果你还在使用旧版本的Python , 查看What Python version can I use with Django?来找到一个合适的Django版本.

可以参考How to install Django来卸载旧版本并安装新版本的Django.

从这里得到帮助;
如果你在使用本教程的时候有困难, 请给django-users发消息, 或者在 Django社区#django on irc.freenode.net寻求帮助.

创建一个项目

如果这是你第一次用 Django, 你需要注意一些初始化设置, 即你需要(通过命令行)自动生成一些代码来建立Django project － Django 网站的一系列设置，包括数据库设置，针对Django的配置以及针对app应用的配置.

在命令行下, cd 到你想要存储 Django 代码的目录, 然后运行如下命令:

django-admin startproject mysite

这将在你当前的目录下创建一个 mysite 目录, 如果没成功, 见 Problems running django-admin.

注意:
你应该避免使用Python或Django的内建变量来给项目起名。这意味着你不能用django（与Django自身冲突）或test（与内建的Python模块冲突）这类项目名.

代码应该存在哪里:
如果你有过老旧的PHP开发背景（没有使用过现代流行框架），你可能会把代码保存到web服务器的文档根目录下（如/var/www）。但在Django里，请不要这样做。将任何的python代码放在web服务器根目录是有很大风险的，因为别人可能通过网站查看到你的源代码。这违背了安全原则。

让我们看看该命令(startproject)都创建了什么:

mysite/
    manage.py
    mysite/
        __init__.py
        settings.py
        urls.py
        wsgi.py

这些文件都是:

• 最外层的 mysite/ 根目录仅仅是你项目的容器, 他的命名不影响 Django, 你可以改成你喜欢的名字.
• manage.py: 一个命令行工具, 可以让你与 Django 项目进行多种方式的交互, 详情请见django-admin and manage.py.
• 内层的 mysite/ 目录是你项目真正的 Python package(包), 你使用它的名字来导入任何东西(如: mysite.urls)
• mysite/__init__.py: 一个空文件, 作用是告诉 Python 这是一个 Python 包, 如果你是 Python 初学者,参考Python 官方文档 more about packages, 来了解更多关于包的知识 .
• mysite/settings.py: 该Django 项目的配置 / 设置, Django settings 会告诉你 settings 是怎样工作的.
• mysite/urls.py: 该Django项目的 UR L声明；你的 Django 站点的“目录”, 详情请见 URL dispatcher.
• mysite/wsgi.py: 项目部署时会用到, 你的项目在与WSGI兼容的 web 服务器部署时的入口, 详情见 How to deploy with WSGI.

开发服务器

让我们验证下你的Django项目是否跑起来了, cd 到包含manage.py 的那层mysite目录, 然后运行下面命令:

python 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.

June 21, 2018 - 15:50:53
Django version 2.0, using settings 'mysite.settings'
Starting development server at [http://127.0.0.1:8000/](http://127.0.0.1:8000/)
Quit the server with CONTROL-C.

提示:
目前暂时先忽略出现的unapplied migrations警告,我们稍后会处理他

You’ve started the Django development server, a lightweight Web server written purely in Python. We’ve included this with Django so you can develop things rapidly, without having to deal with configuring a production server – such as Apache – until you’re ready for production.

Now’s a good time to note: don’t use this server in anything resembling a production environment. It’s intended only for use while developing. (We’re in the business of making Web frameworks, not Web servers.)

Now that the server’s running, visit http://127.0.0.1:8000/ with your Web browser. You’ll see a “Congratulations!” page, with a rocket taking off. It worked!

你已经成功启动了一个Django开发服务器 － 一个纯粹的由Python编写的轻量级Web服务器，我们将他集成在Django里，所以你可以快速的在这里开发，而不需要处理生产上服务器的配置，比如 Apache之类，这些东西可以在项目上线后再去处理．

是时候提示一波了:
千万不要在生产环境上使用这个服务器, 他仅仅被用来在线上开发.( 我们只想做个开发框架, 而不是服务器)

现在Django内置的服务器开始跑了, 你可以访问 http://127.0.0.1:8000/, 你可以看到一个"Congratulations"页面, 还一个小火箭正在起飞.

改变端口:
默认情况下, runserver 命令是跑的本地的 8000 端口, 如果你想改变端口, 加个参数即可, 如下:
python manage.py runserver 8080
如果你想改变服务器的 IP, 可把IP和端口一起作为参数传入, 如: 监听所有可用的公网IP(如果你想运行在Vagrant 虚拟环境或者和互联网上的其他人一起开发时, 这将很有效), 命令如下:
python manage.py runserver 0:8000
0 是 0.0.0.0的简写. 详情见 runserver

runserver 自动重载
开发服务器会根据需要自动重载Python代码, 当修改代码后无需重启服务器即可生效, 除非一些特殊情况, 如添加文件时才需要手动重启服务器.

创建投票 app

现在已经在你的开发环境新建了一个项目，你可以在上面开始工作了.
你创建的每一个django应用，都必须包含一个约定俗成的python包。Django自带了一个自动创建app目录结构的工具，这样你可以专心码代码而不是去创建那些目录.

Project vs. App
项目 和 App 之间有什么区别呢? 一个 App 是一个web程序，它负责特定的工作--比如说一个博客系统，一个存储公共文档的数据库系统或者一个简单的投票应用。而项目是一个网站配置和应用的集合。项目可以包括多个应用，一个应用也可以应用到多个项目中.

你的应用可以放在Python path的任何位置。在本教程，我们将投票应用放在manage.py文件同级目录下，这样就可以作为顶层模块导入，而不是mysite的子模块。进入到manage.py的同级目录下，输入一下命令：

python manage.py startapp polls

该命令会创建一个polls目录, 结构如下:

polls/
    __init__.py
    admin.py
    apps.py
    migrations/
        __init__.py
    models.py
    tests.py
    views.py

这个目录结构就是是投票应用的主体了.

编写第一个视图函数

打开polls目录下的views.py文件, 输入如下代码:

polls/views.py(文件位置)

from django.http import HttpResponse


def index(request):
    return HttpResponse("Hello, world. You're at the polls index.")

这是Django里最简单的视图函数, 为了调用这个视图, 我们需要把他映射到一个 URL 上,也就是说我们需要一个 URL 路由, 为了在 polls 目录下创建一个 URL 路由, 我们先得创建个 py 文件, 我们取名为 urls.py, 所以现在你的 polls app 目录应该是这样:

polls/
    __init__.py
    admin.py
    apps.py
    migrations/
        __init__.py
    models.py
    tests.py
    urls.py
    views.py

在 urls.py 里输入如下代码:

polls/urls.py

from django.urls import path

from . import views

urlpatterns = [
    path('', views.index, name='index'),
]  

下一步是让主路由指向这个 polls.urls 模块, 在mysite/urls.py，导入django.urls.include模块并插入 include() 函数到 urlpatterns 列表中, 故mysite/urls.py如下:

mysite/urls.py 

from django.contrib import admin
from django.urls import include, path

urlpatterns = [
    path('polls/', include('polls.urls')),
    path('admin/', admin.site.urls),
]

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()函数可以代替其他URL路由, 当Django遇到 include() 函数后 , 他会截断 include() 函数前的URL, 并将这段URL发送到被include函数指定的URL路由中, 组合成一个船新URL.

include()的设计思想是方便URL的 即插即用。由于polls独立于自己的URL路由中(polls/urls.py)，所以你可以用“/polls/”, “/fun_polls/”, “/content/polls/”或者其他任意主目录作为他的URL前缀进行替换，它仍可以正常工作。

何时需要用到 include()
当你需要引用其他的URL路由时, 请尽量使用 include, 唯一特例是 admin.site.urls

现在你已经将index视图函数映射到URL路由中了, 我们可以启动服务器来进行验证:

python manage.py runserver

进入http://localhost:8000/polls/ 页面, 你应该能看到“Hello, world. You’re at the polls index.”这几个大字, 这些是你在index函数中定义的.

这个path()函数可以传递四个参数, 其中 route 和 view 是必需的, kwargs 和 name 是可选的, 有必要了解一下这几个参数:

path() 参数之 route :

route 是一个包含URL的字符串, 当处理请求时, Django 会从 urlpatterns 从头开始逐一与被请求的URL进行匹配, 直到找到匹配为止.

匹配时不会匹配 GET 或 POST 参数 以及 域名, 比如, 对于https://www.example.com/myapp/这条请求, URL路由将只尝试匹配myapp/, 对于https://www.example.com/myapp/?page=3请求, URL路由系统也只会匹配myapp/.

path() 参数之 view :

当 Django 找到一个匹配的URL时, 将调用指定的视图函数并将HttpRequest对象作为第一个参数, 以及任何在route中"捕获"到的值作为参数传递进指定的视图函数中, 我们会给个例子(然鹅他这节并没有给 : )

path() 参数之 kwargs :

任意数量的关键字参数可以作为一个字典传递给目标视图。在本教程中，我们将不会用到它.

path() 参数之 name :

为你的URL取个名儿, 能让你在Django的任何地方, 尤其是模板内显式地引用它, 这个强大的功能能让你仅仅通过创建一个文件, 就可以在你的项目里任意的修改 URLpatterns 这个全局变量的值.

如果你已经掌握了基本的 request 和 response 流程, 可以开始下一节了.

下一节: Django 官网最新 Tutorial 渣翻 - Part 2