Django URL 路徑設置｜name 參數與命名空間（Namespace）
更新日期： 2024 年 11 月 28 日
本文為 Django 進階教學，第 2 篇：
- 理解 Django 中的相對路徑與絕對路徑
- Django URL 路徑設置｜name 參數與命名空間（Namespace） 👈 所在位置
- Django 串接資料庫與模型建構：完整入門指南
- Django 模型遷移與資料庫同步完整指南
- 使用 Django ORM 將資料寫入資料庫：新手入門指南
- Django 實現 CRUD 的 C（Create）：新增資料功能完整指南
- Django CRUD 的 R（Read）：資料讀取與顯示功能指南
- Django CRUD 的 U（Update）：資料更新功能完整指南
- Django CRUD 的 D（Delete）：資料刪除功能完整指南
建議閱讀本文前，先閱讀完 Django 新手教學 系列文
在 Django 中，urls.py 是管理 URL 路徑的核心配置文件。
有效地設置與命名 URL 不僅能讓代碼更清晰，也能在專案變得複雜時降低維護成本。
本文將介紹設置路徑的最佳實踐，包括推薦的模組引用方式、name 參數的意義與應用，以及命名空間（namespace）的使用。
項目目錄結構示意圖
以下是我們設定 URL 路徑所涉及的目錄結構示意圖：
mysite/
│
├── manage.py
├── mysite/
│ ├── settings.py
│ ├── urls.py # 主應用路由
│
├── resumes/ # Resumes 應用
│ ├── __init__.py
│ ├── views.py # 定義視圖函數
│ ├── urls.py # Resumes 應用路由
│ ├── templates/
│ ├── resumes/
│ ├── home.html # Resumes 應用的模板文件
設置應用的 URL 路徑
在 resumes/urls.py 中，設置應用的路徑如下：
from django.urls import path
from . import views
urlpatterns = [
path("", views.home), # 根路徑對應 home 視圖
path("new/", views.new) # "new/" 路徑對應 new 視圖
]推薦的模組引用方式
我們建議使用 from . import views 的方式，而非逐一從模組導入函數。
例如：
from . import views這樣當我們在 views.py 中新增函數後，不需要修改 urls.py 中的 from 引用，只需直接在 path() 函數中調用 views.函數名稱 即可，例如：
urlpatterns = [
path("", views.home),
path("new/", views.new),
path("edit/", views.edit), # 無需修改 from 引用，只新增 path
]這種方式可以有效減少代碼重複，特別是在視圖函數多且經常變動的情況下，讓 URL 配置文件更易於維護。
使用 name 參數為路徑命名
為 URL 路徑添加 name 參數可以為每個路徑指定唯一標識，便於在模板或代碼中動態引用。
例如：
urlpatterns = [
path("", views.home),
path("new/", views.new, name='resume_new')
]name 的作用與實際應用
假設原始模板中硬編碼路徑如下：
<a href="/resumes/new">新增 resume</a>如果後期路徑從 /resumes/new 改為 /resumes/create，需要逐一修改所有引用該路徑的模板。
改用命名路由後，模板代碼如下：
<a href="{% url 'resume_new' %}">新增 resume</a>只需更新 urls.py：
path("create/", views.new, name='resume_new')所有使用 resume_new 名稱的模板會自動更新，無需再逐一修改代碼，極大地降低了維護成本。
使用命名空間（Namespace）避免路徑名稱衝突
命名衝突問題
當多個應用中使用相同的路徑名稱時，會引發命名衝突。
例如：
# resumes/urls.py
urlpatterns = [
path("new/", views.new, name='new'), # Resumes 應用的 "new" 路徑
]
# blog/urls.py
urlpatterns = [
path("new/", views.new, name='new'), # Blog 應用的 "new" 路徑
]如果模板中使用 {% url 'new' %}，Django 無法判斷應該匹配哪個路徑，從而引發錯誤。
解決方法：設置命名空間
可以為每個應用設置命名空間，讓路徑名稱變得唯一且可區分：
在 resumes/urls.py 中：
from django.urls import path
from . import views
app_name = 'resumes' # 定義 Resumes 應用的命名空間
urlpatterns = [
path("", views.home),
path("new/", views.new, name='new') # 路徑名稱依然為 "new"
]
在 blog/urls.py 中：
from django.urls import path
from . import views
app_name = 'blog' # 定義 Blog 應用的命名空間
urlpatterns = [
path("", views.home),
path("new/", views.new, name='new')
]模板中使用命名空間
設置命名空間後，在模板中需要明確指定應用的命名空間，例如：
<!-- 引用 Resumes 應用的 "new" 路徑 -->
<a href="{% url 'resumes:new' %}">新增 resume</a>
<!-- 引用 Blog 應用的 "new" 路徑 -->
<a href="{% url 'blog:new' %}">新增文章</a>
命名空間的優勢
- 避免命名衝突：即使多個應用中使用相同的路徑名稱，命名空間確保了唯一性。
- 代碼結構清晰：通過命名空間，能夠快速識別路徑所屬的應用。
- 更易擴展：在多應用項目中，每個應用的路徑都能保持自洽，減少修改時的影響範圍。
5. 整體目錄結構更新
整合命名空間與模板後，目錄結構如下：
mysite/
│
├── manage.py
├── mysite/
│ ├── settings.py
│ ├── urls.py # 主應用路由
│
├── resumes/
│ ├── __init__.py
│ ├── views.py # 定義 home 和 new 視圖
│ ├── urls.py # 包含命名空間 "resumes"
│ ├── templates/
│ ├── resumes/
│ ├── home.html # 使用命名空間的模板文件
├── blog/
│ ├── __init__.py
│ ├── views.py # 定義 blog 視圖
│ ├── urls.py # 包含命名空間 "blog"
│ ├── templates/
│ ├── blog/
│ ├── home.html # Blog 的模板文件
小結
- 推薦模組引用方式：使用
from . import views簡化維護，減少模組引用的重複代碼。 - 使用
name動態生成路徑：實現方式：path("new/", views.new, name='resume_new')，模板中用{% url 'resume_new' %}動態生成。 - 設置命名空間：
- 通過
app_name避免路徑名稱衝突，例如resumes:new和blog:new。 - 確保多應用專案中路徑管理清晰且一致。
- 通過
通過這些技巧，Django URL 的管理將更加靈活、結構化，特別是在多應用專案中，能顯著提升代碼的可讀性與可維護性。