laravel-api

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Laravel API Development

Laravel API 开发

Agent Workflow (MANDATORY)

Agent 工作流（强制要求）

Before ANY implementation, use

TeamCreate

to spawn 3 agents:

fuse-ai-pilot:explore-codebase - Analyze existing API patterns
fuse-ai-pilot:research-expert - Verify Laravel API docs via Context7
mcp__context7__query-docs - Check API Resources and Sanctum patterns

After implementation, run fuse-ai-pilot:sniper for validation.

在进行任何实现之前，使用

TeamCreate

生成3个Agent：

fuse-ai-pilot:explore-codebase - 分析现有API模式
fuse-ai-pilot:research-expert - 通过Context7验证Laravel API文档
mcp__context7__query-docs - 检查API Resources和Sanctum模式

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

Overview

概述

Build RESTful APIs with Laravel using API Resources for response transformation and Sanctum for authentication.

Component	Purpose
Controllers	Handle requests, delegate to services
Form Requests	Validate input, authorize actions
API Resources	Transform models to JSON
Middleware	Auth, rate limiting, CORS
Routes	Versioned endpoints with groups
Pagination	Offset/cursor pagination
HTTP Client	Consume external APIs

使用Laravel构建RESTful API，借助API Resources实现响应转换，通过Sanctum完成认证。

组件	用途
控制器	处理请求，将任务委托给服务层
表单请求	验证输入，授权操作
API Resources	将模型转换为JSON
中间件	认证、速率限制、跨域资源共享
路由	带分组的版本化端点
分页	偏移量/游标分页
HTTP客户端	调用外部API

Critical Rules

核心规则

Always use API Resources - Never return Eloquent models directly
Versioned routes - Prefix with
```
/v1/
```
,
```
/v2/
```
Validate all input - Use Form Requests, not inline validation
Rate limiting - Configure per-route limits
Consistent responses - Same structure, proper status codes
Use services - Keep controllers thin
Eager load - Prevent N+1 with
```
with()
```
before pagination

始终使用API Resources - 切勿直接返回Eloquent模型
版本化路由 - 以
```
/v1/
```
、
```
/v2/
```
作为前缀
验证所有输入 - 使用表单请求，而非内联验证
速率限制 - 按路由配置限制
统一响应格式 - 保持结构一致，使用正确的状态码
使用服务层 - 保持控制器轻量化
预加载关联 - 在分页前使用
```
with()
```
避免N+1查询问题

Reference Guide

参考指南

Core Concepts

核心概念

Topic	Reference	When to consult
Routing	routing.md	Defining versioned API routes
Controllers	controllers.md	Controller patterns, resource methods
Middleware	middleware.md	Route protection, request filtering
Validation	validation.md	Form Requests, validation rules

主题	参考文档	适用场景
路由	routing.md	定义版本化API路由
控制器	controllers.md	控制器模式、资源方法
中间件	middleware.md	路由保护、请求过滤
验证	validation.md	表单请求、验证规则

Request/Response

请求与响应

Topic	Reference	When to consult
Requests	requests.md	Accessing input, files, headers
Responses	responses.md	API Resources, status codes
Pagination	pagination.md	Offset/cursor pagination

主题	参考文档	适用场景
请求	requests.md	获取输入、文件、请求头
响应	responses.md	API Resources、状态码
分页	pagination.md	偏移量/游标分页

Advanced

进阶内容

Topic	Reference	When to consult
Rate Limiting	rate-limiting.md	Throttle configuration
HTTP Client	http-client.md	Consuming external APIs
URLs	urls.md	URL generation, signed URLs
Strings	strings.md	String helpers, UUIDs, slugs
Redirects	redirects.md	Redirect responses

主题	参考文档	适用场景
速率限制	rate-limiting.md	限流配置
HTTP客户端	http-client.md	调用外部API
URL	urls.md	URL生成、签名URL
字符串	strings.md	字符串助手、UUID、友好链接后缀
重定向	redirects.md	重定向响应

Templates (Code Examples)

模板（代码示例）

Controllers & Routes

控制器与路由

Template	Purpose
ApiController.php.md	Complete CRUD controller with service
api-routes.md	Versioned routes with middleware
routing-examples.md	Detailed routing patterns

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

Validation & Resources

验证与资源

Template	Purpose
FormRequest.php.md	Store/Update Form Requests
validation-rules.md	All validation rules reference
ApiResource.php.md	Resource with relationships

模板	用途
FormRequest.php.md	创建/更新表单请求
validation-rules.md	所有验证规则参考
ApiResource.php.md	包含关联关系的资源类

External APIs

外部API

Template	Purpose
HttpClientService.php.md	Reusable HTTP client service

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

Quick Reference

快速参考

Resource Response

资源响应

php

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

php

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

Status Codes

状态码

php

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

php

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

Form Request

表单请求

php

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

php

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

Rate Limiting

速率限制

php

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

php

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

Versioned Routes

版本化路由

php

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

php

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

Pagination

分页

php

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

php

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

Feature Matrix

功能矩阵

Feature	Status	Reference
RESTful Controllers	✅	controllers.md
API Resources	✅	responses.md
Form Request Validation	✅	validation.md
Route Versioning	✅	routing.md
Route Model Binding	✅	routing.md
Middleware	✅	middleware.md
Rate Limiting	✅	rate-limiting.md
Pagination	✅	pagination.md
Cursor Pagination	✅	pagination.md
HTTP Client	✅	http-client.md
Signed URLs	✅	urls.md
JSON Responses	✅	responses.md

功能	状态	参考文档
RESTful控制器	✅	controllers.md
API Resources	✅	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