ia-php-laravel

概述

本技能文档（ia-php-laravel）是一份面向现代 PHP 8.4 与 Laravel 框架的企业级开发规范，由社区资深实践者编纂，内容深度对标 Laravel 官方文档与生产环境最佳实践，属于 T1 级可信来源。

核心用法

技能覆盖六大工程维度：

1. 语言层现代化：强制 PHP 8.4 特性应用，包括只读类/属性、非对称可见性、属性钩子、DNF 类型、构造器提升、array_find() 等新函数，要求代码零注释冗余（开发者应已知这些特性）。

2. 架构模式：主张「瘦控制器、胖模型、服务类、Action 类」分层，Form Request 承担边界验证并转换为类型化 DTO，Events 处理副作用，Feature Folder 组织替代类型分层（项目>20模型时）。

3. 数据层最佳实践：Eloquent 配置 preventLazyLoading 防 N+1，强制 $fillable 白名单，批量操作用 upsert/increment/decrement 减少内存负载，复杂迁移采用 expand-contract 模式。

4. API 工程化：Contract-First 设计（先定义 Resource 与 Form Request），统一 JSON 响应信封，Hyrum's Law 意识（字段增优于改），第三方响应必须验证后使用。

5. 队列与可靠性：Job 批处理、链式调用、唯一任务（ShouldBeUnique）、Redis 限流，生产环境强制实现 failed() 回调。

6. 测试体系：Feature/Unit 分层，Factory 驱动数据，Facade 假对象（Queue::fake/Http::fake），断言覆盖响应状态与副作用，目标覆盖率 80%+。

显著优点

• 生产防御深度：独有「Common Pitfalls」章节，揭示查询构造器 update() 绕过 Observer、Observer 误删同级资源、chunkById 并发覆盖 JSONB、date cast 与 JsonResource 行为不一致等四类隐形生产事故。
• 工具链闭环：PHPStan Level 8+、严格类型声明、零注释文化、CI 前置验证（phpstan && phpunit 零警告），形成可量化的代码质量门禁。
• 性能与韧性并重：OPcache/JIT/预加载配置指引，健康检查端点（/health vs /ready），启动时配置校验（fail-fast），兼顾吞吐与可观测性。

潜在缺点与局限

• 版本锁定激进：PHP 8.4 特性要求可能排除仍需维护 8.1/8.2 的遗留项目，升级成本需评估。
• 隐式知识密度高：「无解释注释」原则假设开发者已掌握所有现代 PHP 特性，新人 onboarding 需配套培训。
• Laravel 生态绑定：部分模式（如 Eloquent 事件系统、Artisan 命令）迁移至其他 PHP 框架（Symfony/Slim）需重构。
• 未覆盖 PHP 内部：明确排除 php-src 内部机制讨论，底层扩展开发需另寻资料。

适合人群

• 构建/维护 Laravel 10/11 生产级应用的 PHP 工程师
• 技术负责人制定团队代码规范与 CI/CD 门禁
• 从 8.x 迁移至 PHP 8.4 并寻求现代化架构模式的项目
• 需要标准化 API 设计、队列可靠性、测试策略的跨功能团队

常规风险

• 静态分析依赖：PHPStan Level 8 可能引入大量遗留代码报错，迁移期需渐进式级别调整。
• Observer 绕过误用：开发者若未理解「查询构造器 update 不触发事件」的陷阱，可能导致审计日志缺失。
• 批量操作并发安全：upsert/chunkById 在高并发场景下的锁策略需结合具体存储引擎（MySQL 间隙锁 vs PostgreSQL 咨询锁）额外验证。
• 测试策略过载：80% 覆盖率目标在快速原型阶段可能拖慢迭代速度，建议按阶段（MVP vs 生产）动态调整。