引言
本文件为 DouPHP 项目制定标准化的开发工作流程，覆盖分支管理、提交规范、代码审查、新功能开发流程、版本发布与回滚策略、协作最佳实践以及开发工具链配置。目标是让团队在大型多模块（前台/后台/API/小程序/插件/主题）项目中保持一致的协作方式，降低合并冲突与回归风险，提升交付质量与可维护性。
项目结构
DouPHP 采用前后端分离与模块化组织：
- 入口与路由：根入口 index.php 负责引导框架、解析语言前缀、分发请求并统一异常处理。
- 业务域：admin（后台）、front（前台）、api（对外接口）、plugin（支付等插件）、theme/miniprogram（前端模板与小程序）。
- 核心框架：core（基础能力：ORM、服务、中间件、配置等）。
- 配置与资源：config、images、languages、storage（运行时数据）。
- 工具与脚本：devtools（升级/迁移/校验脚本）。
graph TB
A["index.php<br/>入口与异常处理"] --> B["Front Router<br/>前台路由"]
A --> C["Admin Router<br/>后台路由"]
A --> D["API Router<br/>接口路由"]
B --> E["Service/Model<br/>业务逻辑"]
C --> E
D --> E
E --> F["Core Framework<br/>ORM/配置/中间件"]
E --> G["Storage/DB<br/>运行时与持久化"]核心组件
- 入口与请求生命周期：index.php 完成初始化、路由设置、请求分发与异常兜底；对 JSON 请求与非 JSON 请求分别返回结构化响应或页面提示。
- 路由与中间件：各子应用（front/admin/api）通过独立路由与中间件实现鉴权、限流、安全头等横切关注点。
- 服务与模型：按领域划分 service/model，便于复用与测试。
- 配置与环境：config 集中管理系统、模块、云服务等配置项。
架构总览
下图展示从 HTTP 请求到业务处理的端到端流程，体现入口、路由、服务与异常处理的关键节点。
sequenceDiagram
participant Client as "客户端"
participant Entry as "入口 index.php"
participant FrontInit as "前台初始化"
participant Route as "路由分发"
participant Service as "业务服务"
participant DB as "数据库/存储"
Client->>Entry : "HTTP 请求"
Entry->>FrontInit : "初始化(语言/路由)"
FrontInit-->>Entry : "初始化完成"
Entry->>Route : "dispatch()"
Route->>Service : "调用对应服务"
Service->>DB : "读写数据"
DB-->>Service : "结果集"
Service-->>Route : "业务结果"
Route-->>Entry : "Response"
Entry-->>Client : "JSON/HTML 响应"详细组件分析
Git 分支管理策略
- 主分支
- main：生产可用基线，仅允许通过受控流程合并，禁止直接推送。
- release/*：预发布分支，用于冻结修复与打包验证。
- 开发分支
- develop：集成日常功能，所有功能分支最终合并到此。
- 功能分支
- feature/*：新功能开发，命名如 feature/订单导出。
- fix/*：缺陷修复，命名如 fix/登录验证码错误。
- hotfix/*：线上紧急修复，直接从 main 拉取，修复后同时合入 main 与 develop。
- 分支保护
- main/develop 开启保护规则，要求至少 1 位审查者批准，CI 全绿方可合并。
- 合并策略
- 优先使用 squash merge 保持历史整洁；hotfix 使用 rebase 最小化变更。
代码提交规范
- Commit 消息格式
- 类型: 描述
- 类型包括：feat, fix, docs, style, refactor, test, chore, revert
- 示例：feat: 新增商品批量导入
- 变更描述要求
- 简要说明动机与影响范围
- 涉及 API/数据库变更需标注
- 关联需求/任务编号（如 #123）
- 提交前检查
- 本地静态检查、格式化、单元测试通过后再 push
代码审查流程
- PR 创建
- 基于 feature/xxx -> develop，或 hotfix/xxx -> main
- PR 标题遵循“类型: 简述”，正文包含变更说明、影响面、测试情况
- 审查标准
- 可读性与一致性（命名、分层、注释）
- 安全性（输入校验、权限控制、敏感信息）
- 性能（N+1 查询、大对象传输）
- 可测试性（边界条件、异常路径）
- 合并策略
- 必须通过 CI 与至少一位 reviewer 批准
- 禁止强制推送至受保护分支
新功能开发标准流程
- 需求分析
- 明确用户故事、验收标准、非功能需求（性能、安全）
- 设计与评审
- 输出接口契约、数据模型、流程图；进行技术评审
- 开发与自测
- 在 feature 分支实现，编写单测/集成测试，确保本地通过
- 提测与联调
- 合并至 develop，触发自动化流水线；与前后端联调
- 预发布与上线
- 打 release/* 标签，灰度发布；监控指标稳定后合并至 main 并打 tag
版本发布流程
- 版本号管理
- 采用语义化版本：主版本.次版本.修订号（MAJOR.MINOR.PATCH）
- 破坏性变更升主版本，新增功能升次版本，修复升修订号
- 变更日志维护
- 每次合并生成变更记录，分类：新增、修复、优化、废弃、已知问题
- 回滚策略
- 支持快速回滚：通过部署平台回退到上一个稳定版本
- 数据库变更需具备向下兼容或可逆脚本；必要时提供回滚 SQL
协作开发最佳实践
- 冲突解决
- 频繁同步 develop，小步提交；冲突时先解冲突再提交
- 复杂冲突建议拆分 PR 或召开对齐会议
- 依赖管理
- 使用 composer 管理 PHP 依赖，锁定版本；避免引入未审计包
- 第三方库升级需评估兼容性并补充测试
- 文档同步
- 接口变更同步更新 API 文档；配置变更更新部署手册
开发工具链配置与使用
- 静态分析与格式化
- 配置 PHP CS Fixer/PHPCS 等工具，纳入 pre-commit 钩子
- 统一编辑器配置（缩进、换行、编码），参考 .editorconfig（若启用）
- 自动化流水线
- CI 阶段：安装依赖、静态检查、单元测试、构建产物
- 可选：覆盖率阈值、安全扫描、镜像构建
- 本地调试
- 开启 site.debug 输出结构化错误；关闭生产环境调试
- 使用 storage 目录隔离日志与缓存，避免入库
依赖分析
- 运行依赖
- PHP >= 5.6，扩展 mysqli/json/curl
- 通过 composer 管理依赖，推荐 dist 安装与排序优化
- 模块耦合
- 入口与路由松耦合，通过服务层聚合业务；控制器/服务/模型分层清晰
- 插件体系解耦外部服务（支付、短信等），便于替换与扩展
graph LR
A["index.php"] --> B["路由/中间件"]
B --> C["服务层"]
C --> D["模型/ORM"]
C --> E["配置/存储"]
C --> F["插件/扩展"]性能考虑
- 减少 N+1 查询：在服务层聚合查询，合理使用 eager loading
- 缓存策略：热点数据缓存（内存/Redis），注意失效与一致性
- 异步处理：耗时任务（邮件、报表）走队列或定时任务
- 资源限制：图片/文件压缩与 CDN 加速；分页与索引优化
- 监控告警：关键指标（QPS、延迟、错误率）接入监控与告警
故障排查指南
- 异常处理
- 入口统一捕获 DomainException/HttpResponseException/普通异常
- JSON 请求返回结构化错误码与消息；HTML 请求显示友好提示或调试页
- 日志记录
- 未捕获异常写入 error_log；结合站点调试开关输出详细堆栈
- 常见问题定位
- 确认路由是否正确解析语言前缀与 route 字符串
- 检查中间件是否拦截（鉴权、限流、安全头）
- 核对配置项（数据库、云服务、功能开关）
结论
通过规范的分支管理、提交与审查流程、标准化的新功能与发布流程，以及完善的工具链与排障机制，DouPHP 可在多模块、多端协同的开发环境中保持稳定迭代与高质量交付。建议在团队内推广本流程，并结合 CI/CD 持续改进。
附录
分支与提交速查
- 分支
- main：生产基线
- develop：日常集成
- feature/ / fix/ / hotfix/*：功能/修复/热修
- 提交
- 类型: 描述（feat/fix/docs/style/refactor/test/chore/revert）
- 变更说明 + 影响面 + 关联编号
发布清单
- 版本号与变更日志
- 数据库变更脚本（含回滚）
- 配置差异与环境变量
- 测试报告与覆盖率
- 部署与回滚预案
忽略与运行时文件
- 运行时存储与临时文件不入库，避免污染仓库
- 本地 IDE 配置与调试日志排除