API控制器必须严格隔离于Web控制器，使用专用命名空间、中间件组、基类和资源封装，否则限流、模型绑定、认证头、错误格式等均失效。
API控制器不能直接复用Web控制器，必须从命名空间、中间件、响应格式到异常处理全部隔离——否则 response()->json() 会漏掉限流、模型绑定，422 错误不带 code 字段，前端根本没法解析。
API控制器必须继承专用基类，且路由走api中间件组
很多人把 UserController 同时挂到 web.php 和 api.php，结果发现 /api/users 不触发速率限制、{id} 模型绑定失败、Authorization 头被忽略。根本原因是：Laravel 的 api 中间件组（定义在 app/Http/Kernel.php）自带 throttle:60,1 和 SubstituteBindings，而 web 组没有。
- API控制器必须放在
app/Http/Controllers/Api/下，命名空间为App\Http\Controllers\Api - 所有 API 路由必须包裹在
Route::middleware('api')或显式前缀分组中，例如：Route::prefix('v1')->middleware('api')->group(...) - 不要在控制器里手动调
$this->middleware('throttle:60,1')—— 这只是补丁，不是替代api组的完整能力
--api 生成的控制器默认不带验证和资源封装，得立刻补上
运行 php artisan make:controller PostController --api 只生成空方法骨架，没验证、没资源类、没统一响应结构。直接返回 Post::all() 会导致日期格式混乱、隐藏字段失效、关联数据未加载控制。
Laravel Cloud（cloud.laravel.com）。此技能用于处理所有 Laravel Cloud 请求，包括搜索和读取数据。只要任务涉及 Laravel Cloud，即使用此技能。
- 每个
index()/show()必须返回PostResource::collection($posts)或new PostResource($post)，不能裸数组 - 所有
store()/update()必须用FormRequest验证，而不是在方法里写$request->validate()—— 否则错误响应不走统一422格式 - 若需版本差异化响应（如 v2 多返回一个字段），新建
V2\PostResource，别在PostResource里加if ($version === 'v2')
构造函数注入服务层，但别在控制器里写数据库查询
控制器职责是“协调”，不是“执行”。看到 DB::table()、Post::where() 或复杂 withSum() 出现在控制器方法里，基本等于给后续维护埋雷。
- 把数据获取、状态计算、第三方调用等逻辑全抽到
app/Services/下的服务类中，例如PostPublicationService - 控制器只负责接收请求、调服务、转资源、返回响应；哪怕一行
$posts = Post::with('author')->latest()->get();也该进服务层 - 依赖注入必须用构造函数方式：
public function __construct(PostService $service)，别用app(PostService::class)或静态调用
异常响应格式必须与 API 版本对齐，convertExceptionToArray() 是关键开关
默认 Laravel 异常返回只有 message 和 HTTP 状态码，前端收不到 code（比如 1003 表示未登录），也没法区分业务错误和系统错误。
- 重写
app/Exceptions/Handler.php中的convertExceptionToArray()，非 debug 模式下强制返回'code' => $e->getCode() - 自定义异常类（如
InvalidPaymentMethodException）必须继承HttpException并设code = 4001 - 别在控制器里用
try/catch手动 return response()->json(...) —— 这绕过全局异常处理器，导致日志缺失、监控失效
最易被忽略的是中间件执行顺序和资源类的自动转换机制：api 中间件组必须在 auth:api 之前注册，否则模型绑定会拿不到已认证用户；PostResource 的 toArray() 方法里调用 $this->whenLoaded('comments') 时，若控制器没预加载，它不会自动查库——这不像 Eloquent accessor 那样透明。
