概觀¶

要為應用程式設計 URL，您需要建立一個非正式地稱為 URLconf（URL 設定）的 Python 模組。此模組是純 Python 程式碼，是 URL 路徑表達式到 Python 函數（您的視圖）之間的映射。

此映射可以根據需要而長或短。它可以參考其他映射。而且，由於它是純 Python 程式碼，因此可以動態建構。

Django 還提供了一種根據活動語言翻譯 URL 的方法。有關更多資訊，請參閱國際化文件。

Django 如何處理請求¶

當使用者從您的 Django 驅動網站請求頁面時，系統會遵循此演算法來決定要執行哪個 Python 程式碼

1. Django 會決定要使用的根 URLconf 模組。通常，這是ROOT_URLCONF 設定的值，但是如果傳入的 HttpRequest 物件具有 urlconf 屬性（由中介軟體設定），則其值將取代ROOT_URLCONF 設定。

2. Django 會載入該 Python 模組，並尋找變數 urlpatterns。這應該是 序列 的 django.urls.path() 和/或 django.urls.re_path() 實例。

3. Django 會依序執行每個 URL 模式，並在第一個與請求的 URL 相符的模式處停止，並與path_info 進行比對。

4. 一旦其中一個 URL 模式匹配，Django 會匯入並呼叫指定的視圖，該視圖是一個 Python 函數（或基於類的視圖）。視圖會傳遞以下引數

   • HttpRequest 的實例。

   • 如果匹配的 URL 模式不包含具名群組，則正規表示式中的匹配項將作為位置引數提供。

   • 關鍵字引數由路徑表達式中匹配的任何具名部分組成，並由django.urls.path() 或django.urls.re_path() 的可選 kwargs 引數中指定的任何引數覆寫。

5. 如果沒有 URL 模式匹配，或者在此過程中的任何點引發例外，Django 將會呼叫適當的錯誤處理視圖。請參閱下方的錯誤處理。

範例¶

以下是一個範例 URLconf

from django.urls import path

from . import views

urlpatterns = [
    path("articles/2003/", views.special_case_2003),
    path("articles/<int:year>/", views.year_archive),
    path("articles/<int:year>/<int:month>/", views.month_archive),
    path("articles/<int:year>/<int:month>/<slug:slug>/", views.article_detail),
]

注意事項

• 若要從 URL 擷取值，請使用角括號。

• 擷取的值可以選擇性地包含轉換器類型。例如，使用 <int:name> 擷取整數參數。如果未包含轉換器，則會比對任何字串（不包括 / 字元）。

• 無需新增前導斜線，因為每個 URL 都有前導斜線。例如，它是 articles，而不是 /articles。

範例請求

• 對 /articles/2005/03/ 的請求會比對列表中的第三個項目。Django 會呼叫函數 views.month_archive(request, year=2005, month=3)。

• /articles/2003/ 會比對列表中的第一個模式，而不是第二個模式，因為模式是依序測試的，而第一個模式是第一個通過測試的模式。您可以自由利用排序來插入像這樣的特殊案例。在這裡，Django 會呼叫函數 views.special_case_2003(request)

• /articles/2003 不會比對任何這些模式，因為每個模式都要求 URL 以斜線結尾。

• /articles/2003/03/building-a-django-site/ 會比對最後一個模式。Django 會呼叫函數 views.article_detail(request, year=2003, month=3, slug="building-a-django-site")。

路徑轉換器¶

預設情況下，可以使用以下路徑轉換器

• str - 比對任何非空字串，但不包括路徑分隔符號 '/'。如果表達式中未包含轉換器，則此為預設值。

• int - 比對零或任何正整數。傳回 int。

• slug - 比對由 ASCII 字母或數字，以及連字號和底線字元組成的任何 slug 字串。例如，building-your-1st-django-site。

• uuid - 比對格式化的 UUID。為防止多個 URL 映射到同一個頁面，必須包含破折號，並且字母必須是小寫字母。例如，075194d3-6885-417e-a8a8-6c931e272f00。傳回 UUID 實例。

• path - 比對任何非空字串，包括路徑分隔符號 '/'。這可讓您比對完整的 URL 路徑，而不是像 str 一樣的 URL 路徑的片段。

註冊自訂路徑轉換器¶

針對更複雜的匹配需求，您可以定義自己的路徑轉換器。

轉換器是一個包含以下內容的類別

• 作為字串的 regex 類別屬性。

• to_python(self, value) 方法，用於處理將匹配的字串轉換為應傳遞至視圖函數的類型。如果無法轉換給定的值，則應引發 ValueError。ValueError 會被解釋為不匹配，因此，除非另一個 URL 模式匹配，否則會將 404 回應傳送給使用者。

• to_url(self, value) 方法，用於處理將 Python 類型轉換為要在 URL 中使用的字串。如果無法轉換給定的值，則應引發 ValueError。ValueError 會被解釋為不匹配，因此，除非另一個 URL 模式匹配，否則reverse() 會引發 NoReverseMatch。

例如

class FourDigitYearConverter:
    regex = "[0-9]{4}"

    def to_python(self, value):
        return int(value)

    def to_url(self, value):
        return "%04d" % value

使用 register_converter() 在您的 URLconf 中註冊自訂轉換器類別

from django.urls import path, register_converter

from . import converters, views

register_converter(converters.FourDigitYearConverter, "yyyy")

urlpatterns = [
    path("articles/2003/", views.special_case_2003),
    path("articles/<yyyy:year>/", views.year_archive),
    ...,
]

使用正規表示式¶

如果路徑和轉換器語法不足以定義您的 URL 模式，您也可以使用正規表示式。若要這樣做，請使用re_path() 而不是path()。

在 Python 正規表示式中，具名正規表示式群組的語法為 (?P<name>pattern)，其中 name 是群組的名稱，而 pattern 是要比對的某些模式。

以下是先前使用正規表示式重寫的範例 URLconf

from django.urls import path, re_path

from . import views

urlpatterns = [
    path("articles/2003/", views.special_case_2003),
    re_path(r"^articles/(?P<year>[0-9]{4})/$", views.year_archive),
    re_path(r"^articles/(?P<year>[0-9]{4})/(?P<month>[0-9]{2})/$", views.month_archive),
    re_path(
        r"^articles/(?P<year>[0-9]{4})/(?P<month>[0-9]{2})/(?P<slug>[\w-]+)/$",
        views.article_detail,
    ),
]

這大致完成了與先前範例相同的操作，除了

• 將匹配的確切 URL 略為受限。例如，年份 10000 將不再匹配，因為年份整數被限制為正好四位數字。

• 無論正規表示式進行哪種比對，每個擷取的引數都會以字串的形式傳送至視圖。

從使用 path() 切換到 re_path() 或反之亦然時，特別要注意視圖引數的類型可能會變更，因此您可能需要調整視圖。

from django.urls import re_path

urlpatterns = [
    re_path(r"^blog/(page-([0-9]+)/)?$", blog_articles),  # bad
    re_path(r"^comments/(?:page-(?P<page_number>[0-9]+)/)?$", comments),  # good
]

URLconf 搜尋的對象¶

URLconf 會針對請求的 URL 進行搜尋，將其視為一般的 Python 字串。這不包含 GET 或 POST 參數，或是網域名稱。

例如，在對 https://www.example.com/myapp/ 的請求中，URLconf 將會搜尋 myapp/。

在對 https://www.example.com/myapp/?page=3 的請求中，URLconf 將會搜尋 myapp/。

URLconf 不會查看請求方法。換句話說，所有請求方法 – POST、GET、HEAD 等 – 都會將相同的 URL 路由到相同的函式。

為檢視引數指定預設值¶

一個方便的技巧是為檢視的引數指定預設參數。以下是一個 URLconf 和檢視的範例

# URLconf
from django.urls import path

from . import views

urlpatterns = [
    path("blog/", views.page),
    path("blog/page<int:num>/", views.page),
]


# View (in blog/views.py)
def page(request, num=1):
    # Output the appropriate page of blog entries, according to num.
    ...

在上面的範例中，兩個 URL 模式都指向相同的檢視 – views.page – 但第一個模式不會從 URL 中捕獲任何內容。如果第一個模式比對，page() 函式將會為 num 使用其預設引數 1。如果第二個模式比對，page() 將會使用捕獲到的任何 num 值。

效能¶

Django 會處理 urlpatterns 清單中的正規表示式，該清單會在第一次存取時編譯。後續的請求會透過 URL 解析器使用快取的組態。

urlpatterns 變數的語法¶

urlpatterns 應該是 sequence 的 path() 和/或 re_path() 執行個體。

錯誤處理¶

當 Django 無法找到請求 URL 的比對，或者當發生例外時，Django 會調用錯誤處理檢視。

這些情況要使用的檢視由四個變數指定。它們的預設值應該足以應付大多數專案，但可以透過覆寫其預設值來進行進一步的自訂。

如需完整詳細資訊，請參閱關於 自訂錯誤檢視 的文件。

這些值可以在根 URLconf 中設定。在任何其他 URLconf 中設定這些變數都將不起作用。

值必須是可呼叫的，或者是以字串形式表示應調用以處理當前錯誤狀況的檢視的完整 Python 導入路徑。

變數如下

• handler400 – 請參閱 django.conf.urls.handler400。

• handler403 – 請參閱 django.conf.urls.handler403。

• handler404 – 請參閱 django.conf.urls.handler404。

• handler500 – 請參閱 django.conf.urls.handler500。

包含其他 URLconf¶

在任何時候，您的 urlpatterns 都可以「包含」其他 URLconf 模組。這基本上會將一組 URL「紮根」在其他 URL 之下。

例如，以下是 Django 網站本身的 URLconf 的摘錄。它包含了許多其他 URLconf

from django.urls import include, path

urlpatterns = [
    # ... snip ...
    path("community/", include("aggregator.urls")),
    path("contact/", include("contact.urls")),
    # ... snip ...
]

每當 Django 遇到 include() 時，它會切斷 URL 中到該點為止比對到的任何部分，並將剩餘的字串傳送到包含的 URLconf 進行進一步處理。

另一種可能性是使用 path() 執行個體的清單來包含其他 URL 模式。例如，考慮此 URLconf

from django.urls import include, path

from apps.main import views as main_views
from credit import views as credit_views

extra_patterns = [
    path("reports/", credit_views.report),
    path("reports/<int:id>/", credit_views.report),
    path("charge/", credit_views.charge),
]

urlpatterns = [
    path("", main_views.homepage),
    path("help/", include("apps.help.urls")),
    path("credit/", include(extra_patterns)),
]

在此範例中，/credit/reports/ URL 將由 credit_views.report() Django 檢視處理。

這可用於從重複使用單一模式前綴的 URLconf 中消除多餘的部分。例如，考慮此 URLconf

from django.urls import path
from . import views

urlpatterns = [
    path("<page_slug>-<page_id>/history/", views.history),
    path("<page_slug>-<page_id>/edit/", views.edit),
    path("<page_slug>-<page_id>/discuss/", views.discuss),
    path("<page_slug>-<page_id>/permissions/", views.permissions),
]

我們可以透過只聲明一次通用路徑前綴並將不同的後綴分組來改進這一點

from django.urls import include, path
from . import views

urlpatterns = [
    path(
        "<page_slug>-<page_id>/",
        include(
            [
                path("history/", views.history),
                path("edit/", views.edit),
                path("discuss/", views.discuss),
                path("permissions/", views.permissions),
            ]
        ),
    ),
]

# In settings/urls/main.py
from django.urls import include, path

urlpatterns = [
    path("<username>/blog/", include("foo.urls.blog")),
]

# In foo/urls/blog.py
from django.urls import path
from . import views

urlpatterns = [
    path("", views.blog.index),
    path("archive/", views.blog.archive),
]

將額外選項傳遞給檢視函式¶

URLconf 有一個勾點，可讓您以 Python 字典的形式將額外的引數傳遞給檢視函式。

path() 函式可以採用可選的第三個引數，該引數應為要傳遞給檢視函式的額外關鍵字引數的字典。

例如

from django.urls import path
from . import views

urlpatterns = [
    path("blog/<int:year>/", views.year_archive, {"foo": "bar"}),
]

在此範例中，對於 /blog/2005/ 的請求，Django 將會呼叫 views.year_archive(request, year=2005, foo='bar')。

此技巧用於 聯合內容框架 中，以將中繼資料和選項傳遞給檢視。

# main.py
from django.urls import include, path

urlpatterns = [
    path("blog/", include("inner"), {"blog_id": 3}),
]

# inner.py
from django.urls import path
from mysite import views

urlpatterns = [
    path("archive/", views.archive),
    path("about/", views.about),
]

# main.py
from django.urls import include, path
from mysite import views

urlpatterns = [
    path("blog/", include("inner")),
]

# inner.py
from django.urls import path

urlpatterns = [
    path("archive/", views.archive, {"blog_id": 3}),
    path("about/", views.about, {"blog_id": 3}),
]

反向解析 URL¶

在 Django 專案中工作時，一個常見的需求是能夠以最終形式取得 URL，無論是為了嵌入在產生的內容中 (檢視和資源 URL、向使用者顯示的 URL 等)，或是為了處理伺服器端的導覽流程 (重新導向等)

強烈建議避免硬式編碼這些 URL (這是一種費力、不可擴展且容易出錯的策略)。同樣危險的是設計特設機制來產生與 URLconf 所描述的設計平行的 URL，這可能會導致產生隨著時間推移而過時的 URL。

換句話說，需要的是一種 DRY 機制。在其他優點中，它允許 URL 設計的發展，而不必查看所有專案原始碼來搜尋和取代過時的 URL。

我們能用來取得 URL 的主要資訊是負責處理該 URL 的視圖的識別資訊（例如名稱）。其他必須參與查找正確 URL 的資訊包括視圖參數的類型（位置、關鍵字）和值。

Django 提供了一個解決方案，讓 URL 對應器成為 URL 設計的唯一儲存庫。您將 URLconf 提供給它，然後它就可以雙向使用。

• 從使用者/瀏覽器請求的 URL 開始，它會呼叫正確的 Django 視圖，並提供從 URL 提取的任何參數及其值。

• 從對應的 Django 視圖的識別資訊，加上將傳遞給它的參數值開始，取得相關聯的 URL。

第一個是我們在前面章節中討論的用法。第二個稱為 URL 的反向解析、反向 URL 比對、反向 URL 查詢，或簡稱為 URL 反轉。

Django 提供了執行 URL 反轉的工具，這些工具與需要 URL 的不同層級相符。

• 在範本中：使用 url 範本標籤。

• 在 Python 程式碼中：使用 reverse() 函式。

• 在與 Django 模型實例的 URL 處理相關的較高層級程式碼中：get_absolute_url() 方法。

from django.urls import path

from . import views

urlpatterns = [
    # ...
    path("articles/<int:year>/", views.year_archive, name="news-year-archive"),
    # ...
]

<a href="{% url 'news-year-archive' 2012 %}">2012 Archive</a>
{# Or with the year in a template context variable: #}
<ul>
{% for yearvar in year_list %}
<li><a href="{% url 'news-year-archive' yearvar %}">{{ yearvar }} Archive</a></li>
{% endfor %}
</ul>

from django.http import HttpResponseRedirect
from django.urls import reverse


def redirect_to_year(request):
    # ...
    year = 2006
    # ...
    return HttpResponseRedirect(reverse("news-year-archive", args=(year,)))

命名 URL 模式¶

為了執行 URL 反轉，您需要使用已命名的 URL 模式，如上面的範例所示。用於 URL 名稱的字串可以包含您喜歡的任何字元。您不限於有效的 Python 名稱。

命名 URL 模式時，請選擇不太可能與其他應用程式的名稱選擇衝突的名稱。如果您將您的 URL 模式命名為 comment，而另一個應用程式也做了相同的事情，那麼 reverse() 找到的 URL 取決於您的專案 urlpatterns 清單中最後一個模式。

在您的 URL 名稱上加上前綴，可能來自應用程式名稱（例如 myapp-comment 而不是 comment），可以減少衝突的機會。

如果您想要覆寫視圖，您可以刻意選擇與另一個應用程式相同的 URL 名稱。例如，一個常見的用例是覆寫 LoginView。Django 的某些部分和大多數第三方應用程式都假設此視圖具有一個名稱為 login 的 URL 模式。如果您有一個自訂的登入視圖，並將其 URL 命名為 login，只要它在包含 django.contrib.auth.urls（如果有的話）之後的 urlpatterns 中，reverse() 就會找到您的自訂視圖。

如果多個 URL 模式的參數不同，您也可以為它們使用相同的名稱。除了 URL 名稱之外，reverse() 還會比對參數的數量和關鍵字參數的名稱。路徑轉換器也可以引發 ValueError 以表示不符合，詳細資訊請參閱 註冊自訂路徑轉換器。

URL 命名空間¶

from django.urls import include, path

urlpatterns = [
    path("author-polls/", include("polls.urls", namespace="author-polls")),
    path("publisher-polls/", include("polls.urls", namespace="publisher-polls")),
]

from django.urls import path

from . import views

app_name = "polls"
urlpatterns = [
    path("", views.IndexView.as_view(), name="index"),
    path("<int:pk>/", views.DetailView.as_view(), name="detail"),
    ...,
]

from django.urls import path

from . import views

app_name = "polls"
urlpatterns = [
    path("", views.IndexView.as_view(), name="index"),
    path("<int:pk>/", views.DetailView.as_view(), name="detail"),
    ...,
]

from django.urls import include, path

urlpatterns = [
    path("polls/", include("polls.urls")),
]

(<list of path()/re_path() instances>, <application namespace>)

from django.urls import include, path

from . import views

polls_patterns = (
    [
        path("", views.IndexView.as_view(), name="index"),
        path("<int:pk>/", views.DetailView.as_view(), name="detail"),
    ],
    "polls",
)

urlpatterns = [
    path("polls/", include(polls_patterns)),
]