用途:为 Laravel 项目定义控制器的编写规范,让控制器只承担 HTTP 层职责,领域逻辑下沉到 Action 等其它层。
主要能力与约定:控制器只做四件事——类型提示依赖、通过 Form Request 校验、调用 Action、返回响应(Resource、重定向、视图)。禁止在控制器内写领域逻辑、直接查数据库、做计算或处理复杂业务规则。命名使用资源复数形式,如 CalendarsController、OrdersController;嵌套资源用父单数加子复数,如 CalendarEventsController,路由用 Route::resource('calendars.events', CalendarEventsController::class)。
方法限制:只允许标准 RESTful 方法。Web 用 index、create、store、show、edit、update、destroy;API 不含 create 与 edit。禁止 all、get、add、remove 等自定义名。非 RESTful 动作抽成可调用控制器,例如 CancelOrderController 的 __invoke,路由 Route::post('/orders/{order:uuid}/cancel', CancelOrderController::class)。
分层:Web 层放 app/Http/Web/Controllers/,路由 routes/web.php,不版本化、可自由变更;公共 API 放 app/Http/Api/V1/Controllers/,路由 routes/api/v1.php,需版本化并保持稳定契约,破坏性变更需新版本。两者结构相同,仅命名空间不同。
配套用法:列表过滤排序用 Query Object(配合 Spatie Query Builder);授权可用 $this->authorize 或路由 ->can();用路由模型绑定简化取参,支持自定义键如 {order:uuid};测试用 Pest 的 Feature 测试覆盖创建、鉴权与校验失败等场景。
限制:资料未提供安装命令、版本要求、性能数据或收费信息。