Laravel API创建教程及开发指南

本文直击 Laravel API 开发中最常见却极易被忽视的致命陷阱：API 路由必须严格定义在 `routes/api.php` 并搭配 `auth:sanctum` 中间件，绝不可混入 `web.php`（否则触发 419、404、空响应及跨域失败）；必须用 `JsonResource` 封装响应以规避序列化错误、N+1 查询和字段不一致问题；务必确保 `APP_URL` 与 `SANCTUM_STATEFUL_DOMAINS` 完全一致才能使 Cookie 认证生效——这些不是可选最佳实践，而是避免项目上线后集体崩溃的硬性铁律。

直接说结论：Laravel 不需要“新建 API 项目”，所有 API 路由必须写在 routes/api.php，配 auth:sanctum 中间件，返回数据用 JsonResource 封装，否则大概率踩 419、404、空响应、跨域失败这些坑。

API 路由为什么不能写在 web.php 里

写在 routes/web.php 的路由默认走 web 中间件组，会强制启用 StartSession 和 VerifyCsrfToken。API 请求不带 cookie 或 CSRF token，结果就是 419 Page Expired —— 你以为是认证问题，其实是进错了中间件组。

更隐蔽的问题：php artisan route:cache 后，web.php 里的 /api/users 路由可能被缓存成带 session 的版本，彻底无法响应前端请求。

• routes/api.php 是唯一合法入口，Laravel 会自动加 /api 前缀，并绑定 api 中间件组（无 session、无 CSRF、自动 JSON 响应）
• 要加版本号，用 Route::prefix('v1')->group()，别往 URL query 里塞 ?v=2
• 别信“路径含 /api 就是 API”——Laravel 只认文件位置和中间件绑定

auth:api 和 auth:sanctum 到底用哪个

auth:api 是 Laravel 自带的守卫别名，但它默认绑的是已弃用的 TokenGuard。Laravel 9+ 移除了 token 字段，直接写 ->middleware('auth:api') 会报错：Call to undefined method Illuminate\Auth\RequestGuard::user()。

新项目必须用 auth:sanctum（配合 laravel/sanctum）或 auth:passport（配合 laravel/passport）。

• 没运行过 php artisan vendor:publish --provider="Laravel\Sanctum\SanctumServiceProvider"？中间件根本不会生效
• 临时调试可注释掉 auth:sanctum，但上线前必须补上，且确保 config/auth.php 中 'defaults' => ['guard' => 'api'] 指向的是你实际配置的 guard
• 别手动给 API 路由加 VerifyCsrfToken —— 它本不该出现在 api 组里

返回 JSON 为什么有时是 HTML、有时是空响应

浏览器直接访问 /api/users，Accept 请求头默认是 text/html，Laravel 就当你是 Web 请求，返回重定向或 HTML 错误页。你以为接口挂了，其实是内容协商失败。

控制器里写 return $user; 看似简洁，但遇到循环引用（比如模型里有闭包关系）会直接抛出 Serialization of 'Closure' is not allowed；而 return response()->json($user) 能绕过序列化陷阱，还能显式设状态码。

• 开发阶段统一用 response()->json()，别依赖隐式转换
• Postman 或前端调用时，必须手动加 Accept: application/json 头
• 验证失败返回 422？前提是请求头有 Accept: application/json，否则 Laravel 会重定向回上一页

JsonResource 不只是“套一层”，它解决三个真实问题

直接 return $post; 会触发 Eloquent 默认序列化，忽略 $hidden、$casts、日期格式等配置；更糟的是，toArray() 里如果写 $this->user->name，没预加载就会 N+1；如果写业务逻辑（比如判断是否收藏），会导致同一模型在不同接口返回结构不一致。

JsonResource 是响应层的“视图”，只做字段映射，不做查询、不放 if-else。

• 控制器里必须预加载：Post::with('user:id,name')->findOrFail($id)
• Resource 的 toArray() 里只写字段提取：'user' => new UserResource($this->whenLoaded('user'))，别调 $this->user->profile
• 集合要用 UserResource::collection($users)，不是 collect($users)->map(...)

最常被忽略的一点：APP_URL 和 SANCTUM_STATEFUL_DOMAINS 必须完全一致，否则 Cookie 认证连 XSRF-TOKEN 都收不到。本地开发用 http://localhost:3000，后端 APP_URL 却配成 http://127.0.0.1:8000，前端发请求就永远拿不到有效 Cookie。

以上就是本文的全部内容了，是否有顺利帮助你解决问题？若是能给你带来学习上的帮助，请大家多多支持golang学习网！更多关于文章的相关知识，也可关注golang学习网公众号。