编写或重构 Laravel 13 应用时用：让控制器…

在 Laravel 13（PHP 8.3+）中创建控制器、模型、迁移、验证、服务类或搭建应用架构时，按 31 条规则与 7 大类别落地最佳实践。

适用场景

解决思路

1. 按优先级排序执行：架构与结构（CRITICAL）→ Eloquent 与数据库（CRITICAL）→ 控制器与路由（HIGH）→ 验证与请求（HIGH）→ 安全（HIGH）→ 性能（MEDIUM）→ API 设计（MEDIUM）
2. 把业务逻辑从控制器抽到 Service 类（如 App\Services\PostService），控制器只负责接收请求、调用服务、返回响应
3. 为单一目的的动作建 Action 类，一个类只做一件事
4. 仅在查询复杂或存在多数据源时才引入 Repository 模式；简单 CRUD 直接用 Eloquent，不要过度封装
5. 用 DTO 在层与层之间传递数据，而不是传裸数组
6. 用 Value Object 封装领域概念（金额、邮箱、ID 等）
7. 用事件（Event）与监听器（Listener）解耦副作用，而不是把通知、统计等逻辑堆在业务方法里
8. 按领域/功能（feature folders）组织目录，而不是按技术类型分 Controller/Model 大目录
9. Laravel 13+ 使用集中式 job queue routing 配置统一管理队列路由
10. 查询关系时用 with() 预加载，消除 N+1：Post::with(['author','category','tags'])->get()
11. 需要多级数据时用嵌套预加载：with(['author.profile','comments.user','tags'])
12. 需要限制关联数量时用约束式预加载：with(['comments' => fn ($query) => $query->latest()->limit(5)])
13. 处理大数据集时用 chunk() 分批，不要一次性 all() 载入
14. 把可复用查询条件写成 scope：public function scopePublished(Builder $query): Builder
15. 把模型副作用放进 observer（模型事件），不要在控制器里手工触发
16. 正确声明关系方法并标注返回类型：BelongsTo、BelongsToMany（可链 withTimestamps()）等
17. 用 protected $casts 自动转换属性，例如 'published_at' => 'datetime'
18. 用 Laravel 13 风格的 Attribute 定义访问器/修改器：protected function title(): Attribute { return Attribute::make(set: fn (string $value) => ucfirst($value)); }
19. 需要可恢复删除时给模型加 SoftDeletes
20. 用 model pruning 自动清理过期旧记录
21. Laravel 13+ 在需要语义搜索时使用 pgvector 向量搜索
22. 用 Resource Controller 与 RESTful 方法组织路由：index/store/show/update/destroy
23. 单个动作的场景用可调用控制器（__invoke）代替多方法控制器
24. 把校验与授权放进 Form Request 类（如 StorePostRequest），并在控制器方法签名中直接注入
25. Form Request 中实现 authorize()，用 Gate/Policy 判断：return $this->user()->can('create', Post::class);
26. Form Request 的 rules() 用数组式规则声明，如 'title' => ['required','string','max:255']、'published_at' => ['nullable','date','after:now']
27. 用 messages() 覆盖默认错误提示，例如 'body.min' => 'The post body must be at least 100 characters.'
28. 用自定义 Rule 类封装复杂校验逻辑
29. 用条件验证规则（sometimes / Rule::when）处理按条件才生效的字段
30. 校验嵌套数组时同时声明容器与元素规则：'tags' => ['nullable','array']、'tags.*' => ['exists:tags,id']
31. 复杂校验用 after hooks（withValidator / after 回调）在基础规则通过后再做业务校验
32. 用 $fillable 白名单（或 $guarded）防止批量赋值漏洞
33. 服务类中的跨表写操作统一用 DB::transaction 包裹，保证原子性，事务内完成后返回 $post->fresh()
34. 迁移 up() 中用 foreignId()->constrained()->cascadeOnDelete() 建外键，对 slug 加 unique()，并为常用查询加复合索引 $table->index(['user_id','published_at'])；down() 中写 Schema::dropIfExists('posts')
35. API 响应用 API Resource 做转换，不要直接返回 Eloquent 模型
36. 按路由/分组/控制器正确挂载 middleware，而不是在方法体内手工判断
37. 通过构造函数或方法签名做依赖注入（如 private readonly NotificationService $notifications），不要在方法内 new 服务
38. 需要逐条细节时查阅 rules/ 下的单个规则文件（如 rules/arch-service-classes.md、rules/eloquent-eager-loading.md、rules/validation-form-requests.md、rules/_sections.md）或完整的 AGENTS.md

适用边界 · 注意事项

• 小型脚本、原型或一次性任务，不需要 Service/Action/DTO/Repository 全套分层，过度抽象会拖慢开发
• 不是 Laravel 13 / PHP 8.3+ 的项目：queue routing、向量搜索等特性依赖新版本 API
• 简单的单表 CRUD 无需引入 Repository 或 Value Object；向量搜索还需要 PostgreSQL 与 pgvector 扩展支持