Laravel 路由与控制器最佳实践实战：以 Coolify 路由系统为例

本文基于 Coolify 仓库内置的 routing.md 路由最佳实践规则展开，完整覆盖隐式路由模型绑定、作用域绑定、资源控制器、瘦控制器与 Form Request 类型提示五项核心规范，并结合 Coolify 真实的 RouteServiceProvider、routes/api.php 与 API 控制器实现，帮助读者理解这些规范在自托管 PaaS 这类大型 Laravel 项目中的落地方式、适用边界与替代方案。

Coolify 的路由体系全景

理解最佳实践之前，先看 Coolify 如何组织路由。RouteServiceProvider 的 boot() 方法将应用路由划分为三个互不干扰的组：

$this->routes(function () {
    Route::middleware('api')
        ->prefix('api')
        ->group(base_path('routes/api.php'));

    Route::prefix('webhooks')
        ->group(base_path('routes/webhooks.php'));

    Route::middleware('web')
        ->group(base_path('routes/web.php'));
});

• API 路由：统一挂 api 中间件组并自动加 api 前缀，入口为 routes/api.php；
• Webhook 路由：加 webhooks 前缀，用于接收 GitHub/GitLab 等外部事件回调，routes/webhooks.php 单独维护；
• Web 路由：挂 web 中间件组，承载 Livewire 主导的管理界面，入口为 routes/web.php。

此外，同文件的 configureRateLimiting() 集中注册了 api、login、two-factor、forgot-password、magic-link 等具名限流器。以 routes/web.php 第 112 行 为例，Route::post('/forgot-password', ...)->middleware('throttle:forgot-password') 引用的正是这里定义的 forgot-password 限流器——它按 IP 与归一化邮箱身份双重维度限制（10 分钟内 3 次）。这种「限流器集中定义、路由按需引用」的组织方式，是路由层保持整洁的基础设施之一。

使用隐式路由模型绑定（Implicit Route Model Binding）

原文档的第一条规范：让 Laravel 从路由参数中自动解析模型，避免在控制器里手写 findOrFail。

错误示例：

public function show(int $id)
{
    $post = Post::findOrFail($id);
}

正确示例：

public function show(Post $post)
{
    return view('posts.show', ['post' => $post]);
}

其原理是：当控制器方法签名中出现与路由参数同名（或可匹配）的 Eloquent 类型提示时，框架会在方法执行前按路由键（默认 id）从数据库查出模型并注入，查不到则自动返回 404。

Coolify 中的对照实践：UUID 路由参数

Coolify 对外 API 不使用自增 ID，而是全局 UUID。BaseModel 在 creating 事件中为所有资源自动生成 uuid：

static::creating(function (Model $model) {
    // Generate a UUID if one isn't set
    if (! $model->uuid) {
        $model->uuid = new_public_id();
    }
});

因此 routes/api.php 中的资源路由参数均为 {uuid}，如 Route::get('/projects/{uuid}', ...)（第 97 行）。值得注意的是，Coolify 的 API 控制器并未采用隐式绑定，而是在方法内显式查询。例如 CloudProviderTokensController 中：

$token = CloudProviderToken::whereTeamId($teamId)->whereUuid($request->route('uuid'))->first();

从源码结构看，这是一个有意识的取舍：显式 whereTeamId(...)->whereUuid(...) 让「团队作用域过滤」与「资源定位」写进同一条查询，天然规避了越权访问其他团队资源的风险。对于多租户 UUID API 而言，这比依赖默认路由键的隐式绑定更可控。而框架原生的隐式绑定机制，Coolify 在基础控制器中仍有体现——Controller::email_verify() 直接取 $request->route('id') 与当前用户主键做 hash_equals 比对后完成邮箱验证，展示了路由参数参与业务校验的标准用法。

实践要点：单一资源、以 id 定位的内部路由优先用隐式绑定；多租户、UUID 标识、需要额外过滤条件（团队、软删除策略等）的场景，显式作用域查询往往更安全。

为嵌套资源使用作用域绑定（Scoped Bindings）

原文档第二条规范：嵌套路由应使用 scopeBindings()，自动强制父子归属关系：

Route::get('/users/{user}/posts/{post}', function (User $user, Post $post) {
    // $post is automatically scoped to $user
})->scopeBindings();

没有作用域绑定时，/users/5/posts/1 可能解析出 user 5 与 post 1（post 1 可能属于别的用户）；加上 scopeBindings() 后，框架会用已解析的 $user 约束 $post 的查询，查不到即 404。

Coolify 的等价实现：中间件 + 查询作用域

Coolify 的 API 没有嵌套 URL 路径表达归属，而是用「路由中间件 + 查询过滤」达成等价效果。以 routes/api.php 第 50-60 行 为例：

Route::group([
    'middleware' => ['auth:sanctum', 'api.token.team', 'api.ability:write'],
    'prefix' => 'v1',
], function () {
    // ...
});

api.token.team 中间件从 Personal Access Token 解析出所属团队并注入请求上下文，后续控制器统一以该团队为父作用域查询子资源。例如 DestinationsController 第 59 行：

return StandaloneDocker::with('server:id,uuid,team_id,ip,user,port,private_key_id')
    ->whereHas('server', fn ($query) => $query->whereTeamId($teamId))
    ->whereUuid($uuid)->first()
    ?? SwarmDocker::with('server:id,uuid,team_id')->whereHas('server', fn ($query) => $query->whereTeamId($teamId))
        ->whereUuid($uuid)->firstOrFail();

这里 whereTeamId($teamId) 就是手动版的「作用域绑定」：无论 URL 里给什么 uuid，查询结果都被限定在当前 token 所属团队内。两条路线的对照是：

机制	表达位置	适用形态
scopeBindings()	路由定义处，依赖嵌套路径参数	RESTful 嵌套资源 /users/{user}/posts/{post}
中间件 + whereTeamId()	控制器查询处，参数为扁平 uuid	多租户 API /cloud-tokens/{uuid}

实践要点：嵌套资源用 scopeBindings() 声明式约束；扁平化多租户 API 则把「父作用域」固化到中间件与查询构造中，两者目标一致——杜绝跨归属访问。

使用资源控制器组织 RESTful 端点

原文档第三条规范：对 RESTful 端点使用 Route::resource() 或 apiResource()：

Route::resource('posts', PostController::class);
// In routes/api.php — the /api prefix is applied automatically
Route::apiResource('posts', Api\PostController::class);

resource() 会一次性生成 index/store/show/update/destroy 七个标准方法映射，apiResource() 则省略 index/show 两个非标准方法。

Coolify 的「手写 REST」变体

Coolify 在 routes/api.php 中没有使用 apiResource()，而是为每个资源显式声明各 HTTP 动词的映射，例如云厂商凭据资源（第 124-129 行）：

Route::get('/cloud-tokens', [CloudProviderTokensController::class, 'index'])->middleware(['api.ability:read']);
Route::post('/cloud-tokens', [CloudProviderTokensController::class, 'store'])->middleware(['api.ability:write']);
Route::get('/cloud-tokens/{uuid}', [CloudProviderTokensController::class, 'show'])->middleware(['api.ability:read']);
Route::patch('/cloud-tokens/{uuid}', [CloudProviderTokensController::class, 'update'])->middleware(['api.ability:write']);
Route::delete('/cloud-tokens/{uuid}', [CloudProviderTokensController::class, 'destroy'])->middleware(['api.ability:write']);

对比标准 resource() 的七个动作，这里有两个明显差异：其一，Coolify 的「更新」用 PATCH 而非 resource 默认的 PUT，且额外挂载 validate 动作（POST /cloud-tokens/{uuid}/validate）；其二，每个动词单独挂能力中间件——读操作用 api.ability:read，写操作用 api.ability:write。从源码结构看，这种细粒度是按操作级别鉴权的需要：apiResource() 的组级中间件无法区分各动词的权限，而 Coolify 的 token 能力模型（read/write/deploy 等）要求逐路由声明。

实践要点：CRUD 完全标准、权限统一时，resource()/apiResource() 是最省事的写法；当各 HTTP 动词需要不同鉴权级别、或存在非标准动作（validate、deploy 等）时，显式逐条声明路由反而更清晰，Coolify 的 API 就是后者的典型案例。

保持控制器纤薄（Keep Controllers Thin）

原文档第四条规范：单个控制器方法控制在 10 行以内，业务逻辑抽取到 action 或 service 类。

错误示例（胖控制器）：

public function store(Request $request)
{
    $validated = $request->validate([...]);
    if ($request->hasFile('image')) {
        $request->file('image')->move(public_path('images'));
    }
    $post = Post::create($validated);
    $post->tags()->sync($validated['tags']);
    event(new PostCreated($post));
    return redirect()->route('posts.show', $post);
}

正确示例（瘦控制器）：

public function store(StorePostRequest $request, CreatePostAction $create)
{
    $post = $create->execute($request->validated());

    return redirect()->route('posts.show', $post);
}

Coolify 的分层结构佐证

Coolify 的业务逻辑确实没有堆积在控制器里，而是按领域拆入 app/Actions/ 目录：Application/（应用部署相关）、Server/（16 个文件，服务器生命周期操作）、Database/（13 个文件，数据库操作）、Stripe/（订阅与计费）等子目录。API 控制器与 Livewire 组件负责「输入接收 + 输出返回」，重活委托给这些 Action 类——与文档中 CreatePostAction 的注入模式一致。

此外，基础控制器 Controller 自身就展示了「横切关注点集中管理」：

class Controller extends BaseController
{
    use AuthorizesRequests, ValidatesRequests;
    // ...
}

AuthorizesRequests 提供策略/权限校验能力，ValidatesRequests 提供 $request->validate() 与 Form Request 支持。像 acceptLink() 这类方法虽然超过 10 行，但它把「解密 token → 事务内锁行 → 接受邀请」整段放进 DB::transaction 闭包中，方法体本身仍是编排代码而非业务细节，符合「控制器做编排、Action 做业务」的分层思想。

类型提示 Form Request

原文档第五条规范：通过类型提示 Form Request，让验证与授权在控制器方法执行前自动触发。

错误示例（验证逻辑写在方法体里）：

public function store(Request $request): RedirectResponse
{
    $validated = $request->validate([
        'title' => ['required', 'max:255'],
        'body' => ['required'],
    ]);

    Post::create($validated);

    return redirect()->route('posts.index');
}

正确示例：

public function store(StorePostRequest $request): RedirectResponse
{
    Post::create($request->validated());

    return redirect()->route('posts.index');
}

Form Request 类把 rules()、authorize()、messages() 聚拢到独立类中，路由解析阶段即完成「授权判定 + 字段验证」，控制器方法入口处的 $request->validated() 直接拿到干净数据。

Coolify 的现状与启示

在 Coolify 中，输入验证主要分布在两处：一是基础控制器内的内联验证，如 Controller::forgot_password() 中的 $request->validate([Fortify::email() => 'required|email'])；二是 Livewire 组件内部——Coolify 的 Web 界面由约 280 个 Livewire 组件构成（见 app/Livewire 目录），组件的 validated() 钩子承担了大部分表单校验职责。当前仓库中未见独立的 Form Request 类，从源码结构看，这是一个可以对照本规范持续改进的方向：将 Livewire 组件与 API 控制器中重复出现的验证规则抽成 Form Request，可同时获得「方法执行前验证」与「规则可复用」两个收益。

小结：五项规范的落地对照

规范	文档要求	Coolify 现状
隐式模型绑定	类型提示模型自动解析	多租户 API 改用 whereTeamId()->whereUuid() 显式作用域查询，安全性更高
作用域绑定	scopeBindings() 约束嵌套资源	api.token.team 中间件 + 团队过滤查询实现等价约束
资源控制器	resource()/apiResource()	显式逐动词声明，为每个 HTTP 动词挂载细粒度能力中间件
瘦控制器	方法 < 10 行，逻辑外提	业务逻辑按领域拆分至 app/Actions 目录
Form Request	类型提示触发前置验证	目前以内联验证与 Livewire 组件钩子为主，是可改进点

这套规则文件与同目录下 SKILL.md 共同构成 Coolify 仓库的 Laravel 工程实践基准。对阅读者的启示是：最佳规范是「默认项」而非「教条」——当隐式绑定在默认路由键下表达不了多租户语义时，显式作用域查询是合理偏离；当 resource() 的组级中间件满足不了逐动词鉴权时，显式路由声明是合理偏离。关键在于偏离有明确理由，且父子归属约束始终存在。