首页打印分享
文档目录
项目概述
架构设计
MVC分层设计
模块化架构
插件系统设计
路由系统
中间件管道
核心框架
引导程序系统
路由系统
中间件管道
依赖注入容器
前台应用
控制器层实现
服务层设计
视图模板系统
中间件管道
后台管理
权限控制系统
管理界面系统
数据管理功能
API接口
用户管理API
商品管理API
订单管理API
内容管理API
营销工具API
小程序模块
小程序架构设计
页面功能模块
组件系统
数据同步机制
样式系统与主题
业务功能模块
内容管理系统
电商平台系统
用户系统
营销工具
AI智能功能
支持服务
插件系统
插件开发指南
支付插件
社交登录插件
主题系统
模板语法规范
样式管理系统
资源组织管理
响应式设计
数据库设计
表结构设计
配置管理
部署运维
安装配置
性能优化
安全加固
监控告警
备份恢复
故障排查
开发指南
路由系统

简介

本技术文档围绕 DouPHP 的三端路由系统（前台、后台、API）展开，系统性说明路由解析的工作原理与实现机制，包括 URL 匹配、参数提取、路由优先级、中间件集成、约束与验证、配置示例与最佳实践、性能优化与调试方法。面向初学者解释基本概念与使用方式，同时为高级开发者提供自定义路由器与高级配置选项的指导。

项目结构

DouPHP 采用“入口统一引导 + 三端独立路由调度器 + 声明式路由匹配”的分层设计：

  • 根入口 index.php 负责全局引导、异常处理与前台路由委托。
  • core/bootstrap.php 完成常量定义、容器初始化、门面注册、Request 捕获与 DelegatingRouter 绑定。
  • 三端各自拥有 Router（薄壳调度器）与 Resolver（解析器），将请求转换为 DispatchPlan，交由中央 Dispatcher 执行。
  • 前台通过 PrettyRouteMatcher 进行外观 URL 到控制器/动作的映射；后台与 API 通过 BackendDeclaredMatcher 基于 route/*.php 声明条目匹配。
  • 路由风格规则集中配置于 config/route.php，支持多风格、短地址模块、可选段与命名参数等。
graph TB
A["根入口 index.php"] --> B["核心引导 core/bootstrap.php"]
B --> C["前台路由调度 front/foundation/routing/Router.php"]
B --> D["后台路由调度 admin/foundation/routing/Router.php"]
B --> E["API路由调度 api/foundation/routing/Router.php"]
C --> F["前台解析 front/foundation/routing/FrontResolver.php"]
D --> G["后台解析 admin/foundation/routing/AdminResolver.php"]
E --> H["API解析 api/foundation/routing/ApiResolver.php"]
F --> I["外观匹配 front/foundation/routing/PrettyRouteMatcher.php"]
G --> J["后端声明匹配(BackendDeclaredMatcher)"]
H --> J
I --> K["路由风格配置 config/route.php"]

图表来源

  • index.php:16-41
  • core/bootstrap.php:144-165
  • front/foundation/routing/Router.php:26-58
  • admin/foundation/routing/Router.php:26-66
  • api/foundation/routing/Router.php:28-70

章节来源

  • index.php:16-75
  • core/bootstrap.php:144-165

核心组件

  • 路由调度器（Router）：三端各自的薄壳调度器，读取 Request 中的路由字符串，调用对应 Resolver 生成 DispatchPlan，再交给中央 Dispatcher 执行。未匹配时返回特定响应或重定向。
  • 路由解析器（Resolver）：
    • 前台 FrontResolver：基于 PrettyRouteMatcher 匹配外观 URL，产出控制器 FQCN、动作、参数与中间件链。
    • 后台 AdminResolver：基于 BackendDeclaredMatcher 匹配 admin/route/*.php 声明条目，产出控制器与方法。
    • API ApiResolver：基于 BackendDeclaredMatcher 匹配 api/route/*.php 声明条目，产出控制器与方法。
  • 匹配器（Matcher）：
    • PrettyRouteMatcher：对外暴露外观 URL 匹配能力，结合 config/route.php 风格规则进行模式匹配与参数提取。
    • BackendDeclaredMatcher：对后台与 API 的声明式路由条目进行匹配，考虑 specificity 排序与 HTTP 方法过滤。
  • 中间件栈：各 Resolver 通过 MiddlewareRegistry 组装默认栈与路由级细化（跳过/追加/参数）。
  • 路由风格配置：config/route.php 定义多种 URL 风格与规则，支持命名参数、正则约束、可选段、短地址模块等。

章节来源

  • front/foundation/routing/FrontResolver.php:32-106
  • admin/foundation/routing/AdminResolver.php:30-104
  • api/foundation/routing/ApiResolver.php:30-91
  • config/route.php:15-356

架构总览

三端路由共享统一的调度与中间件基础设施，但在匹配策略与中间件栈上有所区分：

  • 前台：外观 URL → PrettyRouteMatcher → FrontResolver → 中间件栈（安全头、可信代理、限流、用户认证、CSRF）→ 控制器。
  • 后台：?route=... → BackendDeclaredMatcher → AdminResolver → 中间件栈（安全头、可信代理、认证、权限、CSRF、工作区）→ 控制器。
  • API：?route=... → BackendDeclaredMatcher → ApiResolver → 中间件栈（安全头、可信代理、限流、用户认证）→ 控制器。
sequenceDiagram
participant Client as "客户端"
participant Entry as "根入口 index.php"
participant Boot as "核心引导 bootstrap.php"
participant FR as "前台Router"
participant AR as "后台Router"
participant AAR as "API Router"
participant Disp as "中央Dispatcher"
participant Ctrl as "控制器"
Client->>Entry : "HTTP 请求"
Entry->>Boot : "加载引导与容器"
alt 前台请求
Entry->>FR : "dispatch()"
FR->>FR : "FrontResolver : : resolve()"
FR->>Disp : "运行中间件管道"
Disp-->>FR : "Response 或 null"
FR-->>Client : "发送响应"
else 后台请求
Entry->>AR : "dispatch()"
AR->>AR : "AdminResolver : : resolve()"
AR->>Disp : "运行中间件管道"
Disp-->>AR : "Response 或 null"
AR-->>Client : "发送响应"
else API请求
Entry->>AAR : "dispatch()"
AAR->>AAR : "ApiResolver : : resolve()"
AAR->>Disp : "运行中间件管道"
Disp-->>AAR : "Response 或 null"
AAR-->>Client : "发送响应"
end

图表来源

  • index.php:26-41
  • front/foundation/routing/Router.php:40-58
  • admin/foundation/routing/Router.php:41-66
  • api/foundation/routing/Router.php:43-70

详细组件分析

前台路由系统

  • 入口预处理：LangPrefixParser 剥离语言前缀并写入 Request 的语言标记与路由字符串。
  • 匹配流程：FrontResolver 调用 PrettyRouteMatcher 进行外观 URL 匹配，得到 module/action/sub/controller 及 params。
  • 参数注入：将路由参数设置到 Request 的路由袋并合并输入，便于控制器获取。
  • 中间件装配：默认栈包含安全头、可信代理、限流、用户认证（可选）、CSRF；可通过路由条目进行跳过/追加/参数覆盖。
  • 主题扩展：在控制器执行前加载主题包扩展文件。
flowchart TD
Start(["前台入口"]) --> Parse["LangPrefixParser 解析语言前缀"]
Parse --> Match["PrettyRouteMatcher 匹配外观URL"]
Match --> |命中| BuildPlan["FrontResolver 构建DispatchPlan"]
Match --> |未命中| NotFound["返回404或page_wrong提示"]
BuildPlan --> MW["组装中间件链"]
MW --> Inject["注入路由参数到Request"]
Inject --> Theme["加载主题扩展"]
Theme --> Dispatch["Dispatcher 执行中间件与控制器"]
Dispatch --> End(["输出响应"])

图表来源

  • index.php:28-34
  • front/foundation/routing/FrontResolver.php:52-106
  • front/foundation/routing/FrontResolver.php:159-199

章节来源

  • index.php:28-41
  • front/foundation/routing/FrontResolver.php:52-106
  • front/foundation/routing/FrontResolver.php:159-199

后台路由系统

  • 入口格式：以 ?route=module[/id[/action]] 形式进入。
  • 匹配流程：AdminResolver 使用 BackendDeclaredMatcher 按 admin/route/*.php 声明条目匹配，考虑 specificity 与 HTTP 方法。
  • 中间件分层：默认栈包含安全头、可信代理、认证、权限、CSRF、工作区；可经路由条目细化。
  • 表单目标装配：create/edit 动作自动装配 form_action 与 form_method，简化模板编写。
sequenceDiagram
participant Client as "客户端"
participant AR as "后台Router"
participant AMR as "AdminResolver"
participant DM as "BackendDeclaredMatcher"
participant MW as "中间件栈"
participant Ctrl as "控制器"
Client->>AR : "?route=..."
AR->>AMR : "resolve(request, container)"
AMR->>DM : "match(routeRaw, 'Admin', method)"
DM-->>AMR : "命中条目/方法不允许/未命中"
AMR->>MW : "compose默认栈+路由级细化"
MW->>Ctrl : "执行控制器方法"
Ctrl-->>AR : "Response 或 null"
AR-->>Client : "发送响应"

图表来源

  • admin/foundation/routing/Router.php:41-66
  • admin/foundation/routing/AdminResolver.php:72-104

章节来源

  • admin/foundation/routing/Router.php:26-66
  • admin/foundation/routing/AdminResolver.php:30-104

API路由系统

  • 入口格式：与后台一致，以 ?route=module[/id[/action]] 形式进入。
  • 匹配流程：ApiResolver 使用 BackendDeclaredMatcher 按 api/route/*.php 声明条目匹配。
  • 中间件分层：默认栈包含安全头、可信代理、限流、用户认证（可选）；未匹配返回 JSON 404，方法不允许返回 JSON 405。
  • 响应规范：统一通过 ApiResponse 输出结构化错误信息。
sequenceDiagram
participant Client as "客户端"
participant AR as "API Router"
participant AMR as "ApiResolver"
participant DM as "BackendDeclaredMatcher"
participant MW as "中间件栈"
participant Ctrl as "控制器"
Client->>AR : "POST /api/index.php?route=..."
AR->>AMR : "resolve(request, container)"
AMR->>DM : "match(routeRaw, 'Api', method)"
DM-->>AMR : "命中条目/方法不允许/未命中"
AMR->>MW : "compose默认栈+路由级细化"
MW->>Ctrl : "执行控制器方法"
Ctrl-->>AR : "Response 或 null"
AR-->>Client : "JSON 响应"

图表来源

  • api/foundation/routing/Router.php:43-70
  • api/foundation/routing/ApiResolver.php:60-91

章节来源

  • api/foundation/routing/Router.php:28-70
  • api/foundation/routing/ApiResolver.php:30-109

路由风格与匹配规则

  • 风格分组：config/rule.php 定义了 page、column、simple 三类风格，每类包含多条规则。
  • 规则字段：pattern（URL 模式）、params（参数默认正则）、target（目标文件名模板）、module_fixed（固定模块名）、short_rules（短地址模块专用规则家族）。
  • 语法支持：{param}、{param:regex}、[/optional] 等；分页段 o{page:\d*} 用于列表分页。
  • 优先级与选择：前台通过 PrettyRouteMatcher 按规则顺序与 specificity 匹配；后台/API 通过 BackendDeclaredMatcher 按声明条目 specificity 与 HTTP 方法过滤。
flowchart TD
Start(["接收URL"]) --> Style["选择风格(page/column/simple)"]
Style --> Rules["遍历规则(pattern/params/target/module_fixed)"]
Rules --> Match{"匹配成功?"}
Match --> |是| Params["提取命名参数与正则校验"]
Match --> |否| NextRule["尝试下一条规则"]
Params --> Target["确定目标模块/动作/控制器"]
Target --> ShortRules{"是否短地址模块?"}
ShortRules --> |是| ApplyShort["应用short_rules家族"]
ShortRules --> |否| Done["完成匹配"]
ApplyShort --> Done

图表来源

  • config/route.php:15-356

章节来源

  • config/route.php:15-356

依赖关系分析

  • 入口与引导：index.php 依赖 core/bootstrap.php 完成容器、门面、Request 与 DelegatingRouter 的初始化。
  • 三端调度器：各自 Router 依赖对应 Resolver，Resolver 依赖匹配器与中间件注册表。
  • 匹配器：前台依赖 PrettyRouteMatcher 与 config/route.php；后台/API 依赖 BackendDeclaredMatcher 与各自 route/*.php 声明。
  • 中间件：各 Resolver 通过 MiddlewareRegistry 组合默认栈与路由级细化，确保 secure-by-default。
graph LR
Index["index.php"] --> Bootstrap["core/bootstrap.php"]
Bootstrap --> FR["front/foundation/routing/Router.php"]
Bootstrap --> AR["admin/foundation/routing/Router.php"]
Bootstrap --> AAR["api/foundation/routing/Router.php"]
FR --> FRs["front/foundation/routing/FrontResolver.php"]
AR --> ARs["admin/foundation/routing/AdminResolver.php"]
AAR --> AARs["api/foundation/routing/ApiResolver.php"]
FRs --> PM["front/foundation/routing/PrettyRouteMatcher.php"]
ARs --> BM["BackendDeclaredMatcher"]
AARs --> BM
PM --> CR["config/route.php"]

图表来源

  • index.php:16-41
  • core/bootstrap.php:144-165
  • front/foundation/routing/FrontResolver.php:52-106
  • admin/foundation/routing/AdminResolver.php:72-104
  • api/foundation/routing/ApiResolver.php:60-91

章节来源

  • index.php:16-41
  • core/bootstrap.php:144-165

性能考量

  • 匹配效率：前台使用 PrettyRouteMatcher 进行外观 URL 匹配，规则应尽量具体以减少回溯；后台/API 使用 BackendDeclaredMatcher 按 specificity 排序，优先匹配更具体的条目。
  • 中间件开销：默认栈已最小化必要检查，避免重复计算；按需启用用户认证与限流。
  • 参数注入：路由参数直接注入 Request 路由袋，减少超全局访问与额外解析。
  • 主题扩展：仅在控制器执行前加载，避免不必要的 I/O。
  • 建议：
    • 将高频访问的路由规则置于前面，提高命中率。
    • 合理使用短地址模块规则家族，减少复杂正则。
    • 在 API 中开启限流与缓存策略，降低重复请求压力。

故障排查指南

  • 未匹配路由：
    • 前台：FrontResolver 记录警告日志，返回 404 或 page_wrong 提示。
    • 后台：AdminResolver 返回 notFound，Router 重定向至首页并携带错误提示。
    • API：ApiResolver 返回 JSON 404。
  • 方法不允许：
    • 后台：返回 405 并重定向，附带 Allow 头。
    • API：返回 JSON 405，附带 allow 字段。
  • 未捕获异常：
    • 根入口根据 site.debug 与请求类型输出调试页或 JSON 500，并记录错误日志。
  • 调试建议：
    • 开启站点调试模式，查看异常堆栈与请求上下文。
    • 检查路由声明条目的 specificity 与 HTTP 方法是否正确。
    • 确认中间件栈是否按预期装配，必要时通过路由级 withoutMiddleware 排除干扰。

章节来源

  • front/foundation/routing/FrontResolver.php:58-67
  • admin/foundation/routing/Router.php:47-56
  • api/foundation/routing/Router.php:49-60
  • index.php:46-75

结论

DouPHP 的路由系统通过“外观 URL 匹配 + 声明式条目匹配”的双轨机制，实现了前台、后台、API 三端的清晰分离与统一调度。路由风格配置灵活可扩展，中间件栈遵循 secure-by-default 原则，参数注入与表单目标装配简化了业务开发。通过合理的规则组织与中间件配置，可在保证安全性的同时获得良好的性能与可维护性。

附录

路由配置示例与最佳实践

  • 前台外观 URL：
    • 单页面：{slug}.html 或 page/{slug}，module_fixed 为 page。
    • 栏目模块：支持分类别名嵌套、ID 后缀、日期归档等多种风格。
    • 简单模块：支持 class/{class}、{action}/{sub_action} 等。
  • 后台/API 声明式路由：
    • 在 admin/route/.php 或 api/route/.php 中声明条目，指定 URL pattern、HTTP 方法与控制器方法。
    • 利用 specificity 排序确保精确匹配，避免歧义。
  • 最佳实践：
    • 使用命名参数与正则约束，确保参数合法性。
    • 合理划分模块与动作，保持路由可读性与可维护性。
    • 通过路由级 withoutMiddleware 豁免敏感接口（如支付回调）的 CSRF 检查。

章节来源

  • config/route.php:38-356

中间件集成方式

  • 前台默认栈：安全头 -> 可信代理 -> 限流 -> 用户认证（可选）-> CSRF。
  • 后台默认栈：安全头 -> 可信代理 -> 认证 -> 权限 -> CSRF -> 工作区。
  • API 默认栈：安全头 -> 可信代理 -> 限流 -> 用户认证（可选）。
  • 路由级细化：
    • skip_all：跳过所有默认中间件。
    • without：跳过指定中间件。
    • append：追加中间件。
    • params：传递中间件参数。

章节来源

  • front/foundation/routing/FrontResolver.php:159-199
  • admin/foundation/routing/AdminResolver.php:45-63
  • api/foundation/routing/ApiResolver.php:42-51

路由约束与验证机制

  • 参数类型检查：通过 pattern 中的 {param:regex} 与 params 默认正则进行约束。
  • 权限验证：后台通过 PermissionMiddleware 进行权限检查。
  • 格式校验：CSRF 中间件保护 POST/PUT/DELETE 等写操作；限流中间件防止滥用。
  • 会员模块闸：Module::assertUserAvailable 在 features.user 关闭时阻止访问 user 模块相关路由。

章节来源

  • config/route.php:21-30
  • admin/foundation/routing/AdminResolver.php:88-90
  • api/foundation/routing/ApiResolver.php:77-79

自定义路由器与高级配置

  • 自定义前台匹配器：可替换 PrettyRouteMatcher 的实现，扩展外观 URL 匹配逻辑。
  • 自定义声明式匹配：可调整 BackendDeclaredMatcher 的行为，增加新的匹配策略。
  • 高级中间件：通过 MiddlewareRegistry 注册自定义中间件别名，并在默认栈或路由级细化中使用。
  • 路由风格扩展：在 config/route.php 中添加新风格与规则家族，支持短地址模块与嵌套分类。

章节来源

  • front/foundation/routing/FrontResolver.php:32-43
  • admin/foundation/routing/AdminResolver.php:30-41
  • api/foundation/routing/ApiResolver.php:30-38
  • config/route.php:15-30
添加日期：2026-10-05