资源控制器需严格遵循七项约定才能正常运行：方法名、参数名、HTTP动词、路由位置、中间件、控制器继承、请求体解析；API路由必须用Route::apiResource()，不可混用Route::resource()。
资源控制器不是“写完就能用”，而是“写对七件事才能跑通”——方法名、参数名、HTTP动词、路由位置、中间件、控制器继承、请求体解析，缺一不可。
Route::apiResource() 和 Route::resource() 别混用
API 路由必须用 Route::apiResource()，别手滑写成 Route::resource()。前者默认排除 create 和 edit，请求体自动解析为 JSON，中间件自动套 api 组（含 throttle 和 substituteBindings）；后者默认走 web 中间件组，带 session、CSRF，还硬塞两个 HTML 表单路由，API 场景下会直接 419 或 405。
常见错误现象：POST /api/users 返回 419，或 param() 始终为空——大概率是用了 Route::resource() 却没配 CSRF 排除，或没意识到它不自动解析 JSON body。
-
Route::apiResource('users', UserController::class)→ 生成 5 条路由（不含 create/edit），store()方法可直接用$request->all() -
Route::resource('users', UserController::class)→ 生成 7 条，store()仍需手动处理input()，且默认校验 CSRF - 纯 API 项目，routes/api.php 里只允许用
Route::apiResource()，别跨文件混用
控制器方法签名必须严格匹配约定
Laravel 不做模糊匹配，show($id) 写成 show($userId) 或 show(int $id) 都可能让路由绑定失败——框架只认参数名 $id（单数资源）或 $photo（资源名复数变单数），且不校验类型提示。
容易踩的坑：update(Request $request, $id) 少了 $request 参数，PUT/PATCH 请求体就取不到；destroy($id) 写成 delete($id)，DELETE 请求直接 404。
- 标准七动作对应方法：index、show、store、update、destroy（
Route::apiResource()） - 参数名必须是资源单数形式，如
users→$user，api_tokens→$apiToken（下划线转驼峰） - 方法必须是 public，不能加 static，不能有额外默认参数
php artisan make:controller --api 是唯一安全起点
别手动新建控制器再补七个空方法——php artisan make:controller Api/V1/UserController --api 生成的类，已经删掉 create() 和 edit()，方法签名全对，连注释都标好了 HTTP 动词和用途。手写极易漏掉 use Illuminate\Http\Request; 或返回 response()->json() 的惯用写法。
Laravel Cloud（cloud.laravel.com）。此技能用于处理所有 Laravel Cloud 请求，包括搜索和读取数据。只要任务涉及 Laravel Cloud，即使用此技能。
使用场景：所有新 API 控制器必须从此命令开始；已有控制器若要转 API，建议重生成再迁移逻辑，别修修补补。
- --api 选项生成的方法不含视图返回，全是
return response()->json(...)模板 - 路径建议按版本分层：
app/Http/Controllers/Api/V1/UserController.php - 生成后立刻执行
php artisan route:list --path=api确认路由已注册，别等联调才发现没生效
嵌套资源与自定义动作要显式声明
嵌套如 /api/posts/{post}/comments，不能靠字符串拼接，得用 Route::apiResource('posts.comments', CommentController::class)。框架会自动识别两级参数，index(Post $post) 方法第一个参数就是已绑定的 $post 实例。
非标准动作（如 publish、restore）绝不能塞进标准方法里判断 flag，必须单独定义：
Route::post('posts/{post}/publish', [PostController::class, 'publish'])->name('posts.publish');- 自定义动作路由必须放在
apiResource()之后，否则会被覆盖 - 嵌套时避免三层以上，如
users.posts.comments，应考虑改用查询参数或独立端点
最常被忽略的是命名规范：->name('posts.comments.index') 这种完整点号命名，是 Laravel 生成 URL 和重定向的基础，漏掉会导致 route() 辅助函数失效。
