django CMS Apphook(应用钩子)机制详解:把 Django 应用挂载到 CMS 页面的路由架构
django CMS Apphook(应用钩子)机制详解:把 Django 应用挂载到 CMS 页面的路由架构
Apphook(Application Hook,应用钩子)是 django CMS 将任意 Django 应用的 URL 树挂载到 CMS 页面上的核心机制:一个带 apphook 的页面会变成一个"挂载点",其自身及其下所有 URL 全部交给被挂载的应用去解析。本文基于仓库中的概念文档 docs/explanation/apphooks.rst,结合 cms/app_base.py、cms/apphook_pool.py、cms/appresolver.py 等源码,从概念模型、请求路由、发布约束到源码级实现原理,完整讲清 apphook 的工作方式,读完后你将掌握如何评估"页面直接渲染"与"页面挂载应用"两种方案的取舍,并理解 apphook 在 slug 冲突、菜单集成、权限与发布流程中的位置。
一、Apphook 是什么:把页面变成应用 URL 的"挂载点"
一个 Application Hook(通常简称为 apphook)的作用是把一个 Django 应用的 URL 树"挂"到一个 django CMS 页面上。概念上,apphook 把一个 CMS 页面变成一个挂载点(mount point):一旦挂载完成,发往该页面(以及该页面路径之下的所有路径)的请求,都将被路由进被挂载的应用,而不再当作普通的 CMS 页面内容来渲染。
可以把它理解为"把一段 URLconf include 进项目的 urls.py"——区别在于,基础路径(base path)由内容编辑者通过页面树来定义,而不是由开发者硬编码在代码里。文档给出了非常直观的示例:
/records/ -> handled by the attached application's URLs
/records/1984/ -> handled by the attached application's URLs
/records/... -> handled by the attached application's URLs
换句话说:CMS 页面提供基础路径(/records),应用提供其下的其余 URL 空间(/1984/)。
文档以一个"奥运会纪录(Olympic records)"应用为例:你可以把这个应用加进项目的 urls.py(放在 django CMS 的 URL 模式之前),让用户通过 /records 访问它。但这只是把它集成进了 project,并没有完整地集成进 django CMS:
- django CMS 不会感知到这个 URL 空间,编辑者完全可能创建一个 slug 为
records的 CMS 页面——这个页面将永远无法被访问到(slug 冲突不可见); - 应用的页面不会自动出现在站点的菜单里;
- 应用的页面无法利用 CMS 的发布工作流、权限体系等其他功能。
Apphook 通过"让 CMS 感知该 URL 空间"来提供更完整的集成。
二、请求处理发生了什么变化
没有 apphook 时,一个形如 /records/1984/ 的请求先由 Django 的 URLconf 解析,如果落到 CMS 部分,再由 django CMS 处理。
有了 apphook 之后,django CMS 把被挂载的页面当作一条"路由条目"来处理:
- 先解析基础路径(
/records/)对应的 CMS 页面; - 如果该页面挂载了 apphook(并且已发布),就把剩余路径(
1984/)的 URL 解析工作委托给应用的 URLconf。
正是这种委托关系,让 apphook 被形容为"吞掉(swallowing)"页面之下的 URL 空间——应用接管了基础路径之下的所有内容。
从源码看,这条委托链路在 cms/urls.py 中实现:urlpatterns 的第一条是一个 LazyURLResolver(RegexPattern(r''), 'app_resolver', get_urlpatterns=_get_apphook_urlpatterns),它惰性地调用 _get_apphook_urlpatterns()——该函数避免在导入时触碰数据库,只有在存在已注册 apphook 时才调用 cms/appresolver.py 中的 get_app_patterns() 生成挂载模式。这个空正则的解析器排在 pages-details-by-slug 与 pages-root 之前,意味着应用挂载模式的优先级高于普通 CMS 页面解析。
在 cms/appresolver.py 中,AppRegexURLResolver 按语言缓存每个挂载点的 URL 模式(url_patterns_dict[lang]),并实现 resolve_page_id(path):在无法解析到应用视图时抛 Resolver404,从而让请求回落到 CMS 的 details 视图;applications_page_check(request) 则用于在 apphook 模式下反查请求对应的页面对象。
三、挂载之后具体发生了什么
当你把一个应用挂到某个 CMS 页面上时,会产生如下效果:
- 该 CMS 页面的 URL 成为应用的基础路径(例如
/records); - 应用接管基础路径之下的全部 URL(例如
/records/1984); - django CMS 可以把该应用视为站点结构的一部分——例如阻止产生会导致挂载应用不可达的 slug 冲突,并支持菜单集成。
实际效果是:这个 CMS 页面表现得就像项目 URLconf 里的一条路由条目。也因此,应用可以被内容管理者定义的 URL 所承载,并且可以通过移动页面来移动应用在站点结构中的位置。
需要注意,apphook 只有在编辑者把它挂载到页面上之后才会生效(具体操作见 docs/how_to/11-apphooks.rst)。
四、Apphook 属于 CMS 的"发布"模型
文档用 important 提醒强调了一个关键约束:
Apphooks are part of the CMS publishing model.
- 在页面**发布(published)**之前,apphook 不会服务任何公网流量;
- 这也意味着路径上的所有父页面都必须已发布。
也就是说,apphook 是否对外生效,完全由 CMS 的发布状态决定——挂载点是否公开,首先是一个发布控制问题。这与 docs/explanation/publishing.rst 描述的 CMS 发布工作流是一体的。
五、影响与权衡:从"渲染自身内容"到"成为挂载点"
Apphook 用"页面渲染自己的内容"换来了"页面成为挂载点",这带来几个实际后果:
- Slug 冲突变得对 CMS 可见:因为 django CMS 拥有该基础路径,它可以阻止编辑者创建会让被挂载应用不可达的页面;
- 菜单集成成为可能:被挂载应用的页面可以参与站点的导航(取决于应用/apphook 提供的菜单集成能力);
- CMS 工作流与权限可以应用:至少,发布与否决定了挂载点是否公开;更深入的集成则因应用而异。
文档同时给出了一个重要警告:
An apphook "swallows" all URLs below the apphooked page.
被挂载页面之下的子页面将不再可靠地可达,因为该路径下的请求都被路由给了应用。对需要子页面的高级场景,必须显式地把请求"路由回" CMS(在 docs/how_to/11-apphooks.rst 的 "Sub-pages of an apphooked page" 一节中给出了用 reroute_cms_page 视图配合 re_path(r"^(?P<path>world/.*)$", reroute_cms_page, {"page": page}) 回指 cms.views.details 的完整示例)。
六、同一应用可以多次挂载,并且支持配置化
同一个应用可以被挂载到不同的页面上多次,每次挂载都会产生一个不同的挂载点——例如 /records 和 /results 可以同时路由进同一个应用(参见 docs/how_to/11-apphooks.rst 关于多实例的说明)。
更进一步,一个应用还可以支持多种配置(configuration),让每个挂载点的行为互不相同。回到奥运纪录的例子:应用可能在一个位置发布田径(athletics)成绩,在另一个位置发布自行车(cycling)成绩。通过 apphook 配置类,站点编辑者可以创建多个配置实例来指定这种差异化的行为。
在 cms/app_base.py 中,CMSApp 基类为配置化提供了三个抽象钩子:get_configs()(返回全部配置实例)、get_config(namespace)(按命名空间返回配置实例)、get_config_add_url()(返回新增配置实例的 URL,通常是 model admin 的 add 视图);同时 app_config 属性用于声明配置模型,且 __new__ 中强制"每个 AppHookConfiguration 只能对应一个 AppHook",防止一个配置类被多个 apphook 复用。
术语辨析:三个容易混淆的概念
文档用一张表格清晰区分了 apphook 涉及的三个概念:
| 概念 | 由谁定义 | 含义 |
|---|---|---|
| Apphook 类(Apphook class) | 开发者 | 把 CMS 页面与应用 URLconf 连接起来的代码("在这里挂载这个应用") |
| Apphook 配置类(Apphook configuration class) | 开发者 | 描述存在哪些配置选项("编辑者可以选什么?") |
| Apphook 配置实例(Apphook configuration instance) | 编辑者 | 为某个挂载点选定的具体配置数据("这里用自行车模式") |
可用的配置选项通过 admin 表单呈现,而这些选项由应用开发者决定。同样地,apphook(以及 apphook 配置)在被挂载到页面之前不发挥任何作用,且直到页面发布之前,应用在该位置对公众都是不可达的。
七、源码级深入:Apphook 的注册、发现与 URL 重写
7.1 注册与发现:ApphookPool
所有 apphook 都通过全局单例 apphook_pool(定义于 cms/apphook_pool.py)管理。其核心方法:
register(app):既可作为装饰器(@apphook_pool.register),也可直接调用。注册时校验类必须继承自cms.app_base.CMSApp(否则抛出ImproperlyConfigured),同名 apphook 重复注册会抛出AppAlreadyRegistered;若定义了menu属性而menus为空还会给出拼写提示警告。注册成功后以app.__name__为键实例化并存入self.apps。discover_apps():当设置项CMS_APPHOOKS非空时,按字符串路径逐个import_string导入注册;否则调用 Django 的autodiscover_modules('cms_apps'),自动在每个 INSTALLED_APPS 里寻找cms_apps.py文件。这正是"在应用中新建cms_apps.py并放入CMSApp子类即可被自动发现"的底层来源。get_apphooks():遍历已注册应用,仅保留get_urls()返回非空列表的项,按展示名称排序后返回(app_name, name)元组列表;它也是 CMS 后台"应用"下拉框的数据来源。get_apphook(app_name):按类名查找实例;找不到时回退到按 urlconf 名匹配的兼容逻辑(兼容旧版以 urlconf 名注册的方式),仍找不到则给出No registered apphook ...警告并返回None。
7.2 URL 重写:把应用模式"前缀化"后挂入 CMS
在 cms/appresolver.py 的 _get_app_patterns() 中可以看到完整的挂载实现:
- 查询所有
PageUrl,过滤出page__application_urls非空的记录,并按page__path降序排列(子路径优先); - 通过
apphook_pool.get_apphook()拿到应用实例,调用其get_urls()得到 urlconf 列表; recurse_patterns(path, pattern_list, page_id)把应用中每个 URL 模式的正则拼接上页面路径前缀(rf'^{path}{app_pat}'),并用resolver.page_id = page_id记录每个模式所属页面——这就是"基础路径来自页面、剩余路径来自应用"的代码级体现;AppRegexURLResolver为每个挂载点按语言保存重写后的模式,并写入模块级APP_RESOLVERS列表;- 若应用声明
permissions = True,则用_set_permissions遍历所有模式,把每个 callback 用 cms/utils/decorators.py 的cms_perms装饰器包装(该装饰器读取request.current_page,执行login_required登录跳转与user_can_view_page查看权限检查),实现"apphook 继承页面权限"的默认行为;exclude_permissions列出的命名空间会被跳过。
7.3 变更自动重载:ApphookReloadMiddleware 与信号
新增/移除 apphook、或改动含 apphook 页面(或其有 apphook 后代的页面)的 slug 后,URL 缓存必须重载。仓库提供了两种方式:
- 推荐做法:安装
cms.middleware.utils.ApphookReloadMiddleware。它在每个请求的前后调用apphook_reload.ensure_urlconf_is_up_to_date()(见 cms/middleware/utils.py):通过对比数据库UrlconfRevision(见 cms/utils/apphook_reload.py 的get_global_revision()/get_local_revision())的版本号,发现变化时调用reload_urlconf()——重载cms.urls与ROOT_URLCONF、清空 URL 缓存、重新生成 app 模式。 - 信号方式:CMS 会监听请求结束,发出
cms.signals.urls_need_reloading信号(见 cms/signals/apphook.py)。需要说明的是:该信号本身不做任何事,自动化重启逻辑需由项目自行实现(因为 Django 的部署方式千差万别,CMS 无法提供通用的解决方案);且信号在请求之后触发(例如保存页面设置时),若通过 API 修改 apphook 设置,信号要等到下一次请求才会发出。
八、实战要点:从概念到落地
以下要点来自 docs/how_to/11-apphooks.rst,与本概念文档互为补充:
-
创建:在应用目录新建
cms_apps.py,定义CMSApp子类并注册:from cms.app_base import CMSApp from cms.apphook_pool import apphook_pool @apphook_pool.register class MyApphook(CMSApp): app_name = "myapp" # 必须与应用命名空间一致 name = "My Apphook" def get_urls(self, page=None, language=None, **kwargs): return ["myapp.urls"] # 指向应用的 URL 模块 -
命名空间:应用应使用命名空间 URL;
app_name必须与应用命名空间匹配,否则模板里的{% url 'myapp:index' %}或reverse('myapp:index')会抛出NoReverseMatch。对无命名空间的第三方应用,apphook 应省略app_name,且这种 apphook 只能挂载到一个页面。 -
发布:页面及其所有父页面必须发布,apphook 才会生效。
-
权限:默认继承页面权限;设
permissions = False可关闭,用cms.utils.decorators.cms_perms装饰器可为单个视图开启;exclude_permissions可列出不继承权限的子应用名。 -
菜单:通过重写
get_menus(page=None, language=None, **kwargs)返回菜单类列表(CMSApp.menus属性自 3.3 起废弃、3.5 移除),返回的菜单类需在其get_nodes()中产出节点。 -
模板占位符(5.1+):apphook 视图模板中仍可使用
{% placeholder "content" %}标签,因为 django CMS 会为 apphook 请求设置request.current_page,占位符默认解析到当前页面的PageContent(含inherit向上继承);若视图调用request.toolbar.set_object(...)传入使用PlaceholderRelationField的模型实例,则改为解析该对象的占位符。 -
结构视图模板(5.1+):
CMSApp.get_root_template()会尝试从匹配空路径的根视图的template_name(CBV 类属性或as_view(template_name=...)参数)推断模板名;函数视图、运行时选模板、直接返回渲染HttpResponse的视图无法推断,需重写该方法按page/language返回模板名,且返回的模板必须与根视图实际渲染的一致,否则结构视图上的占位符会与页面实际渲染不一致。 -
卸载:移除仍有实例挂在页面上的 apphook 类时,页面会保留记录(若重新安装则恢复)、列表仍显示指示、页面退化为普通 CMS 页面;保存其 Advanced settings 会移除 apphook。也可用管理命令清理:
python -m manage cms uninstall apphooks MyApphook MyOtherApphook,并用python -m manage cms list apphooks查看已安装列表。
九、总结
Apphook 是 django CMS 连接"页面树"与"任意 Django 应用"的桥梁:页面提供基础路径并受发布模型控制,应用接管其下的全部 URL 空间。理解"挂载点"这一心智模型,就理解了它为何能带来 CMS 可见的 slug 冲突防护、菜单集成与权限继承,也理解了它为何会"吞掉"子页面 URL、为何必须依赖发布状态。结合 cms/apphook_pool.py 的注册发现、cms/appresolver.py 的 URL 重写与 cms/middleware/utils.py 的自动重载,你可以放心地把新闻、博客、论坛等任何 Django 应用以可控的方式挂进 django CMS 的内容架构中。