API路由应禁用create/edit、单独定义批量操作、显式绑定非标方法；验证需带Accept:application/json头；Resource需预加载+字段精简；开发时php artisan serve不执行CORS中间件，须改用Valet/Sail或临时加header。
API 路由怎么配才不踩 Route::apiResource 的坑
直接用 Route::apiResource 看似省事，但默认行为在真实项目里常出问题：比如不需要 create 和 edit 这两个返回 HTML 表单的路由，却硬塞进 API；又或者想批量更新却没对应方法。它生成的 7 个动作里，真正常用于前后端分离 API 的往往只有 index、show、store、update、destroy 五个。
实操建议：
- 明确禁用不需要的动作：
Route::apiResource('posts', PostController::class)->except(['create', 'edit']) - 需要批量操作（如
massUpdate）时，别硬套资源路由，单独加：Route::put('posts/batch', [PostController::class, 'batchUpdate']) - 如果控制器方法名不是标准命名（比如叫
toggleStatus），必须显式绑定：Route::post('posts/{id}/toggle', [PostController::class, 'toggleStatus'])，不能指望资源路由自动猜
验证失败时怎么让 ValidateRequest 返回 JSON 而不是跳转
Laravel 默认表单验证失败会重定向回上一页，但在 API 场景下这会导致前端收不到 422 Unprocessable Entity 和错误详情，只看到空响应或 302。根本原因在于请求没带 Accept: application/json 头，Laravel 就当它是 Web 请求处理。
实操建议：
- 确保前端请求头包含：
Accept: application/json（Postman、Axios 默认不带，得手动设） - 验证类继承
FormRequest即可，不用改逻辑；但若混用 Web 和 API 路由，建议拆开：Web 用App\Http\Requests\StorePostRequest，API 用App\Http\Requests\Api\StorePostRequest - 调试时看日志里是否出现
Illuminate\Validation\ValidationException，出现说明验证触发了，但返回格式不对——八成是 Accept 头缺失
Resource 类里怎么避免 N+1 和字段冗余
API 返回数据时直接 return new PostResource($post) 很干净，但一查 SQL 日志就发现：关联模型没预加载，每个 PostResource 里访问 $this->user->name 就触发一次查询；更糟的是，前端只要标题和发布时间，Resource 却把整个 $this->user 对象都 toArray() 了。
实操建议：
- 控制器里必须预加载：
Post::with('user:id,name')->findOrFail($id)，id和name是白名单，防字段泄露 - Resource 的
toArray()方法里，别写'user' => new UserResource($this->whenLoaded('user'))这种兜底逻辑——whenLoaded只防报错，不防 N+1；要确保with已调用 - 字段精简靠
makeHidden或在 Resource 里手动写键值对，比如只返回'author_name' => $this->user->name ?? null，而不是整个user数组
为什么 php artisan serve 开发 API 会跨域失败，而 Nginx 不会
本地用 php artisan serve 启动后，前端发请求提示 CORS header ‘Access-Control-Allow-Origin’ missing，但部署到 Nginx 就正常。这是因为 Laravel 自带的开发服务器不运行中间件栈里的 cors 中间件——它只对 Apache/Nginx 等完整 HTTP 服务器生效。
实操建议：
- 开发时别依赖
php artisan serve测 API 跨域，要么切到 Valet / Sail / Docker，要么临时在public/index.php顶部加响应头（仅限本地）：header('Access-Control-Allow-Origin: *'); - 正式用
fruitcake/laravel-cors包时，确认config/cors.php里'paths'匹配了你的 API 前缀，比如['api/*']，而不是['*']（后者在某些 Laravel 版本下失效） - Chrome 控制台报错说 “No 'Access-Control-Allow-Origin' header”，先 curl 测响应头：
curl -I http://localhost:8000/api/posts，没看到对应 header 就说明中间件根本没跑
API 开发里最麻烦的从来不是写接口，而是验证头有没有传对、关联有没有预加载、跨域中间件在不在请求链路上——这些地方一漏，前端就卡在“明明写了代码却没反应”上。
