架构设计 | DouPHP 开发手册 | 文档中心 | DouPHP企业建站系统

架构设计

简介

本架构设计文档面向 DouPHP 框架，系统性阐述其 MVC 分层、模块化与插件化设计，以及前台、后台、API 三端应用的统一路由与差异化处理。文档覆盖组件交互、数据流向、集成模式、技术决策与权衡、基础设施要求、可扩展性与部署拓扑，并给出系统上下文图与组件分解图，帮助读者快速理解与扩展该框架。

项目结构

DouPHP 采用“入口 + 核心 + 应用”的分层组织方式：

根入口 index.php 负责全局引导、异常兜底与前台路由委派。
core/bootstrap.php 完成环境检测、路径常量定义、配置加载、自动加载、DI 容器初始化、Request/Route 等核心对象绑定。
三个应用入口分别位于 front（前台）、admin（后台）、api（API），各自拥有独立的 Init、路由解析器、中间件与视图/响应策略。
config 集中管理数据库、模块、路由风格与安全等配置。
plugin 提供支付、物流、登录等插件式能力。
theme/miniprogram 提供前端主题与小程序资源。

graph TB
A["根入口<br/>index.php"] --> B["核心引导<br/>core/bootstrap.php"]
B --> C["前台入口<br/>front/index.php"]
B --> D["后台入口<br/>admin/index.php"]
B --> E["API入口<br/>api/index.php"]
C --> F["前台路由调度<br/>front/foundation/routing/Router.php"]
D --> G["后台路由调度<br/>admin/foundation/routing/Router.php"]
E --> H["API路由调度<br/>api/foundation/routing/Router.php"]
B --> I["配置中心<br/>config/*.php"]
B --> J["DI容器<br/>core/foundation/container/Container.php"]

核心组件

引导与生命周期：bootstrap.php 统一完成 PHP 版本检查、路径常量、安装态判断、配置加载、自动加载、别名注册、DI 容器初始化、Request/Route 早绑定、助手函数加载与事件场景注册。
请求与响应：Request 在 bootstrap 阶段捕获超全局；Response/JsonResponse/ApiResponse 在各入口根据请求类型输出。
路由系统：三端各自 Router 薄壳将请求交由 Resolver 生成 DispatchPlan，再由中央 Dispatcher 执行中间件管道与控制器。
DI 容器：轻量级容器支持 bind/singleton/factory/instance/alias/contextual binding，反射自动注入依赖，构建栈追踪错误链。
中间件：前台安全头、后台认证与权限、API 用户鉴权与限流等。
配置与模块：module.php 声明栏目/单页模块集合；route.php 提供多套 URL 风格规则（含短地址族）。

架构总览

DouPHP 采用“统一内核 + 多端应用”的架构：

统一内核：bootstrap、容器、ORM、文件系统、事件、消息、视图、HTTP 基础能力。
多端应用：前台（Web 页面）、后台（管理控制台）、API（JSON 接口）共享内核但隔离路由、中间件、视图与响应策略。
模块化：通过 module.php 声明业务模块集合，配合路由风格与模板体系实现功能解耦。
插件化：plugin 目录按支付/物流/登录等能力拆分，遵循约定接入内核服务。

graph TB
subgraph "内核"
K1["引导<br/>bootstrap.php"]
K2["容器<br/>Container.php"]
K3["HTTP基础<br/>Request/Response"]
K4["ORM/存储/事件"]
end
subgraph "前台"
F1["Init/路由/中间件"]
F2["控制器/服务/模型"]
F3["视图/模板"]
end
subgraph "后台"
A1["Init/路由/中间件"]
A2["控制器/服务/模型"]
A3["管理视图"]
end
subgraph "API"
R1["Init/路由/中间件"]
R2["控制器/服务/模型"]
R3["JSON响应"]
end
K1 --> F1; K1 --> A1; K1 --> R1
K2 --> F1; K2 --> A1; K2 --> R1
K3 --> F1; K3 --> A1; K3 --> R1
K4 --> F2; K4 --> A2; K4 --> R2
F1 --> F2 --> F3
A1 --> A2 --> A3
R1 --> R2 --> R3

详细组件分析

入口与引导流程

根入口 index.php：设置 IN_DOUCO，引入 bootstrap，委派前台路由，预处理语言前缀到 Request，启动 Init，调度 Route，统一异常处理（业务域异常、重定向、未捕获异常 JSON/HTML 渲染）。
核心引导 bootstrap.php：版本检测、路径常量、安装态跳转、配置加载、自动加载、别名注册、DI 容器初始化、Request/DelegatingRouter 早绑定、助手加载、邮件事件与场景注册。
后台入口 admin/index.php：委派后台路由，写入 route 参数，启动 Admin Init，统一异常处理（JSON/AJAX 友好）。
API 入口 api/index.php：委派 API 路由，写入 route 参数，启动 Api Init，统一异常处理（始终 JSON）。

sequenceDiagram
participant U as "客户端"
participant IDX as "根入口<br/>index.php"
participant BS as "核心引导<br/>bootstrap.php"
participant FR as "前台路由<br/>front Router"
participant AD as "后台路由<br/>admin Router"
participant AP as "API路由<br/>api Router"
U->>IDX : HTTP请求
IDX->>BS : 加载引导
BS-->>IDX : 完成容器/Request/Route绑定
IDX->>FR : setDelegate(前台Router)
IDX->>FR : dispatch()
alt 匹配前台
FR-->>U : HTML/JSON响应
else 进入后台
IDX->>AD : setDelegate(后台Router)
AD-->>U : 管理界面响应
else 进入API
IDX->>AP : setDelegate(API Router)
AP-->>U : JSON响应
end

路由系统与统一设计

统一思想：三端 Router 均为薄壳，仅负责解析为 DispatchPlan 并交给中央 Dispatcher 执行中间件管道；参数通过 Request 独立路由袋注入，不污染超全局。
前台 Router：剥离语言前缀后解析，未命中返回 page_wrong。
后台 Router：未命中或方法不允许时重定向至后台首页并携带提示。
API Router：未命中或方法不允许时返回标准 JSON 404/405。
路由风格：config/route.php 提供 PAGE/COLUMN/SIMPLE 等多套规则，支持命名参数、可选段、分页段、短地址族等。
模块映射：config/module.php 声明 column_module/single_module 等集合，供路由与菜单/导航生成复用。

flowchart TD
Start["接收请求"] --> Parse["解析route字符串<br/>LangPrefixParser/入口写入"]
Parse --> Resolve{"Resolver匹配?"}
Resolve --> |否| NotFound["404/重定向/提示"]
Resolve --> |是| Plan["生成DispatchPlan"]
Plan --> MW["中间件管道执行"]
MW --> Controller["控制器/服务处理"]
Controller --> Response{"是否返回Response?"}
Response --> |是| Send["发送响应"]
Response --> |否| Continue["继续后续逻辑"]
NotFound --> End["结束"]
Send --> End
Continue --> End

中间件与横切关注点

前台安全头：SecurityHeadersMiddleware 继承抽象基类，统一设置安全响应头。
后台认证：AuthMiddleware 从会话恢复管理员身份，未登录抛 HttpResponseException 跳转登录页；免登路由通过路由级 withoutMiddleware 豁免。
API 用户鉴权：UserAuthMiddleware 基于 AbstractUserAuthMiddleware，从 Authorization 头提取 token，解析用户上下文并注入；拒绝时直接返回 JSON 401/403。
其他：后台还包含权限、CSRF、工作区等中间件；API 包含限流中间件。

classDiagram
class SecurityHeadersMiddleware {
+handle(next) mixed
}
class AuthMiddleware {
+handle(next) mixed
}
class UserAuthMiddleware {
+resolveContext() array
+inject(context) void
+rejectUnauthenticated() void
+rejectForbidden() void
}
class AbstractUserAuthMiddleware {
<<abstract>>
+handle(next) mixed
}
UserAuthMiddleware --|> AbstractUserAuthMiddleware : "继承"
SecurityHeadersMiddleware <.. AbstractUserAuthMiddleware : "同属中间件体系"

数据访问与服务层

ORM/数据库：由核心 ORM 与 DB Facade 提供，连接信息来自 bootstrap 收敛的 DOU_DB_CONFIG。
服务层：各模块 service 目录封装领域逻辑，控制器调用服务，模型负责数据映射。
存储：Storage Facade 统一文件/云存储抽象，便于扩展。

插件系统设计

插件目录 plugin 按能力划分（支付、物流、登录等），通过约定与内核服务对接。
模块配置 module.php 控制前台展示与后台菜单可见性，插件可据此暴露能力。
插件扩展点：可通过事件、中间件、路由、服务等方式接入，保持低耦合。

依赖关系分析

入口依赖：index.php 依赖 bootstrap 与前台 Router；admin/api 入口依赖各自 Router。
引导依赖：bootstrap 依赖配置、自动加载、容器、Request/Route 绑定。
路由依赖：各 Router 依赖 Container、Request、Dispatcher 及对应 Resolver。
中间件依赖：各中间件依赖核心中间件接口与 HTTP 工具。
容器依赖：Container 被路由、中间件、服务广泛使用，作为依赖注入中枢。

graph LR
IDX["index.php"] --> BS["bootstrap.php"]
BS --> CT["Container.php"]
IDX --> FR["front Router"]
IDX --> AD["admin Router"]
IDX --> AP["api Router"]
FR --> DIS["Dispatcher"]
AD --> DIS
AP --> DIS
FR --> REQ["Request"]
AD --> REQ
AP --> REQ
AD --> MW_A["Admin Middleware"]
AP --> MW_R["Api Middleware"]
FR --> MW_F["Front Middleware"]

性能与可扩展性

性能要点
- 引导阶段一次性加载配置与自动加载，减少重复 IO。
- Request/Route 在引导期早绑定，避免重复捕获与构造。
- 路由解析产出 DispatchPlan 后统一走 Dispatcher 管道，减少分支复杂度。
- 容器支持工厂与单例，按需创建与缓存实例，降低开销。
可扩展性
- 模块化：通过 module.php 声明模块集合，新增模块只需遵循约定目录结构与路由风格。
- 插件化：plugin 目录按能力拆分，通过事件/中间件/服务接入，不影响主流程。
- 路由风格：route.php 支持多套规则与短地址族，便于 SEO 与历史兼容。
- 中间件：按端定制，易于横向扩展安全、限流、审计等功能。

横切关注点：安全、监控与灾难恢复

安全性
- 前台安全头中间件统一设置响应头，降低常见攻击面。
- 后台认证中间件基于会话恢复登录态，未登录强制跳转。
- API 鉴权中间件基于 token 解析用户上下文，拒绝时返回标准 JSON 错误码。
- 入口对 route 参数进行清洗，避免直接读取超全局。
监控
- 各入口统一记录未捕获异常到 error_log，便于日志采集。
- 调试模式下输出结构化调试信息（HTML/JSON），生产模式回退到友好提示。
灾难恢复
- 安装态检测：未安装时自动跳转到安装程序，防止非法访问。
- 异常兜底：DomainException/HttpResponseException/RedirectException 分类处理，确保稳定降级。
- 配置与存储分离：config 与 storage 目录分离，便于备份与迁移。

技术栈与兼容性

PHP 版本：最低要求 5.6.0，引导阶段进行版本检测。
运行时：基于 PHP Web 运行环境，依赖 HTTP 服务器（如 Nginx/Apache）进行 URL 重写与静态资源托管。
数据库：MySQL/MariaDB（通过配置项 host/user/pass/name/prefix 指定）。
存储：本地/云存储抽象（Storage Facade）。
模板：DWT 模板引擎（theme/miniprogram）。
第三方依赖：无外部包管理器依赖，核心自研；插件生态丰富。

部署拓扑与运维要点

部署拓扑
- Web 服务器（Nginx/Apache）指向站点根目录，启用 URL 重写以支持路由。
- 静态资源（images/css/js）由 Web 服务器直接服务。
- 数据库与缓存服务独立部署，通过配置连接。
运维要点
- 安装态：首次访问自动跳转安装程序，完成后生成 install.lock。
- 配置管理：config 目录集中管理，敏感信息建议环境变量或外部配置。
- 日志与监控：统一 error_log 输出，结合日志平台收集。
- 安全加固：限制 admin/api 目录访问，启用 HTTPS，设置安全头。
- 备份与恢复：定期备份 storage 与数据库，支持平滑升级。

故障排查指南

常见问题定位
- 未安装跳转：检查 storage/install.lock 是否存在。
- 路由 404：确认 route 字符串是否正确，Resolver 是否匹配，中间件是否拦截。
- 认证失败：检查会话状态、token 有效性、中间件配置。
- 异常输出：开启 site.debug 获取结构化调试信息；生产环境查看 error_log。
排查步骤
- 确认入口是否正确委派路由。
- 检查 Request 中 routeString 与 langSign 是否正确设置。
- 验证中间件管道顺序与豁免规则。
- 查看容器绑定与依赖注入链，定位缺失依赖。

结论

DouPHP 通过统一内核与多端应用实现了高内聚、低耦合的架构设计。MVC 分层清晰，模块化与插件化提升了扩展性；统一路由与中间件机制保障了三端一致的开发体验。结合严格的安全与异常处理、完善的配置与存储分离，框架具备良好的可维护性与可运维性。未来可在事件驱动、异步任务、分布式缓存等方面进一步增强，以满足更大规模的业务需求。

添加日期：2026-10-05