已經同步到gitbook，想閱讀的請轉到gitbook: Django 1.10 中文文檔

Let’s learn by example.

讓我們通過例子來學習

Throughout this tutorial, we’ll walk you through the creation of a basic poll application.

通過本教程，我們將帶著你創建一個基本的投票應用

It’ll consist of two parts:

A public site that lets people view polls and vote in them.

An admin site that lets you add, change, and delete polls.

它將包含兩個部分：

一個公開的網站，可以讓人們查看投票結果以及讓他們投票

一個后臺管理系統，可以添加，更新，和刪除投票

We’ll assume you have Django installed already. You can tell Django is installed and which version by running the following command:

假設你已經安裝好了Django，你可以輸入以下命令來驗證和查看你所安裝的版本：

python -m django --version

If Django is installed, you should see the version of your installation. If it isn’t, you’ll get an error telling “No module named django”.

如果已經安裝Django，你將看到你安裝的版本好。如果沒有，將會報一個“No module named django”的錯誤

This tutorial is written for Django 1.10 and Python 3.4 or later. If the Django version doesn’t match, you can refer to the tutorial for your version of Django by using the version switcher at the bottom right corner of this page, or update Django to the newest version. If you are still using Python 2.7, you will need to adjust the code samples slightly, as described in comments.

本教程基于Django 1.10 以及 Python 3.4+版本編寫。如果你的Django版本不符， 如果Django版本不符，可以通過當前頁面右下角的版本轉換器查看適用于你所使用的版本的Django教程，或者把Django升級到最新的版本。 如果你還在使用2.7版本的Python，你將需要按照注釋中的內容稍微調整一下示例代碼。

See How to install Django for advice on how to remove older versions of Django and install a newer one.

關于如何卸載舊版本并安裝新版本的Django，請參考How to install Django

• Where to get help:

If you’re having trouble going through this tutorial, please post a message to django-users or drop by #django on irc.freenode.net to chat with other Django users who might be able to help.

• 如何獲得幫助：

在本教程中，你有任何問題，都可以發消息給django 開發人員 或者訪問 #django on irc.freenode.net網站，與其他Django開發者交流尋求幫助。

Creating a project

創建項目

If this is your first time using Django, you’ll have to take care of some initial setup. Namely, you’ll need to auto-generate some code that establishes a Django project – a collection of settings for an instance of Django, including database configuration, Django-specific options and application-specific settings.

From the command line, cd

into a directory where you’d like to store your code, then run the following command:

如果這是你第一次使用Django，你需要注意一下初始化設置。換句話說，你需要使用命令行來自動創建一個Django項目 --一個Django框架開發的網站，包括數據庫設置，針對Django的配置以及針對app應用的配置。

在命令行中，cd到你想要報錯你項目代碼的目錄，并執行一下命令：

django-admin startproject mysite

This will create a mysite

directory in your current directory. If it didn’t work, see Problems running django-admin.

這將會在你的當前目錄下創建一個mysite目錄。如果沒有，請查看Problems running django-admin.

• NOTE

You’ll need to avoid naming projects after built-in Python or Django components. In particular, this means you should avoid using names like django (which will conflict with Django itself) or test (which conflicts with a built-in Python package).

• 注意

你應該避免使用Python或Django的內建變量來給項目起名。特別地，這意味著你不能用django（與Django自身沖突）或test（與內建的Python模塊沖突）這類項目名

• Where should this code live?

If your background is in plain old PHP (with no use of modern frameworks), you’re probably used to putting code under the Web server’s document root (in a place such as /var/www). With Django, you don’t do that. It’s not a good idea to put any of this Python code within your Web server’s document root, because it risks the possibility that people may be able to view your code over the Web. That’s not good for security.

Put your code in some directory outside of the document root, such as /home/mycode.

• 代碼應該存在哪里

如果你有過普通老久的PHP開發背景（沒有使用過現代流行框架），你可能會把代碼保存到web服務器的文檔根目錄下（如/var/www）。但在Django里，請不要這樣做。將任何的python代碼放在web服務器根目錄是有很大風險的，因為別人可能通過網站查看到你的源代碼。這違背了安全原則。

將你的代碼放置在Web服務器根目錄以外的地方，例如/home/mycode。

Let’s look at what startproject created:

讓我們看一下startproject命令創建了哪些文件和目錄：

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

These files are:

• The outer mysite/ root directory is just a container for your project. Its name doesn’t matter to Django; you can rename it to anything you like.

• manage.py: A command-line utility that lets you interact with this Django project in various ways. You can read all the details about manage.py in django-admin and manage.py.

• The inner mysite/ directory 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: An empty file that tells Python that this directory should be considered a Python package. If you’re a Python beginner, read more about packages in the official Python docs.

• mysite/settings.py: Settings/configuration for this Django project. Django settings will tell you all about how settings work.

• mysite/urls.py: The URL declarations for this Django project; a “table of contents” of your Django-powered site. You can read more about URLs in URL dispatcher.

• mysite/wsgi.py: An entry-point for WSGI-compatible web servers to serve your project. See How to deploy with WSGIfor more details.

這些文件是：

• 外層的mysite/根目錄僅僅是一個項目容器。它的命名對Django無關，你可以把它重命名為任何你喜歡的名字。

• manage.py：一個命令行工具，可以使你用多種方式對Django項目進行交互。你可以在django-admin和manage.py中讀到關于manage.py的所有細節。

• 內層的mysite/目錄是你的項目的真正的Python包。它是你導入任何東西時將需要使用的Python包的名字（例如 mysite.urls。

• mysite/init.py：一個空文件，它告訴Python這個目錄應該被看做一個Python包。如果你是一個Python初學者，關于包的更多內容請閱讀Python的官方文檔）。

• mysite/settings.py：該Django 項目的設置/配置。Django 設置 將告訴你這些設置如何工作。

• mysite/urls.py：該Django項目的URL聲明；你的Django站點的“目錄”。

你可以在URL 轉發器 中閱讀到關于URL的更多內容。

• mysite/wsgi.py：用于你的項目的與WSGI兼容的Web服務器入口。

更多細節請參見如何利用WSGI進行部署。

**
The development server**
開發服務器
Let’s verify your Django project works. Change into the outer mysite directory, if you haven’t already, and run the following commands:
讓我們來驗證一下你的django項目是否正常。進入外層的mysite目錄，如果你還

python manage.py runserver

You’ll see the following output on the command line:

你將在命令行看到如下輸出：

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.
March 01, 2017 - 15:50:53
Django version 1.10, 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.

• Note

Ignore the warning about unapplied database migrations for now; we’ll deal with the database shortly.

• 注意

暫時忽略關于未應用的數據庫遷移，我們很快會講到database

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.

你已經啟動了一個Django開發服務器，一個輕量級的純python寫的web服務器。我們集成在了Django內，這樣你就可以快速的開發產品，直到你準備好上線前都無需配置生產服務器--比如Apache

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 “Welcome to Django” page, in pleasant, light-blue pastel. It worked!

友情提示：千萬不要在類生產服務器使用，它僅能在開發中使用。（我們重點是開發web框架，而不是web服務器）

服務器運行后，瀏覽器訪問http://127.0.0.1:8000/ ，你可以看到令人賞星悅目的淡藍色的Django歡迎頁面，它工作了。

• Changing the port

By default, the runserver command starts the development server on the internal IP at port 8000.

If you want to change the server’s port, pass it as a command-line argument. For instance, this command starts the server on port 8080:

• 更改端口

默認默認情況下，runserver 命令啟動的開發服務器運行在內部IP的8000端口。如果你想更改端口，需要加個參數，比如說，下面這個命令開啟了8080端口

python manage.py runserver 8080

If you want to change the server’s IP, pass it along with the port. So to listen on all public IPs (useful if you want to show off your work on other computers on your network), use:

如果你想更改綁定的服務IP，可把IP和端口一起作為參數。因此若要監聽所有外網IP（如果你想在局域網內與其他人開發同一站點的話，該功能非常有用），輸入命令：

python manage.py runserver 0.0.0.0:8000

Full docs for the development server can be found in the runserver reference.

開發服務器的所有文檔可以在runserver的參考手冊中找到。

• Automatic reloading of runserver

The development server automatically reloads Python code for each request as needed. You don’t need to restart the server for code changes to take effect. However, some actions like adding files don’t trigger a restart, so you’ll have to restart the server in these cases.

• runserver的自動重載

開發服務器會根據需要自動重新載入Python代碼。 你不必為了使更改的代碼生效而重啟服務器。 然而，一些行為比如添加文件，不會觸發服務器的重啟，所以在這種情況下你需要手動重啟服務器。

創建投票應用

Now that your environment – a “project” – is set up, you’re set to start doing work.

現在你已經在你的開發環境新建了一個項目，你可以在上面開始工作了

Each application you write in Django consists of a Python package that follows a certain convention. Django comes with a utility that automatically generates the basic directory structure of an app, so you can focus on writing code rather than creating directories.

你創建的每一個django應用，都必須包含一個約定俗成的python包。Django自帶了一個自動創建app目錄結構的工具，這樣你可以專心碼代碼而不是去創建那些目錄

• Projects vs. apps

What’s the difference between a project and an app? An app is a Web application that does something – e.g., a Weblog system, a database of public records or a simple poll app. A project is a collection of configuration and apps for a particular website. A project can contain multiple apps. An app can be in multiple projects.

項目和應用之間有什么區別呢？一個應用是一個web程序，它負責特定的工作--比如說一個博客系統，一個存儲公共文檔的數據庫系統或者一個簡單的投票應用。而項目是一個網站配置和應用的集合。項目可以包括多個應用，一個應用也可以從屬于多個項目

Your apps can live anywhere on your Python path. In this tutorial, we’ll create our poll app right next to your manage.py file so that it can be imported as its own top-level module, rather than a submodule of mysite.
To create your app, make sure you’re in the same directory as manage.py and type this command:

你的應用可以放在Python path的任何位置。在本教程，我們將投票應用放在manage.py文件同級目錄下，這樣就可以作為頂層模塊導入，而不是mysite的子模塊。進入到manage.py的同級目錄下，輸入一下命令：

python manage.py startapp polls

That’ll create a directory polls, which is laid out like this:

命令將會創建一個polls目錄，結構如下：

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

This directory structure will house the poll application.

這個目錄就結構是投票應用的框架了

Write your first view

Let’s write the first view. Open the file polls/views.py and put the following Python code in it:

讓我們開始寫第一個view函數，打開polls/views.py,輸入以下代碼：

from django.http import HttpResponse

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

This is the simplest view possible in Django. To call the view, we need to map it to a URL - and for this we need a URLconf.

To create a URLconf in the polls directory, create a file called urls.py. Your app directory should now look like:

這是Django里最簡單的view函數。為了調用該函數，我們需要編輯URLconf.在polls目錄創建URLconf，也就是創建一個名為urls.py文件。這時你的目錄結構看起來像這樣：

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

In the polls/urls.py file include the following code:

from django.conf.urls import url

from . import views

urlpatterns = [
url(r'^$', views.index, name='index'),
]

The next step is to point the root URLconf at the polls.urls module. In mysite/urls.py, add an import for django.conf.urls.include and insert an include() in the urlpatterns list, so you have:

下一步就是讓項目主urls文件指向polls.urls這個模塊。在mysite/urls.py，導入django.conf.urls.include模塊，并且添加到urlpatterns列表，所以mysite/urls.py如下：

# mysite/urls.py
from django.conf.urls import include, url
from django.contrib import admin

urlpatterns = [
url(r'^polls/', include('polls.urls')),
url(r'^admin/', admin.site.urls),
]

The include() function allows referencing other URLconfs. Note that the regular expressions for the include() function doesn’t have a $ (end-of-string match character) but rather a trailing slash. 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()函數可以關聯其他的URLconfs。注意include()函數前的正則表達式沒有$符(末尾匹配)，取而代之的是斜杠。Django在遇到include()函數后，會截斷正則表達式匹配到的字符串，然后將剩下的url傳遞到所incloude的URLconf進一步處理。

The idea behind include() is to make it easy to plug-and-play URLs. Since polls are in their own URLconf (polls/urls.py), they can be placed under “/polls/”, or under “/fun_polls/”, or under “/content/polls/”, or any other path root, and the app will still work.

include()的設計思想是方便即插即用。由于polls在它自己的URLconf(polls/urls.py)，你可以用“/polls/”, “/fun_polls/”, “/content/polls/”或者其他任意主目錄隨意替換，它仍可以正常工作。

When to use include()

You should always use include() when you include other URL patterns.admin.site.urls is the only exception to this.

當你需要引入其他url時，盡量使用include()，唯一的特例是patterns.admin.site.urls

Doesn’t match what you see?

If you’re seeing include(admin.site.urls) instead of just admin.site.urls, you’re probably using a version of Django that doesn’t match this tutorial version. You’ll want to either switch to the older tutorial or the newer Django version.

如果你看到的是include(admin.site.urls)，而不是admin.site.urls，那你的Django版本可能與本教程不符。你應該切換到舊的教程教程或

You have now wired an index view into the URLconf. Lets verify it’s working, run the following command:

你已經將view函數index()映射到URLconf，讓我們來驗證它能否正常工作，運行如下命令：

python manage.py runserver

Go to http://localhost:8000/polls/ in your browser, and you should see the text “Hello, world. You’re at the polls index.”, which you defined in the index
view.

The url() function is passed four arguments, two required: regex and view, and two optional: kwargs, and name. At this point, it’s worth reviewing what these arguments are for.

在你的瀏覽器訪問http://localhost:8000/polls/，你將看到“Hello, world. You’re at the polls index.”，這就是我們剛剛在index view函數定義的。

url()函數需要四個參數，兩個必需參數：regex和view，兩個可選參數：Kwargs和name。我們有必要詳細了解下這些參數。

**
url() argument: regex**

The term “regex” is a commonly used short form meaning “regular expression”, which is a syntax for matching patterns in strings, or in this case, url patterns. Django starts at the first regular expression and makes its way down the list, comparing the requested URL against each regular expression until it finds one that matches.

“正則”是正則表達式的通用縮寫，它是一種匹配字符串或url地址的語法。在這里就是指url patterns。Django拿著用戶請求的url地址，在urls.py文件中對urlpatterns列表中的每一項條目從頭開始進行逐一對比，直到匹配為止。

Note that these regular expressions do not search GET and POST parameters, or the domain name. For example, in a request to https://www.example.com/myapp/, the URLconf will look for myapp/. In a request to https://www.example.com/myapp/?page=3, the URLconf will also look for myapp/.

需要注意的是，regex不會去匹配GET或POST參數或域名，例如對于https://www.example.com/myapp/， regex只嘗試匹配myapp/。對于https://www.example.com/myapp/?page=3, regex也只嘗試匹配myapp/。

If you need help with regular expressions, see Wikipedia’s entry and the documentation of the re module. Also, the O’Reilly book “Mastering Regular Expressions” by Jeffrey Friedl is fantastic. In practice, however, you don’t need to be an expert on regular expressions, as you really only need to know how to capture simple patterns. In fact, complex regexes can have poor lookup performance, so you probably shouldn’t rely on the full power of regexes.

如果你想深入研究正則表達式，可以參考Wikipedia’s entry 以及 re 模塊的文檔，由作者Jeffrey Friedl出版的O’Reilly “Mastering Regular Expressions”書籍也非常不錯。但是實踐中，你不需要多高深的正則表達式知識，因為你只需要知道如何匹配簡單的規則。事實上，復雜的正則表達式查詢性能會比較差，所以盡可能不用正則的復雜功能

Finally, a performance note: these regular expressions are compiled the first time the URLconf module is loaded. They’re super fast (as long as the lookups aren’t too complex as noted above).

最后，關于性能問題：正則表達式會進行預先編譯當URLconf模塊加載的時候，因此它的匹配搜索速度非常快，你通常感覺不到。

url() argument: view

When Django finds a regular expression match, Django calls the specified view function, with an HttpRequest object as the first argument and any “captured” values from the regular expression as other arguments. If the regex uses simple captures, values are passed as positional arguments; if it uses named captures, values are passed as keyword arguments. We’ll give an example of this in a bit.

當正則表達式匹配到某個條目時，自動將封裝的HttpRequest對象作為第一個參數，正則表達式“捕獲”到的值作為其他參數，傳遞給該條目指定的視圖。如果是簡單捕獲，那么捕獲值將作為一個位置參數進行傳遞，如果是命名捕獲，那么將作為關鍵字參數進行傳遞。我們會舉例說明這點

url() argument: kwargs

Arbitrary keyword arguments can be passed in a dictionary to the target view. We aren’t going to use this feature of Django in the tutorial.

任意數量的關鍵字參數可以作為一個字典傳遞給目標視圖。在本教程中，我們不會用到它

url() argument: name

Naming your URL lets you refer to it unambiguously from elsewhere in Django, especially from within templates. This powerful feature allows you to make global changes to the URL patterns of your project while only touching a single file.
When you’re comfortable with the basic request and response flow, read part 2 of this tutorialto start working with the database.

對你的URL進行命名，可以讓你能夠在Django的任意處，尤其是模板內顯式地引用它。這個強大的功能，僅僅通過創建一個文件就可以讓你在項目里任意修改URL patterns這個全局變量的值。如果你已經掌握了基本的request和response的過程，那就閱讀教程第二部分 數據庫開始學習數據庫相關