Laravel中如何在URL非末尾位置使用可选URL段？

现有Laravel路由配置如下：

Route::prefix('/projects/{project}')->middleware('auth:sanctum')->group(function () {
    Route::prefix('/entel')->group(function () {
        Route::post('/search-by-code', [EntelController::class, 'searchByCode']);
        // 其他Entel路由
    });
    Route::prefix('/movistar')->group(function () {
        // movistar路由
    });
    Route::prefix('/claro')->group(function () {
        // claro路由
    });    
});

对应EntelController的核心方法：

class EntelController extends Controller
{
    public function searchByCode(Request $request, Project $project)
    {
        // 业务逻辑
    }
}

需求是给Entel路由配置两种访问路径：

• /projects/1/entel/search-by-code
• /dev/projects/1/entel/search-by-code

两个路径需指向同一控制器方法，仅通过URL判断执行不同数据库操作。

尝试配置以下路由后出现错误：

Route::prefix('/{dev?}/projects/{project}')->middleware('auth:sanctum')->group(function () {
  Route::prefix('/entel')->group(function () {
     Route::post('/search-by-code', [EntelController::class, 'searchByCode']);
     // 其他Entel路由
  });
});

Route::prefix('/projects/{project}')->middleware('auth:sanctum')->group(function () {
  Route::prefix('/movistar')->group(function () {
     // movistar路由
  });
  Route::prefix('/claro')->group(function () {
     // claro路由
  });    
});

错误信息：

"message": "App\Http\Controllers\API\V1\EntelController::searchByCode(): Argument #2 ($project) must be of type App\Models\Project, string given"

单独配置Route::prefix('/dev/projects/{project}')可正常运行，但移除dev后路由失效，需解决该问题。

错误原因 #

使用可选参数{dev?}时，访问不带/dev的路径（如/projects/1/entel/search-by-code），Laravel会错误将projects解析为$dev参数的值，把1以字符串形式传递给$project参数，导致路由模型绑定失败（无法找到ID为projects的Project实例），最终抛出类型错误。

方法一：给可选参数添加匹配约束 #

通过where方法限制{dev?}只能匹配dev值，让Laravel正确识别路由结构：

Route::prefix('/{dev?}/projects/{project}')
    ->where('dev', 'dev')
    ->middleware('auth:sanctum')
    ->group(function () {
        Route::prefix('/entel')->group(function () {
            Route::post('/search-by-code', [EntelController::class, 'searchByCode']);
            // 其他Entel路由
        });
    });

// 保留原有的movistar和claro路由
Route::prefix('/projects/{project}')->middleware('auth:sanctum')->group(function () {
    Route::prefix('/movistar')->group(function () {
        // movistar路由
    });
    Route::prefix('/claro')->group(function () {
        // claro路由
    });
});

同时修改控制器方法，接收可选的$dev参数判断环境：

public function searchByCode(Request $request, Project $project, $dev = null)
{
    $isDevEnvironment = !is_null($dev);
    // 根据$isDevEnvironment执行对应数据库操作
}

方法二：拆分路由定义 #

直接单独定义两种路径的Entel路由，避免可选参数的匹配歧义：

// 不带/dev的Entel路由
Route::prefix('/projects/{project}')->middleware('auth:sanctum')->group(function () {
    Route::prefix('/entel')->group(function () {
        Route::post('/search-by-code', [EntelController::class, 'searchByCode']);
        // 其他Entel路由
    });
});

// 带/dev的Entel路由
Route::prefix('/dev/projects/{project}')->middleware('auth:sanctum')->group(function () {
    Route::prefix('/entel')->group(function () {
        Route::post('/search-by-code', [EntelController::class, 'searchByCode']);
        // 其他Entel路由
    });
});

// 原有的movistar和claro路由
Route::prefix('/projects/{project}')->middleware('auth:sanctum')->group(function () {
    Route::prefix('/movistar')->group(function () {
        // movistar路由
    });
    Route::prefix('/claro')->group(function () {
        // claro路由
    });
});

这种方式逻辑直观，适合路由数量较少的场景，控制器方法中可通过请求路径判断环境：

public function searchByCode(Request $request, Project $project)
{
    $isDevEnvironment = str_contains($request->path(), 'dev/projects');
    // 根据$isDevEnvironment执行对应数据库操作
}

内容的提问来源于stack exchange，提问作者DeveloperX