简介
本指南面向DouPHP的贡献者与新增开发者，目标是帮助你在最短时间内搭建本地开发环境、理解代码结构与命名约定、掌握添加功能与修改现有代码的流程、编写测试与进行调试、遵循版本控制与协作规范，并了解常见陷阱与性能分析方法。文档基于仓库中的入口文件、引导流程、自动加载与路由机制等源码进行分析与总结。
项目结构
DouPHP采用“三端分离 + 模块化”的架构：
- 前台（front）：面向用户访问的前端页面与业务逻辑
- 后台（admin）：管理后台界面与管理功能
- API（api）：对外提供JSON接口
- 核心（core）：框架基础能力（路由、容器、ORM、文件系统、中间件、异常处理等）
- 配置（config）：数据库、应用密钥、模块开关等
- 主题（theme/newtheme）：前端模板与静态资源
- 插件（plugin）：支付、登录等可插拔扩展
- 小程序（miniprogram）：小程序客户端代码
- 存储（storage）：运行时缓存与安装锁等
graph TB
A["请求入口<br/>index.php"] --> B["核心引导<br/>core/bootstrap.php"]
B --> C["自动加载器<br/>core/autoload.php"]
B --> D["配置中心<br/>config/config.php"]
A --> E["前台路由调度<br/>front/router"]
A --> F["后台路由调度<br/>admin/router"]
A --> G["API路由调度<br/>api/router"]
E --> H["控制器/服务/模型"]
F --> I["控制器/服务/模型"]
G --> J["控制器/服务/模型"]
H --> K["数据库/缓存/文件"]
I --> K
J --> K核心组件
- 入口与引导
- 根入口 index.php 负责定义常量、引入核心引导、设置路由委托、解析语言前缀、执行 Init::boot、分发路由并统一异常处理。
- 核心引导 core/bootstrap.php 完成PHP版本检查、路径常量定义、未安装跳转、配置文件加载、自动加载注册、别名注册、DI容器初始化、Request与路由委托绑定、全局助手加载等。
- 自动加载
- core/autoload.php 实现 Dou\ 命名空间的自动加载，支持插件类、Core类、端侧类（Admin/Front/Api）、Vendor适配类、Core模块映射与兜底映射。
- 配置
- config/config.php 集中数据库连接、字符集、系统标识、目录名、应用密钥与调试开关等。
- 三端入口
- admin/index.php、api/index.php 分别承担后台与API的引导、路由委托、异常处理与响应输出。
架构总览
DouPHP的请求生命周期从入口开始，经过引导、路由解析、中间件与控制器/服务处理，最终返回HTTP响应或JSON数据。异常在入口层统一捕获并按站点调试模式与请求类型输出不同格式。
sequenceDiagram
participant Client as "客户端"
participant Entry as "入口 index.php"
participant Boot as "核心引导 bootstrap.php"
participant Router as "路由调度 Route"
participant Handler as "控制器/服务"
participant DB as "数据库/存储"
Client->>Entry : HTTP请求
Entry->>Boot : 加载核心引导
Boot-->>Entry : 完成自动加载/别名/容器/Request绑定
Entry->>Router : setDelegate(端路由)
Entry->>Router : dispatch()
Router->>Handler : 匹配路由并调用
Handler->>DB : 读取/写入数据
DB-->>Handler : 结果
Handler-->>Router : Response/JsonResponse
Router-->>Entry : Response对象
Entry-->>Client : 发送响应详细组件分析
入口与引导流程
- 根入口 index.php
- 定义 IN_DOUCO 常量，引入 core/bootstrap.php。
- 设置前台路由委托为 Front\Foundation\Routing\Router。
- 解析 route 查询参数中的语言前缀并写入 Request，随后清理超全局。
- 执行 Front\Init\Init()->boot()，然后 Route::dispatch() 分发路由。
- 统一捕获 HttpResponseException、RedirectException、DomainException 与通用异常，按 JSON/HTML 与调试模式输出。
- 核心引导 core/bootstrap.php
- 检查PHP版本、定义ROOT_PATH/CONFIG_PATH/STORAGE_PATH等路径常量。
- 未安装时重定向到 install/index.php。
- 加载 config/config.php，定义DOU_MODULE_SETTING、DOU_DB_CONFIG等。
- 注册自动加载器、别名、DI容器、DelegatingRouter与Request单例。
- 加载全局助手（app/view/json/redirect/response）。
- 注册邮件事件监听与场景分发器。
flowchart TD
Start(["进程启动"]) --> CheckInstall["检测是否已安装"]
CheckInstall --> |未安装| RedirectInstall["重定向至安装程序"]
CheckInstall --> |已安装| LoadConfig["加载配置 config.php"]
LoadConfig --> DefinePaths["定义路径与协议常量"]
DefinePaths --> RegisterAutoload["注册自动加载与别名"]
RegisterAutoload --> InitContainer["初始化DI容器"]
InitContainer --> BindRouter["绑定路由委托与Request"]
BindRouter --> LoadHelpers["加载全局助手"]
LoadHelpers --> End(["引导完成"])自动加载与命名空间约定
- 自动加载优先级
- 插件类 Dou\Plugin* -> plugin//src/ 或 plugin/*
- Core类 Dou\Core* -> core/*
- 端侧类 Dou\Admin|Front|Api{Init|Lib|Middleware|Http|Controller|Model|Service|Request|Facade|Foundation}* -> 对应端目录
- Core模块映射 Dou\Core\Module* -> core/module/*
- Vendor适配 Dou\Vendor* -> core/library/{package}/...
- 兜底映射 core/*
- 端侧类文件解析规则
- Controller/Model/Service/Request/Facade/Foundation/Contract 等层按子命名空间映射到端目录同名子目录。
- Init/Lib/Middleware 为基础层，Init固定为 init/Init.php。
classDiagram
class AutoLoader {
+spl_autoload_register()
+douResolvePluginClassFile()
+douResolveEndpointClassFile()
+douResolveVendorClassFile()
}
class PluginClass {
<<Dou\\Plugin\\*>>
}
class CoreClass {
<<Dou\\Core\\*>>
}
class EndpointClass {
<<Dou\\{Admin|Front|Api}\\*>>
}
class VendorClass {
<<Dou\\Vendor\\*>>
}
AutoLoader --> PluginClass : "优先解析"
AutoLoader --> CoreClass : "Core动态解析"
AutoLoader --> EndpointClass : "端侧类解析"
AutoLoader --> VendorClass : "Vendor适配"路由与声明式路由
- 前台入口使用 LangPrefixParser 解析语言前缀，将 route 字符串写入 Request，再交由路由调度。
- 示例：设备模块 equipment 使用简单声明式路由，将 URL 段映射到 EquipmentController 的 index/show 方法。
- 路由规则工具 RouteRules 提供栏目详情pattern判断与默认配置合并能力。
sequenceDiagram
participant Client as "客户端"
participant FrontIndex as "前台入口 index.php"
participant Parser as "LangPrefixParser"
participant Router as "前台路由"
participant Controller as "EquipmentController"
Client->>FrontIndex : GET /equipment?route=...
FrontIndex->>Parser : 解析语言前缀
Parser-->>FrontIndex : 返回langSign与routeString
FrontIndex->>Router : dispatch()
Router->>Controller : 匹配simple路由并调用
Controller-->>Router : 返回响应
Router-->>Client : 发送响应后台与API入口差异
- 后台入口 admin/index.php
- 设置后台路由委托，解析 route 参数，执行 Admin\Init\Init()->boot()，统一捕获异常并按Ajax/HTML/调试模式输出。
- API入口 api/index.php
- 设置API路由委托，执行 Api\Init\Init()->boot()，统一捕获 DomainException 并返回标准错误码与消息；未捕获异常以JSON 500返回。
依赖关系分析
- 入口与引导
- index.php 依赖 core/bootstrap.php 完成环境准备与核心对象实例化。
- core/bootstrap.php 依赖 config/config.php 获取数据库与应用配置。
- 自动加载与模块
- core/autoload.php 依赖 DOU_MODULE_MAP 与 DOU_DB_CONFIG 等常量，决定模块类与数据库连接配置。
- 路由与控制器
- 各端入口通过 Route::setDelegate 指定端路由，控制器/服务/模型由自动加载器按需加载。
graph LR
Index["index.php"] --> Bootstrap["core/bootstrap.php"]
Bootstrap --> Config["config/config.php"]
Bootstrap --> Autoload["core/autoload.php"]
Index --> Router["路由调度"]
Router --> Controllers["控制器/服务/模型"]
Controllers --> Storage["数据库/存储"]性能与调试
- 调试模式
- 通过 config/config.php 的 DOU_DEBUG 控制站点调试开关。开启后，异常会在HTML或JSON中输出详细堆栈；关闭则回退到友好提示或标准错误响应。
- 日志记录
- 入口层对未捕获异常统一写入 error_log，便于问题定位。
- 性能优化建议
- 避免在高频路径中进行不必要的数据库查询与文件IO。
- 合理使用缓存与分页，减少大对象传输。
- 关注自动加载器的解析路径，确保类文件存在且命名规范，避免多次文件探测。
- 监控与追踪
- 结合错误日志与站点调试模式，定位异常发生位置与上下文。
- 对于API，关注标准错误码与错误信息，便于前端统一处理。
故障排查指南
- 未安装跳转
- 若 storage/install.lock 不存在，入口会重定向到安装程序。请确认已完成安装流程。
- 数据库连接失败
- 检查 config/config.php 中的数据库主机、用户名、密码与表前缀是否正确。
- 路由不生效
- 确认路由文件是否存在且命名符合自动加载约定；检查声明式路由配置是否正确。
- 异常未捕获
- 检查入口层的异常捕获分支是否覆盖当前异常类型；确认站点调试模式是否开启以便查看详细堆栈。
- API返回非JSON
- 确认请求头Accept包含application/json或为Ajax请求；检查入口层的wantsJson判定逻辑。
结论
DouPHP通过清晰的入口与引导流程、强大的自动加载机制与三端分离的路由架构，提供了可扩展、易维护的开发体验。遵循本文档的结构与规范，开发者可以快速上手、高效迭代，并在生产环境中保持稳定的运行表现。
附录：开发规范与最佳实践
- 环境搭建
- 确保PHP版本满足要求；配置数据库连接与应用密钥；完成安装流程。
- IDE配置
- 启用PSR-4自动加载；配置命名空间映射；开启语法检查与代码格式化。
- 代码规范
- 遵循Dou\命名空间约定；控制器/服务/模型按端目录分层组织；使用声明式路由简化URL映射。
- 单元测试
- 针对服务层与核心逻辑编写用例；模拟外部依赖（数据库、缓存、第三方API）；保证断言覆盖关键分支。
- 代码审查
- 提交前自查命名、注释、异常处理与日志记录；关注性能敏感路径与安全性校验。
- 版本控制
- 使用分支策略（feature/fix/hotfix）；提交信息清晰描述变更；合并前通过CI检查。
- 协作开发
- 明确模块边界与接口契约；定期同步上游变更；冲突及时沟通解决。
- 调试技巧
- 利用站点调试模式输出详细堆栈；结合error_log与请求上下文定位问题；对API使用标准错误码与消息。
- 性能分析
- 使用性能分析工具识别瓶颈；优化SQL与缓存策略；减少不必要的数据传输。
- 常见陷阱
- 避免直接操作超全局变量；统一通过Request与配置中心获取数据；注意异常类型与捕获顺序；确保类文件路径与命名一致。