本文目录导读：
编写一份高质量的 PHP 项目架构决策记录（ADR） 需要结合具体业务场景，由于你没有提供具体的项目背景（如：是单体应用、微服务、电商、SaaS 还是框架选型问题），我将提供一个通用且高度可定制的模板，并附上针对 PHP 生态特定痛点的决策示例。
你可以直接复制以下 Markdown 格式，替换方括号 中的内容即可。
架构决策记录：PHP 项目技术栈与分层策略
状态：[提议中 / 已接受 / 已废弃] 日期：[202X-XX-XX] 决策者：[技术负责人、核心开发成员]
背景（Context）
当前项目 [项目名称] 面临以下核心诉求与痛点：
- 业务需求：需要支持 [高并发/复杂业务逻辑/快速迭代/多租户/严格合规]。
- 团队现状：团队主要熟悉 [原生 PHP / Laravel / Symfony / ThinkPHP]，人数为 [X] 人，DevOps 能力 [强/中/弱]。
- 遗留系统：存在 [老旧的 PHP 5.x 系统 / 单体巨石应用 / 无自动化测试] 需要兼容或重构。
- 部署环境：目标部署于 [自建机房 / 阿里云 / AWS / Docker/K8s]，PHP 版本要求为 [7.4 / 8.1 / 8.3]。
核心决策问题：我们需要决定采用何种语言版本、框架、架构风格（分层/DDD/微服务）及关键组件来平衡交付速度与长期可维护性。
决策（Decision）
我们决定采用“基于现代 PHP 8.x 的模块化单体（Modular Monolith）为主，预留服务拆分能力”的架构策略。
具体决策内容如下：
- 语言版本：强制使用 PHP 8.2+，充分利用
readonly类、枚举类型、构造器属性提升等特性。 - 主框架：选择 Laravel 11.x（或 Symfony 7.x / ThinkPHP 8.0，取决于团队熟悉度），原因：生态丰富、ORM 强大、队列与事件系统完善。
- 架构风格：分层架构 + DDD（领域驱动设计）战术模式。
- Interface/Http 层：Controller 只负责参数校验和响应返回，不写业务逻辑（瘦控制器）。
- Application 层：Service 负责业务流程编排、事务管理。
- Domain 层：Entity 与 Domain Service 承载核心业务规则，不依赖 Laravel 框架（保持纯 PHP）。
- Infrastructure 层：Repository 实现、第三方 SDK 封装、Eloquent ORM 模型（仅存在于该层）。
- 数据库：MySQL 8.0+（InnoDB），核心表强制使用 UUID 或雪花ID（避免自增ID暴露业务量），所有表包含
created_at和updated_at。 - 关键中间件：
- 缓存：Redis（用于缓存、Session、队列驱动）。
- 队列：Redis 驱动，用于异步任务（邮件、短信、耗时计算）。
- API 认证：Laravel Sanctum（个人令牌）或 JWT（OAuth2.0）取决于是否有第三方接入需求。
- 前端分离：前后端完全分离，后端仅返回 JSON 数据，前端使用 Vue3/React 独立部署（通过 Nginx 反向代理）。
决策背景与驱动因素（Motivation）
- 模块化单体 相比微服务，在项目初期能极大降低运维复杂度和调试成本，同时通过物理目录隔离（
app/Modules/*）保留了未来拆分为独立服务的可能性。 - PHP 8.2 相比 7.4 在性能上提升约 20-30%，且强类型特性有助于减少运行时错误，提高代码静态分析能力（PHPStan Level Max）。
- 瘦控制器 + Service 层 解决了历史项目中“Controller 里堆 SQL”导致无法单元测试的痛点。
- 领域层纯 PHP 确保了核心业务逻辑不依赖于 Laravel Facade,方便未来在不同框架间迁移或进行单元测试。
备选方案（Alternatives Considered）
| 方案 | 优点 | 缺点/被否决原因 |
|---|---|---|
| 原生 PHP（无框架） | 性能极致、无依赖 | 开发效率极低，安全性（SQL注入、XSS）难以系统化防御，不符合团队协作要求。 |
| Laravel 单体式（MVC 无目录分层） | 上手快，代码量少 | 随着业务增长，Model 文件会膨胀至“上帝类”，Service 间相互调用耦合严重，后期维护成本高。 |
| Hyperf / Swoole 常驻内存 | 超高并发 | 对团队技术要求高，Debug 调试方式与传统 PHP 不同，且目前项目预估并发未达到该量级。 |
| Presto / ClickHouse | 分析型查询快 | 事务支持弱，不适合作为核心 OLTP（联机事务处理）业务的唯一存储。 |
关键改动与影响（Consequences）
正面影响：
- 代码结构强制统一,新成员通过目录结构即可定位功能代码。
- 单元测试覆盖率可以提升至核心业务 80% 以上。
- 接口响应速度预计提升 [X]%（得益于 PHP 8 和 Redis 缓存）。
负面影响 / 风险：
- 过度设计风险：DDD 分层可能导致初期开发速度略慢。
- 学习成本：团队需要熟悉 Repository 模式，避免在 Controller 中直接使用
Model::query()。 - 部署不可变：由于使用了
readonly属性和强类型，PHP 7.x 环境无法兼容，必须为 PHP 8.2 专门配置运行环境。
具体实施指导 (Code Guidelines)
在实际写代码时,必须遵守以下规则以落实架构决策：
- 禁止在 Blade 模板中书写复杂业务逻辑。
- 禁止在控制器中使用
DB::table()查询，必须通过 Repository 接口调用。 - 遵循 Fat Domain，所有与金额、状态流转相关的逻辑封装在
Domain层，不可直接在 Service 中写if判断状态。 - Eloquent Model 必须继承自
App\Models\BaseModel，且只定义 关联关系、字段映射（casts）、作用域（Scope）。
后续待办事项（Action Items）
- [ ] 搭建基础的 PHPStan/Psalm 静态分析环境，并设置为 Git commit 钩子。
- [ ] 编写本项目独有的
Architecture Test（如使用 PestPHP 或 PHPMD 校验：禁止Impl类在Http层直接引用）。 - [ ] 制定数据库迁移规范（使用 Laravel Migrations，禁止手工改库）。
针对特定场景的快速决策速查表
如果你只是想快速选型,可参考以下简短建议：
- 如果是个人的博客/小型CMS：直接选 Laravel 11 + Laravel Breeze + SQLite，不需要做 DDD。
- 如果是企业级中后台系统（如 ERP、OA）：Laravel + AdminLTE/Voyager + RBAC扩展，架构使用多层 Service 即可。
- 如果是电商或金融类系统（高一致性要求）：Laravel/Symfony + MySQL + Redis，必须引入 队列 (Horizon) 和 事务脚本,领域层设计需仔细推敲。
- 如果是支付接口/API 服务（纯后端）：Laravel + Sanctum + Spatie/laravel-permission + API Resources，使用
strict_types和 DTO（数据传输对象）。
注意中关于 Laravel 的版本号（如 11.x）、PHP 版本（8.2）是基于 2024-2025 年的行业主流选择，请在决策时根据实际 Packagist 最新版本做稍许调整。
如果你有具体的业务场景（如电商库存超卖、IM即时通信），欢迎提供更多细节，我可以为你生成更贴合业务的 ADR。
