laravel-best-practices

Laravel 最佳实践

Laravel 最佳实践，按规则文件索引组织。每个规则文件都会说明应该怎么做以及原因。对于确切的 API 语法，请使用 search-docs 验证。

一致性优先

应用任何规则前，先检查应用程序现有的做法。Laravel 提供了多种有效方案。最佳选择是代码库已经采用的方案，即使从理论上看其他模式更好。不一致比次优模式更糟。

检查同级文件以及相关控制器、模型或测试中已有的模式。如果存在，就遵循它。不要引入第二种做法。这些规则是在尚无既有模式时使用的默认方案，而不是覆盖既有做法的规则。

如何应用

1. 检查变更文件、附近代码、项目配置和相关测试中已有的模式。只有存在正确性或安全缺陷时才偏离，并明确说明偏离之处。
2. 将每项受影响的关注点对应到下面的规则索引。编辑前阅读每个对应的规则文件。跳过不相关的规则文件。
3. 做出最小且完整的变更。沿用应用程序的架构和命名，不要为同一任务引入第二种模式。
4. 使用 search-docs 验证与版本相关的 Laravel API 是否适用于已安装的版本；如果 search-docs 不可用，则检查已安装的框架。
5. 先运行范围最小的相关测试；如果变更需要，再运行项目的格式检查和静态分析。
6. 完成前，对照每条对应规则重新检查差异。

规则索引

跨领域的变更通常需要参考多个规则文件。

关注点	阅读
查询数量、预加载、索引、大型数据集	rules/db-performance.md
子查询、聚合、复杂排序和查询计划	rules/advanced-queries.md
模型、关联、作用域、类型转换	rules/eloquent.md
身份验证、授权、输入安全、机密、上传	rules/security.md
表单请求和验证规则	rules/validation.md
控制器、路由绑定、资源、中间件	rules/routing.md
架构变更、列、外键、索引	rules/migrations.md
作业、重试、唯一性、批次、Horizon	rules/queue-jobs.md
缓存有效期、失效、锁、记忆化	rules/caching.md
发出的请求、重试、超时、伪造	rules/http-client.md
异常、报告、渲染、日志上下文	rules/error-handling.md
事件和通知	rules/events-notifications.md
可邮寄对象和邮件断言	rules/mail.md
计划任务和防止重叠	rules/scheduling.md
集合、惰性迭代、批量操作	rules/collections.md
Blade 组件、属性、视图合成器	rules/blade-views.md
环境值和应用程序配置	rules/config.md
测试：覆盖率、工厂、伪造和断言	testing-best-practices 技能
命名、辅助函数、文件边界、PHP 风格	rules/style.md
操作、服务、依赖、应用程序结构	rules/architecture.md

决策规则

• 优先使用框架功能和应用程序现有抽象，而不是新增辅助函数或依赖。
• 避免推测性抽象。只有在形成清晰的领域边界、消除有意义的重复，或使行为能够独立测试时，才提取代码。
• 不要在 Blade 视图中访问数据库，并防止控制器、资源、作业和序列化过程中出现隐式 N+1 查询。