laravel-api

介绍如何使用 Laravel 构建 RESTful API：使用 API Resources 转换响应、使用 Sanctum 进行身份验证、速率限制、路由版本控制、Form Request 验证、分页（偏移量／游标），以及通过 HTTP 客户端调用外部 API。对于符合 JSON:API 规范的端点（稀疏字段集、包含关系、链接），请改用 laravel-jsonapi。

Laravel API 开发

Agent 工作流（强制）

在进行任何实现之前，必须并行启动 3 个 Agent，每次调用一个 Agent，并指定 name：

1. fuse-ai-pilot:explore-codebase - 分析现有 API 模式
2. fuse-ai-pilot:research-expert - 通过 Context7 核实 Laravel API 文档
3. mcp__context7__query-docs - 检查 API Resources 和 Sanctum 模式

实现完成后，运行 fuse-ai-pilot:sniper 进行验证。

---

概览

使用 Laravel 和 API Resources 转换响应，并使用 Sanctum 进行身份验证，构建 RESTful API。

组件	用途
Controllers	处理请求并委派给服务
Form Requests	验证输入并授权操作
API Resources	将模型转换为 JSON
Middleware	身份验证、速率限制、CORS
Routes	带分组的版本化端点
Pagination	偏移量／游标分页
HTTP Client	调用外部 API

---

关键规则

1. 始终使用 API Resources - 切勿直接返回 Eloquent 模型
2. 路由版本控制 - 使用 /v1/、/v2/ 作为前缀
3. 验证所有输入 - 使用 Form Requests，而非内联验证
4. 速率限制 - 为每条路由配置限制
5. 响应保持一致 - 使用相同结构和适当的状态码
6. 使用服务 - 保持控制器精简
7. 预加载 - 在分页前使用 with() 防止 N+1 问题

---

参考指南

核心概念

主题	参考文档	适用场景
Routing	routing.md	定义版本化 API 路由
Controllers	controllers.md	控制器模式、资源方法
Middleware	middleware.md	路由保护、请求筛选
Validation	validation.md	Form Requests、验证规则

请求／响应

主题	参考文档	适用场景
Requests	requests.md	访问输入、文件、标头
Responses	responses.md	API Resources、状态码
Pagination	pagination.md	偏移量／游标分页

进阶

主题	参考文档	适用场景
Rate Limiting	rate-limiting.md	节流配置
HTTP Client	http-client.md	调用外部 API
URLs	urls.md	URL 生成、签名 URL
Strings	strings.md	字符串辅助函数、UUID、slug
Redirects	redirects.md	重定向响应

---

模板（代码示例）

控制器与路由

模板	用途
ApiController.php.md	包含服务的完整 CRUD 控制器
api-routes.md	带中间件的版本化路由
routing-examples.md	详细的路由模式

验证与资源

模板	用途
FormRequest.php.md	Store／Update Form Requests
validation-rules.md	所有验证规则参考
ApiResource.php.md	包含关联关系的 Resource

外部 API

模板	用途
HttpClientService.php.md	可复用的 HTTP 客户端服务

---

快速参考

资源响应

return PostResource::collection($posts);
return PostResource::make($post);

状态码

return PostResource::make($post)->response()->setStatusCode(201);
return response()->json(null, 204);

表单请求

public function store(StorePostRequest $request): JsonResponse
{
    $post = $this->service->create($request->validated());
    return PostResource::make($post)->response()->setStatusCode(201);
}

速率限制

Route::middleware('throttle:60,1')->group(fn () => ...);

版本化路由

Route::prefix('v1')->group(function () {
    Route::apiResource('posts', PostController::class);
});

分页

return PostResource::collection(Post::paginate(15));

---

功能矩阵

功能	状态	参考
RESTful 控制器	✅	controllers.md
API 资源	✅	responses.md
表单请求验证	✅	validation.md
路由版本控制	✅	routing.md
路由模型绑定	✅	routing.md
中间件	✅	middleware.md
速率限制	✅	rate-limiting.md
分页	✅	pagination.md
游标分页	✅	pagination.md
HTTP 客户端	✅	http-client.md
签名 URL	✅	urls.md
JSON 响应	✅	responses.md

---

Laravel 13 说明

API 资源的属性

Laravel 13 引入了 #[Collects] 和 #[PreserveKeys]，用于通过 PHP 属性配置 ResourceCollections。

use Illuminate\Http\Resources\Json\ResourceCollection;
use Illuminate\Http\Resources\Attributes\Collects;
use Illuminate\Http\Resources\Attributes\PreserveKeys;

#[Collects(PostResource::class)]
#[PreserveKeys]
final class PostCollection extends ResourceCollection {}

JSON:API 合规性

对于 JSON:API API（稀疏字段集、包含项、链接），请参阅 [[laravel-jsonapi]]，其中介绍了 ?include=、?fields[type]= 和符合规范的分页。

最佳实践

应该

• 每个公开的 JSON 响应都使用 API 资源（JsonResource）
• 通过 URL（/api/v1）而非请求头进行版本控制（易读、可缓存）
• 按用户和 IP 分别限制速率（throttle:60,1 + 自定义限制器）
• 在编写端点代码前，使用 OpenAPI/Scribe 编写文档
• 大型列表优先使用 cursor() 分页（稳定、高效）

不应该

• 直接返回 Eloquent Model（会泄露敏感列）
• 混淆 HTTP 状态码（验证失败始终返回 422，区分 401 和 403）
• 跳过表单请求验证（绝不要在控制器中验证）
• 向外部公开自增 ID（优先使用 UUID/ULID）
• 忘记为外部 webhook 豁免 PreventRequestForgery