简介

本文件系统性说明 DouPHP 框架的“模块生命周期管理”，覆盖从进程启动、应用初始化、路由分发、中间件管道执行到响应输出与异常处理的完整流程；并解释前台、后台、API 三个入口在生命周期上的差异与共性。同时，文档阐述事件系统（监听器注册与触发）、场景分发机制、状态管理与错误处理策略，以及生命周期扩展点的使用方法与自定义钩子的开发指南，重点说明生命周期如何与请求处理管道集成。

项目结构

DouPHP 采用三端分离的入口设计：前台 index.php、后台 admin/index.php、API 入口 api/index.php，三者均通过 core/bootstrap.php 完成基础环境准备（常量定义、配置加载、自动加载、容器与 Request 单例绑定等），随后调用各自 Init::boot 完成端侧初始化，再进入路由分发与响应输出。

graph TB
A["HTTP 请求"] --> B["前端入口 index.php"]
A --> C["后台入口 admin/index.php"]
A --> D["API 入口 api/index.php"]
B --> E["core/bootstrap.php"]
C --> E
D --> E
E --> F["各端 Init::boot()"]
F --> G["Route::dispatch()"]
G --> H["中间件管道 MiddlewarePipeline"]
H --> I["控制器动作 / 业务逻辑"]
I --> J["Response 发送 / 退出"]

核心组件

• 引导与容器：core/bootstrap.php 负责 PHP 版本检查、路径常量、配置加载、自动加载、别名注册、DI 容器实例化、Request 单例绑定、助手函数加载、事件注册器登记等。
• 三端初始化：
  • 前台：index.php 设置语言前缀解析后调用 Front\Init\Init()->boot(Route::current())，然后 Route::dispatch()。
  • 后台：admin/index.php 设置 route 字符串后调用 Admin\Init\Init()->boot()，然后 Route::dispatch()。
  • API：api/index.php 设置 route 字符串后调用 Api\Init\Init()->boot()，然后 Route::dispatch()。
• 路由与调度：Dispatcher 将路由参数注入 Request，构建中间件管道，最终调用控制器方法。
• 中间件管道：MiddlewarePipeline 以链式方式组合多个中间件，最后执行控制器动作。
• 事件系统：Event 提供 listen/fire/dispatch/hasListeners；SceneRegistry 提供场景处理器工厂注册与延迟引导，支持按 key 单播或扇出。

架构总览

下图展示一次典型请求的生命周期：入口 -> 引导 -> 端初始化 -> 路由分发 -> 中间件管道 -> 控制器 -> 响应输出。异常在各入口被捕获并按端特性返回 JSON 或提示页。

sequenceDiagram
participant Client as "客户端"
participant Entry as "入口 index.php"
participant Boot as "core/bootstrap.php"
participant Init as "端 Init : : boot()"
participant Router as "Route : : dispatch()"
participant Pipe as "中间件管道"
participant Ctrl as "控制器动作"
participant Resp as "Response"
Client->>Entry : HTTP 请求
Entry->>Boot : 加载引导
Boot-->>Entry : 容器/Request/助手就绪
Entry->>Init : 调用 Init : : boot()
Init-->>Router : 初始化完成
Router->>Pipe : 构建并运行中间件管道
Pipe->>Ctrl : 调用控制器方法
Ctrl-->>Resp : 生成 Response
Resp-->>Client : 发送响应并退出

详细组件分析

入口与引导阶段

• 前台入口：
  • 设置路由委托为前端 Router。
  • 解析语言前缀，写入 Request 的 langSign 与 routeString，并从超全局移除 route。
  • 调用 Front\Init\Init()->boot(Route::current())，随后 Route::dispatch()。
  • 统一异常处理：HttpResponseException、RedirectException、DomainException、通用 Exception/Throwable，分别输出 Response、重定向、业务错误提示或调试页/JSON。
• 后台入口：
  • 设置路由委托为后台 Router。
  • 写入 route 字符串并清理超全局。
  • 调用 Admin\Init\Init()->boot()，随后 Route::dispatch()。
  • 异常处理：对特定 AI 接口返回 JSON 错误，其他走 message 提示或调试页。
• API 入口：
  • 设置路由委托为 API Router。
  • 写入 route 字符串并清理超全局。
  • 调用 Api\Init\Init()->boot()，随后 Route::dispatch()。
  • 异常处理：统一 ApiResponse JSON 错误，开启站点调试时输出调试 JSON。

端初始化阶段（Admin 与 API）

• 后台 Init::boot：
  • 启动会话、错误报告、时区、定义后台常量。
  • 核心对象实例化、视图引擎装配、模块加载（含语言包、功能开关、主题、工作区等）。
  • 授权检测、服务注册（插件、导航、缓存清理等）。
  • 模板变量填充（site、param、features、workspace、更新角标等）。
• API Init::boot：
  • 公共初始化（会话、错误报告、时区、API 常量、根 URL、自定义文件加载）。
  • 核心对象实例化、Provider 注册、语言契约、站点信息、参数加载。
  • 模块与语言加载、授权检测、API Guard 注册（GuestGuard 或真实 Auth）。
  • 站点关闭检测（503 JSON 响应）。

路由与中间件管道

• Dispatcher：
  • 将路由参数注入 Request（确保中间件与控制器均可读取）。
  • 使用 MiddlewarePipeline 组装中间件链，最终调用容器解析的控制器方法。
• MiddlewarePipeline：
  • 以反向累积的方式构建调用链，依次执行中间件的 handle(next)。
• AbstractSecurityHeadersMiddleware：
  • 在管道最前置下发基线安全头（X-Content-Type-Options、X-Frame-Options、Referrer-Policy、Permissions-Policy），HTTPS 且配置开启时附加 HSTS。

flowchart TD
Start(["请求进入"]) --> R["路由匹配<br/>Dispatcher"]
R --> P["构建中间件管道<br/>MiddlewarePipeline"]
P --> M1["安全头中间件<br/>AbstractSecurityHeadersMiddleware"]
M1 --> M2["其他中间件..."]
M2 --> C["控制器动作"]
C --> O["生成 Response"]
O --> End(["发送响应并退出"])

事件系统与场景分发

• 事件系统 Event：
  • 提供静态方法 listen(event, listener, priority)、fire(event, ...params)、dispatch(event, ...params)、hasListeners(event)。
  • 监听器按优先级排序执行，fire 返回每个监听器的结果数组。
• 场景分发 SceneRegistry：
  • register(scene, key, factory) 注册场景处理器工厂。
  • addBootstrapper(bootstrapperClass) 延迟注册，首次 dispatch 时执行 bootstrapper 的 register。
  • dispatch(scene, payload, key='') 支持单播（指定 key）或扇出（所有处理器）。
  • ensureBooted 保证仅引导一次，避免重复注册。

classDiagram
class Event {
+static listen(event, listener, priority) void
+static fire(event, ...params) array
+static dispatch(event, ...params) array
+static hasListeners(event) bool
}
class SceneRegistry {
+static register(scene, key, factory) void
+static addBootstrapper(class) void
+static dispatch(scene, payload, key) void
+static reset() void
-static ensureBooted() void
-static invokeHandler(factory, scene, payload) void
}
Event <.. SceneRegistry : "事件驱动场景"

生命周期扩展点与自定义钩子

• 扩展点位置：
  • 引导阶段：core/bootstrap.php 中可注册事件监听器与场景注册器（如 OrderPaidSceneRegistrar）。
  • 端初始化阶段：Admin\Init\Init 与 Api\Init\Init 中 ProviderRegistry 注册、模块加载、语言与参数加载、授权检测等。
  • 路由阶段：Dispatcher 在中间件管道前后可扩展日志、审计、限流等。
  • 响应阶段：各入口统一异常处理与响应输出，可在中间件中追加响应头或拦截响应。
• 自定义钩子开发指南：
  • 事件监听：使用 Event::listen('your.event', $callback, $priority) 注册监听器，在合适时机 Event::fire('your.event', ...$params) 触发。
  • 场景处理器：实现 SceneHandler 并通过 SceneRegistry::register('scene', 'key', function(){ return new YourHandler(); }) 注册；如需延迟注册，使用 addBootstrapper 并在其 register 中完成注册。
  • 中间件扩展：实现 MiddlewareInterface，编写 handle($next) 逻辑，加入管道即可在请求处理前后插入横切关注点。

状态管理与错误处理策略

• 状态管理：
  • 会话：各端 Init::boot 启动 Session，用于用户态、临时数据、排序偏好等。
  • 配置：Config 集中管理 site、module、system、features、param、defined 等，模块加载后刷新。
  • 语言：根据 features.language 与模块可用性动态解析语言契约，必要时重新注册 Provider。
• 错误处理：
  • 前台：DomainException 按 JSON 或 message 提示；未捕获异常按站点调试模式输出 HTML/JSON 或回退 page_wrong。
  • 后台：AI 相关接口返回 JSON 错误；其他走 message 提示或调试页。
  • API：统一 ApiResponse 错误码；站点调试时输出调试 JSON；站点关闭返回 503。

依赖关系分析

• 入口与引导：
  • 三端入口均依赖 core/bootstrap.php 提供的常量、配置、自动加载、容器、Request 单例与助手。
• 路由与调度：
  • Dispatcher 依赖 Container 解析控制器，依赖 MiddlewarePipeline 组合中间件。
• 中间件：
  • AbstractSecurityHeadersMiddleware 依赖 Config 获取安全头配置，作用于已匹配路由。
• 事件与场景：
  • bootstrap.php 注册场景注册器；SceneRegistry 在首次 dispatch 时引导；Event 提供轻量事件机制。

graph LR
Bootstrap["core/bootstrap.php"] --> Entr["三端入口"]
Entr --> Init["端 Init::boot()"]
Init --> Router["Route::dispatch()"]
Router --> Disp["Dispatcher"]
Disp --> Pipe["MiddlewarePipeline"]
Pipe --> MW["中间件(如安全头)"]
MW --> Ctrl["控制器"]
Ctrl --> Resp["Response"]
Bootstrap --> Events["事件/场景注册器"]
Events --> Registry["SceneRegistry"]

性能考量

• 引导阶段一次性加载配置与模块映射，减少重复 IO。
• 场景注册器延迟引导，仅在首次 dispatch 时执行，降低冷启动开销。
• 中间件管道顺序优化：安全头在最前置，避免后续逻辑重复计算。
• 事件监听器按优先级排序，避免频繁 re-sort。
• 建议：
  • 将昂贵初始化放入懒加载或按需触发（如场景处理器工厂）。
  • 合理使用缓存（模板编译、语言包、路由清单）。
  • 控制中间件数量与复杂度，避免阻塞关键路径。

故障排查指南

• 前台异常：
  • DomainException：JSON 请求返回 422 业务规则错误；HTML 请求走 message 提示。
  • 未捕获异常：站点调试开启时输出调试页/JSON；否则回退 page_wrong。
• 后台异常：
  • AI 相关接口：返回 JSON 错误，便于前端处理。
  • 其他：message 提示或调试页。
• API 异常：
  • 统一 ApiResponse 错误码；站点调试时输出调试 JSON；站点关闭返回 503。
• 常见问题定位：
  • 确认入口是否正确设置路由委托与 route 字符串。
  • 检查 Init::boot 是否成功完成（会话、配置、语言、模块）。
  • 验证中间件是否提前终止或抛出异常。
  • 事件/场景是否正确注册与触发。

结论

DouPHP 的模块生命周期以“引导 -> 端初始化 -> 路由分发 -> 中间件管道 -> 控制器 -> 响应”为主线，三端入口共享核心引导但各自维护独立的初始化流程与错误处理策略。事件系统与场景分发提供了灵活的扩展点，结合中间件管道可实现横切关注点的统一治理。通过合理的状态管理与错误处理，框架在保证稳定性的同时具备良好的可扩展性与可维护性。

附录：扩展与自定义钩子开发指南

• 在引导阶段注册事件监听器：
  • 使用 Event::listen('event.name', $callback, $priority) 注册。
  • 在业务关键点调用 Event::fire('event.name', ...$params) 触发。
• 使用场景分发：
  • 实现 SceneHandler 并在 SceneRegistry::register('scene', 'key', $factory) 注册。
  • 通过 addBootstrapper 延迟注册，确保 Config 就绪后再执行。
• 中间件扩展：
  • 实现 MiddlewareInterface，编写 handle($next) 逻辑。
  • 在路由或端初始化中注册中间件，加入管道。
• 最佳实践：
  • 保持钩子幂等与轻量，避免阻塞主流程。
  • 明确优先级与执行顺序，避免副作用冲突。
  • 记录日志与异常，便于问题追踪。