路由系统基础

URLconf = URL 与视图之间的映射表。ROOT_URLCONF 是入口。

核心概念

• urlpatterns — 路由列表，元素是 path() / re_path() 的结果
• ROOT_URLCONF — 入口 URLconf 模块路径
• 匹配规则：URL 视作普通字符串（不含协议 / 域名 / 查询串），按顺序匹配，命中即停止
• 不区分 HTTP 方法（GET/POST 都会路由到同一视图，由视图自己处理）

推荐结构

每个 App 维护自己的 urls.py，根 URLconf 通过 include 分发：

# config/urls.py
urlpatterns = [
    path("admin/", admin.site.urls),
    path("post/", include("post.urls")),
    path("auth/", include("django.contrib.auth.urls")),
]

path / re_path / include

path

path("topic/<int:pk>/", views.detail, name="topic_detail")

参数：

• route — URL 模式
• view — 视图函数 / View.as_view() / include() 结果
• kwargs — 额外字典参数
• name — 命名（用于反向解析）

kwargs 示例：

path("topic/<int:pk>/", views.detail, kwargs={"foo": "bar"})

def detail(request, pk, foo):
    ...

URL 中显式给出的参数会覆盖 kwargs 同名项。

re_path

正则路由，灵活度更高：

re_path(r"^articles/(?P<year>[0-9]{4})/$", views.year_archive)

2026 年更推荐 path + 自定义转换器，正则只在必要时使用。

include

# 1. 引入模块
include("post.urls")

# 2. 引入可迭代的 path 列表
include([
    path("a/", views.a),
    path("b/", views.b),
], namespace="x")

转换器

名称	匹配	转换
str	非空字符串（默认）	str
int	整数	int
slug	[a-zA-Z0-9_-]+	str
uuid	UUID 字符串	UUID
path	包含 / 的字符串	str

自定义：

class YearConverter:
    regex = r"20[0-9]{2}"
    def to_python(self, value): return int(value)
    def to_url(self, value): return str(value)

register_converter(YearConverter, "year")

参数传递的四种姿势

方式	适用
无参	静态页 / 首页
kwargs	注入视图默认值
请求参数	request.GET / request.POST
路径参数	<converter:name> 或正则命名组

自定义错误页面

1. settings.py 设 DEBUG = False
2. templates/ 下放 400.html / 403.html / 404.html / 500.html
3. 在 App 的 views.py 中定义同名视图
4. 根 urls.py 注册：

handler400 = "post.views.bad_request"
handler403 = "post.views.permission_denied"
handler404 = "post.views.page_not_found"
handler500 = "post.views.server_error"

名字固定，handler 名称不可修改。