必须用 Route::apiResource() 而非 Route::resource()，因其自动跳过 web 中间件组（如 VerifyCsrfToken、StartSession），避免 API 场景下出现 419 错误、session 写入失败或响应头污染；routes/api.php 默认启用 api 中间件组（含 throttle:api，不含 session/CSRF）。
Route::apiResource() 配合 --api 控制器就能跑通标准 CRUD，90% 的基础接口不需要写额外路由或手动封装 JSON。
为什么必须用 Route::apiResource() 而不是 Route::resource()
两者生成的 URL 和动作一样，但中间件完全不同：Route::apiResource() 自动跳过 web 中间件组（比如 VerifyCsrfToken、StartSession），而 Route::resource() 默认会加载它们——这在 API 场景下会导致 419 错误或 Session 写入失败。
- 常见错误现象：
POST /api/posts返回419 Page Expired，查日志发现CSRF token mismatch - API 请求本该无状态，
session_start()被意外触发后还可能引发并发写冲突 -
routes/api.php里的所有路由默认走api中间件组，它不包含 session 或 CSRF，但含throttle:api
php artisan make:controller --api 真正省掉的是什么
加 --api 不是“少写两个方法”那么简单，它从骨架上剔除了 Web 惯用逻辑：没有 create()、edit()，也没有任何 return view() 或 $request->old() 相关代码。这些残留逻辑一旦混进 API 控制器，轻则返回 HTML 模板，重则因调用 session() 导致响应头污染。
- 已误建普通控制器？别删方法，直接
php artisan make:controller Api/PostController --api新建，旧控制器留着删 -
--api不影响模型绑定或请求验证写法，$request->validate()依然可用 - 返回值直接写
Post::find($id)就行，Laravel 自动转 JSON +200；不用response()->json()手动包一层
什么时候该上 ApiResource 类
不是“用了就高级”，而是当你需要统一字段、隐藏敏感属性、处理关联嵌套或做条件序列化时才值得引入。比如用户列表里不想暴露 password_hash，或者文章详情要带作者和评论数，这时候裸模型 return $post 就不够用了。
- 生成命令：
php artisan make:resource PostResource - 控制器里用：
return new PostResource($post)（单条）或PostResource::collection($posts)（列表） - 注意：资源类里调
$this->whenLoaded('comments')可避免 N+1，但得先在控制器里with('comments')预加载 - 别在资源类里写业务逻辑，比如权限判断——那该放
Policy或中间件里
认证别卡在 Sanctum 初始化上
Sanctum 的 HasApiTokens trait 和数据库迁移必须配对生效。漏跑 php artisan vendor:publish --provider="Laravel\Sanctum\SanctumServiceProvider" 或忘记 php artisan migrate，后续调 $user->createToken() 会静默失败或抛 BadMethodCallException。
- 检查
users表是否有api_tokens字段（migration 文件名含create_sanctum_tables） - 前端请求头必须带
Authorization: Bearer {token}，且不能漏Accept: application/json，否则验证失败时可能返回 302 重定向而非 401 - 本地开发用
sanctum中间件即可，别一上来就切passport——后者需 OAuth 流程，API 场景多数用不上
v1）和错误响应结构的一致性。前者不加，后期改接口就得全量兼容；后者不统一，前端要写一堆 if (res.data?.message) 去猜错误类型。这两项没写在骨架命令里，但上线前必须补上。 
