3.7 路由注册

:::tip 概述全部 API 路由定义在 routes/api.php 中。公开接口（无需认证）放在中间件组外面，认证接口统一绑定 auth.jwt + tenant + demo + log.operation 中间件组。 :::

路由文件位置

routes/api.php

文件结构（来自项目实际代码）

<?php

use App\Http\Controllers\Api;
use Illuminate\Support\Facades\Route;

/*
|--------------------------------------------------------------------------
| API Routes
|--------------------------------------------------------------------------
|
| 公开接口放在 middleware 组外面，天然排除认证。
| 认证接口统一使用 auth.jwt + tenant + demo + log.operation 中间件。
| demo 位于 log.operation 之前：演示模式下被拦截的请求不写操作日志。
|
*/

// ===== 公开接口（无需认证）=====
Route::post('login', [Api\AuthController::class, 'login']);
Route::post('refresh', [Api\AuthController::class, 'refresh']);
Route::get('captcha', [Api\CaptchaController::class, 'generate']);
Route::post('oauth2/token', [Api\AuthController::class, 'token']);
Route::get('oauth2/check/token', [Api\AuthController::class, 'checkToken']);

// ===== 认证接口 =====
Route::middleware(['auth.jwt', 'tenant', 'demo', 'log.operation'])->group(function () {

    // --- 登出 ---
    Route::post('logout', [Api\AuthController::class, 'logout']);

    // --- 个人中心 ---
    Route::get('index/getUser', [Api\IndexController::class, 'getUser']);

    // ... 其他业务路由
});

Example 模块路由（来自项目实际代码）

// routes/api.php（认证中间件组内）

// --- 案例演示 ---
Route::get('example/page', [Api\ExampleController::class, 'page']);
Route::get('example/list', [Api\ExampleController::class, 'list']);
Route::get('example/detail/{id}', [Api\ExampleController::class, 'detail']);
Route::post('example/add', [Api\ExampleController::class, 'add']);
Route::put('example/update', [Api\ExampleController::class, 'update']);
Route::delete('example/delete/{id}', [Api\ExampleController::class, 'delete']);
Route::delete('example/batchDelete', [Api\ExampleController::class, 'batchDelete']);
Route::get('example/export', [Api\ExampleController::class, 'export']);
Route::post('example/import', [Api\ExampleController::class, 'import']);

路由格式说明

Route::HTTP方法('路径', [控制器类::class, '方法']);

HTTP 方法	用途	路径格式	示例
GET	查询	`{模块}/page`、`{模块}/detail/{id}`	`GET /api/example/page`
POST	新增/导入	`{模块}/add`、`{模块}/import`	`POST /api/example/add`
DELETE	批量删除	`{模块}/batchDelete`	`DELETE /api/example/batchDelete`
PUT	修改	`{模块}/update`	`PUT /api/example/update`
DELETE	删除	`{模块}/delete/{id}`	`DELETE /api/example/delete/1`

:::tip 路径参数风格本项目统一使用 Laravel 标准 {id} 路径参数；批量删除使用 batchDelete 路径且为 DELETE 方法（请求体仍传 ids 数组——本项目 DELETE 接口携带 body）。前缀 /api 由 bootstrap/app.php 的 withRouting(api: ...) 默认前缀统一添加。 :::

标准路由模板

每个业务模块通常包含以下 9 条路由（全部放在认证中间件组内）：

// --- 模块名 ---
Route::get('{模块}/page', [Api\XxxController::class, 'page']);            // 分页列表
Route::get('{模块}/list', [Api\XxxController::class, 'list']);            // 全量列表（可选）
Route::get('{模块}/detail/{id}', [Api\XxxController::class, 'detail']);    // 详情
Route::post('{模块}/add', [Api\XxxController::class, 'add']);             // 新增
Route::put('{模块}/update', [Api\XxxController::class, 'update']);        // 修改
Route::delete('{模块}/delete/{id}', [Api\XxxController::class, 'delete']); // 删除
Route::delete('{模块}/batchDelete', [Api\XxxController::class, 'batchDelete']); // 批量删除
Route::get('{模块}/export', [Api\XxxController::class, 'export']);        // 导出（可选）
Route::post('{模块}/import', [Api\XxxController::class, 'import']);       // 导入（可选）

中间件组说明

别名	类	职责
`auth.jwt`	`Authenticate`	JWT 解析、`#[Permission]` 反射鉴权、用户信息注入
`tenant`	`ResolveTenant`	租户上下文解析与注入
`demo`	`DemoMiddleware`	演示模式拦截写操作（`#[DemoAllow]` 放行）
`log.operation`	`LogOperation`	操作日志采集（响应后落库）

跨域 Cors、强制 JSON ForceJsonResponse、真实 IP ProxyMiddleware 前置于 API 中间件组（bootstrap/app.php 的 $middleware->api(prepend:)），对全部 /api 请求生效，无需在路由上声明。演示模式 DemoMiddleware（别名 demo）位于认证路由组内（tenant 与 log.operation 之间）。详见附录 F 中间件执行顺序。

:::warning 公开接口放组外 login / refresh / captcha / oauth2 等公开接口必须放在中间件组外面（如上例），不要在中间件内部做排除——这是项目的路由约定。 :::

验证路由注册

# 查看所有已注册路由（含中间件与方法名）
php artisan route:list

# 测试路由是否正确（需先登录获取 token，见 2.7 第一个接口调试）
curl http://localhost:8000/api/example/page -H "Authorization: Bearer <token>"

5.4 KiB Raw Blame History Unescape Escape