532 lines
15 KiB
Markdown
532 lines
15 KiB
Markdown
# 4.2 请求处理链路
|
||
|
||
:::tip 链路概览
|
||
一个典型的 API 请求经过以下阶段：浏览器 → Nginx → CORS 中间件 → Auth 中间件（JWT 认证 + RBAC 鉴权）→ Tenant 中间件 → Demo 中间件 → Log 中间件 → 控制器 → 逻辑层 → 模型层 → 数据库 → 响应序列化 → 浏览器
|
||
:::
|
||
|
||
本节以 `POST /api/example/add` 添加案例为例，逐步拆解完整链路。
|
||
|
||
## 第一阶段：网络层
|
||
|
||
### 1. 浏览器发起请求
|
||
|
||
```typescript
|
||
// 前端 Axios 调用（ui/src/api/tool/example.ts）
|
||
export function exampleAdd(data: any) {
|
||
return http.request({
|
||
url: '/example/add',
|
||
method: 'POST',
|
||
data, // { name: '测试案例', status: 1, sort: 0 }
|
||
});
|
||
}
|
||
```
|
||
|
||
前端通过 Axios 发起 HTTP POST 请求，携带：
|
||
- `Authorization: Bearer <JWT Token>` 请求头（由请求拦截器自动添加）
|
||
- `Content-Type: application/json` 请求头
|
||
- JSON 请求体
|
||
|
||
### 2. Nginx 反向代理（生产环境）
|
||
|
||
```nginx
|
||
location /api/ {
|
||
proxy_pass http://127.0.0.1:8000;
|
||
proxy_set_header Host $host;
|
||
proxy_set_header X-Real-IP $remote_addr;
|
||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||
}
|
||
```
|
||
|
||
开发环境下，Vite 开发服务器将 `/api` 请求代理到后端：
|
||
|
||
```typescript
|
||
// ui/vite.config.ts
|
||
server: {
|
||
proxy: {
|
||
'/api': {
|
||
target: 'http://localhost:8000',
|
||
changeOrigin: true,
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
## 第二阶段：路由解析
|
||
|
||
### 3. ThinkPHP 入口
|
||
|
||
```text
|
||
public/index.php → 引导框架 → 路由解析 route/app.php
|
||
```
|
||
|
||
### 4. 路由匹配
|
||
|
||
```php
|
||
// route/app.php
|
||
|
||
// 公开接口（无需认证）
|
||
Route::group('api', function () {
|
||
Route::post('login', 'LoginController/login');
|
||
Route::get('captcha', 'LoginController/captcha');
|
||
});
|
||
|
||
// 需认证接口
|
||
Route::group('api', function () {
|
||
Route::group('example', function () {
|
||
Route::post('add', 'ExampleController/add'); // ← 匹配到此处
|
||
});
|
||
})->middleware([
|
||
\app\middleware\AuthMiddleware::class, // JWT 认证 + 权限校验
|
||
\app\middleware\TenantMiddleware::class, // 租户上下文
|
||
\app\middleware\DemoMiddleware::class, // 演示环境拦截
|
||
\app\middleware\LogMiddleware::class, // 操作日志
|
||
]);
|
||
```
|
||
|
||
路由匹配到 `POST api/example/add` → `ExampleController::add()`，同时绑定四个中间件。
|
||
|
||
## 第三阶段：中间件链（按顺序执行）
|
||
|
||
### 5. CorsMiddleware（全局中间件）
|
||
|
||
```php
|
||
// app/middleware/CorsMiddleware.php
|
||
|
||
public function handle(Request $request, \Closure $next): Response
|
||
{
|
||
// 处理 OPTIONS 预检请求
|
||
if ($request->isOptions()) {
|
||
$response = Response::create('', 'html', 204);
|
||
} else {
|
||
$response = $next($request);
|
||
}
|
||
|
||
// 设置跨域响应头
|
||
$response->header([
|
||
'Access-Control-Allow-Origin' => $origin,
|
||
'Access-Control-Allow-Methods' => 'GET, POST, PUT, DELETE, PATCH, OPTIONS',
|
||
'Access-Control-Allow-Headers' => 'Content-Type, Authorization, ...',
|
||
'Access-Control-Allow-Credentials' => 'true',
|
||
]);
|
||
|
||
return $response;
|
||
}
|
||
```
|
||
|
||
- 每个请求都经过（全局中间件）
|
||
- OPTIONS 预检请求直接返回 204
|
||
- 普通请求附加 CORS 响应头
|
||
|
||
### 6. AuthMiddleware（JWT 认证 + 权限校验）
|
||
|
||
```php
|
||
// app/middleware/AuthMiddleware.php
|
||
|
||
public function handle(Request $request, \Closure $next): Response
|
||
{
|
||
// 1. 检查排除路由（login/captcha 等直接放行）
|
||
$path = $request->pathinfo();
|
||
foreach ($exceptList as $except) {
|
||
if (strpos($path, $except) !== false) {
|
||
return $next($request);
|
||
}
|
||
}
|
||
|
||
// 2. 从请求头获取 Token
|
||
$token = Jwt::getTokenFromHeader();
|
||
if (empty($token)) {
|
||
return json(['code' => 401, 'msg' => '未提供认证令牌']);
|
||
}
|
||
|
||
// 3. 解析 Token，校验签名和有效期
|
||
try {
|
||
$decoded = Jwt::decode($token);
|
||
} catch (\RuntimeException $e) {
|
||
return json(['code' => 401, 'msg' => $e->getMessage()]);
|
||
}
|
||
|
||
// 4. 校验 token 类型必须为 access
|
||
if (($decoded->type ?? '') !== 'access') {
|
||
return json(['code' => 401, 'msg' => '无效的认证令牌']);
|
||
}
|
||
|
||
// 5. 注入用户信息到 Request
|
||
$request->userInfo = $decoded;
|
||
|
||
// 6. 读取 #[Permission] 注解，校验权限
|
||
$permission = AttributeService::getPermission($controllerClass, $action);
|
||
if ($permission !== null) {
|
||
$hasPermission = $this->checkPermission($decoded->uid, $permission->code);
|
||
if (!$hasPermission) {
|
||
return json(['code' => 403, 'msg' => '无访问权限']);
|
||
}
|
||
}
|
||
|
||
return $next($request);
|
||
}
|
||
```
|
||
|
||
处理流程：
|
||
|
||
```text
|
||
请求进入
|
||
│
|
||
├─ 路径在排除列表？ → 直接放行
|
||
│
|
||
├─ 提取 Authorization: Bearer <token>
|
||
│ └─ 为空 → 返回 401
|
||
│
|
||
├─ Jwt::decode($token) 解析验证
|
||
│ └─ 失败（过期/签名错误）→ 返回 401
|
||
│
|
||
├─ 校验 type === 'access'
|
||
│ └─ 不是 → 返回 401
|
||
│
|
||
├─ 注入 $request->userInfo = {uid, username, type, exp}
|
||
│
|
||
├─ 读取 #[Permission] 注解
|
||
│ ├─ 无注解 → 跳过权限校验
|
||
│ └─ 有注解 → checkPermission()
|
||
│ ├─ uid === 1 → 直接放行（超级管理员）
|
||
│ └─ 查询 UserRole → RoleMenu → Menu.permission
|
||
│ ├─ 包含 → 放行
|
||
│ └─ 不包含 → 返回 403
|
||
│
|
||
└─ 放行 → 进入下一个中间件
|
||
```
|
||
|
||
### 7. TenantMiddleware（租户上下文）
|
||
|
||
```php
|
||
// app/middleware/TenantMiddleware.php
|
||
|
||
public function handle(Request $request, \Closure $next): Response
|
||
{
|
||
$userInfo = $request->userInfo ?? null;
|
||
$userId = $userInfo->uid ?? 0;
|
||
|
||
$user = User::find($userId);
|
||
$tenantId = $user->tenant_id ?? 0;
|
||
|
||
// 注入租户上下文
|
||
$request->tenantId = $tenantId;
|
||
$request->isSuperAdmin = ($tenantId == 0);
|
||
|
||
// 非超级管理员校验租户状态
|
||
if ($tenantId > 0) {
|
||
$tenant = Tenant::find($tenantId);
|
||
if (!$tenant || $tenant->status != 1) {
|
||
return json(['code' => 403, 'msg' => '租户已被禁用']);
|
||
}
|
||
if ($tenant->expire_time && strtotime($tenant->expire_time) < time()) {
|
||
return json(['code' => 403, 'msg' => '租户已过期']);
|
||
}
|
||
$request->tenantInfo = $tenant;
|
||
}
|
||
|
||
return $next($request);
|
||
}
|
||
```
|
||
|
||
注入内容：
|
||
- `$request->tenantId` — 租户 ID（0=超级管理员）
|
||
- `$request->isSuperAdmin` — 是否超级管理员
|
||
- `$request->tenantInfo` — 租户信息对象
|
||
|
||
### 8. DemoMiddleware（演示环境拦截）
|
||
|
||
```php
|
||
// app/middleware/DemoMiddleware.php
|
||
|
||
public function handle(Request $request, \Closure $next): Response
|
||
{
|
||
// 非演示环境直接放行
|
||
if (!env('app_demo', false)) {
|
||
return $next($request);
|
||
}
|
||
|
||
// GET 请求放行（读操作）
|
||
if (strtoupper($request->method()) === 'GET') {
|
||
return $next($request);
|
||
}
|
||
|
||
// 检查 #[DemoAllow] 注解
|
||
if (AttributeService::hasDemoAllow($controllerClass, $action)) {
|
||
return $next($request);
|
||
}
|
||
|
||
// 拦截写操作
|
||
return json(['code' => 403, 'msg' => '演示环境，禁止操作']);
|
||
}
|
||
```
|
||
|
||
### 9. LogMiddleware（操作日志）
|
||
|
||
```php
|
||
// app/middleware/LogMiddleware.php
|
||
|
||
public function handle(Request $request, \Closure $next): Response
|
||
{
|
||
$startTime = microtime(true);
|
||
|
||
// 执行后续中间件和控制器
|
||
$response = $next($request);
|
||
|
||
// 写操作始终记录
|
||
if (in_array($method, ['POST', 'PUT', 'DELETE', 'PATCH'])) {
|
||
// 读取 #[Log] 注解
|
||
$logAttr = AttributeService::getLog($controllerClass, $action);
|
||
|
||
// 组装日志数据
|
||
$logData = [
|
||
'title' => $logAttr?->title ?: $path,
|
||
'type' => $logAttr?->type ?: $this->guessType($method),
|
||
'method' => $method,
|
||
'url' => $request->url(),
|
||
'param' => json_encode($request->param()),
|
||
'ip' => $requestInfo->getIp(),
|
||
'location' => $requestInfo->getIpLocation(),
|
||
'os' => $requestInfo->getOs(),
|
||
'browser' => $requestInfo->getBrowser(),
|
||
'consume_time'=> round((microtime(true) - $startTime) * 1000),
|
||
'status' => $this->detectStatus($response->getContent()),
|
||
];
|
||
|
||
// 写入数据库（失败不影响主业务）
|
||
OperationLog::create($logData);
|
||
}
|
||
|
||
return $response;
|
||
}
|
||
```
|
||
|
||
## 第四阶段：控制器层
|
||
|
||
### 10. ExampleController::add()
|
||
|
||
```php
|
||
// app/controller/ExampleController.php
|
||
|
||
#[Log('案例演示-新增记录', Log::TYPE_ADD, '新增案例演示：{name}')]
|
||
#[Permission('sys:example:add', '添加案例演示')]
|
||
public function add(): Json
|
||
{
|
||
// getJsonBody() 获取前端 POST 提交的 JSON 数据
|
||
// _add() 内部调用 $this->logic->add($data)
|
||
return parent::_add($this->logic, $this->getJsonBody());
|
||
}
|
||
```
|
||
|
||
控制器层职责：
|
||
- 通过 `#[Permission]` 声明所需权限
|
||
- 通过 `#[Log]` 声明日志信息
|
||
- 获取参数，调用 Logic 层，返回响应
|
||
|
||
## 第五阶段：逻辑层
|
||
|
||
### 11. ExampleLogic::add()
|
||
|
||
```php
|
||
// app/logic/ExampleLogic.php → 继承 BaseLogic
|
||
|
||
// BaseLogic::add() 的完整流程：
|
||
public function add(array $data): int
|
||
{
|
||
// 1. 钩子：新增前（可修改数据，抛异常可拦截）
|
||
$data = $this->beforeAdd($data);
|
||
|
||
// 2. 保留原始数据供 afterAdd 使用
|
||
$originalData = $data;
|
||
|
||
// 3. 入库前转换：camelCase → snake_case
|
||
$data = array_camel_to_snake($data);
|
||
|
||
// 4. 租户ID自动填充
|
||
$data = $this->processTenantId($data);
|
||
|
||
// 5. 文件字段：迁移临时文件，去掉域名
|
||
$data = $this->processFileFieldsOnSave($data);
|
||
|
||
// 6. 富文本字段：迁移临时文件
|
||
$data = $this->processContentFieldsOnSave($data);
|
||
|
||
// 7. 过滤非数据库字段
|
||
$saveData = $this->filterTableFields($data);
|
||
|
||
// 8. 唯一性校验
|
||
$this->checkUnique($saveData);
|
||
|
||
// 9. 写入数据库
|
||
$model = $this->getModel()->create($saveData);
|
||
$id = $model->id;
|
||
|
||
// 10. 钩子：新增后
|
||
$this->afterAdd($id, $originalData);
|
||
|
||
return $id;
|
||
}
|
||
```
|
||
|
||
## 第六阶段：模型层
|
||
|
||
### 12. BaseModel 自动处理
|
||
|
||
```php
|
||
// app/model/Example.php
|
||
class Example extends BaseModel
|
||
{
|
||
protected $name = 'example';
|
||
}
|
||
|
||
// BaseModel 提供的能力：
|
||
// 1. 全局查询范围 soft_delete → WHERE is_delete = 0
|
||
// 2. onBeforeInsert → 自动填充 create_user, create_time
|
||
// 3. onBeforeUpdate → 自动填充 update_user, update_time
|
||
```
|
||
|
||
### 13. 数据库执行
|
||
|
||
ThinkPHP ORM 将操作转换为 SQL：
|
||
|
||
```sql
|
||
INSERT INTO think_example (name, status, sort, avatar, create_user, create_time)
|
||
VALUES ('测试案例', 1, 0, '', 'admin', '2026-09-20 12:00:00');
|
||
```
|
||
|
||
## 第七阶段：响应返回
|
||
|
||
### 14. 响应序列化
|
||
|
||
```php
|
||
// BaseController::_add()
|
||
protected function _add(BaseLogic $logic, array $data): Json
|
||
{
|
||
$id = $logic->add($data);
|
||
return $this->success(['id' => $id], '添加成功');
|
||
}
|
||
|
||
// Result::success()
|
||
public static function success($data, string $msg = '操作成功'): Json
|
||
{
|
||
return json([
|
||
'code' => 0,
|
||
'ok' => true,
|
||
'msg' => $msg,
|
||
'data' => self::convertData($data), // snake_case → camelCase
|
||
]);
|
||
}
|
||
```
|
||
|
||
### 15. 浏览器接收响应
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"ok": true,
|
||
"msg": "添加成功",
|
||
"data": {
|
||
"id": 42
|
||
}
|
||
}
|
||
```
|
||
|
||
前端 Axios 拦截器统一处理：`code === 0` 时展示成功提示，否则展示错误信息。
|
||
|
||
## 完整链路流程图
|
||
|
||
```text
|
||
[浏览器]
|
||
│ POST /api/example/add
|
||
│ Authorization: Bearer <token>
|
||
▼
|
||
[Nginx / Vite Proxy] ── 反向代理转发
|
||
│
|
||
▼
|
||
[ThinkPHP 入口] ── public/index.php
|
||
│
|
||
▼
|
||
[路由解析] ── route/app.php 匹配 api/example/add
|
||
│
|
||
▼
|
||
[CorsMiddleware] ── 跨域校验通过（全局）
|
||
│
|
||
▼
|
||
[AuthMiddleware]
|
||
├─ 提取 Token → Jwt::decode()
|
||
├─ 校验 type === 'access'
|
||
├─ 注入 $request->userInfo
|
||
├─ 读取 #[Permission] 注解
|
||
├─ checkPermission() 权限校验
|
||
│ ├─ uid=1 → 跳过（超级管理员）
|
||
│ └─ UserRole → RoleMenu → Menu.permission
|
||
└─ 放行
|
||
│
|
||
▼
|
||
[TenantMiddleware]
|
||
├─ 查询用户 tenant_id
|
||
├─ 注入 $request->tenantId
|
||
└─ 校验租户状态（禁用/过期 → 403）
|
||
│
|
||
▼
|
||
[DemoMiddleware]
|
||
├─ 非演示环境 → 放行
|
||
├─ GET 请求 → 放行
|
||
└─ 有 #[DemoAllow] → 放行
|
||
│
|
||
▼
|
||
[LogMiddleware] ── 记录开始时间
|
||
│
|
||
▼
|
||
[ExampleController::add()]
|
||
├─ #[Log] 注解元数据
|
||
├─ #[Permission] 注解元数据
|
||
└─ parent::_add($this->logic, $data)
|
||
│
|
||
▼
|
||
[ExampleLogic::add()]
|
||
├─ beforeAdd() 钩子
|
||
├─ array_camel_to_snake() 键名转换
|
||
├─ processTenantId() 租户填充
|
||
├─ processFileFieldsOnSave() 文件处理
|
||
├─ filterTableFields() 字段过滤
|
||
├─ checkUnique() 唯一性校验
|
||
├─ Model::create() 写入数据库
|
||
└─ afterAdd() 钩子
|
||
│
|
||
▼
|
||
[BaseModel]
|
||
├─ onBeforeInsert → create_user, create_time
|
||
└─ 执行 SQL INSERT
|
||
│
|
||
▼
|
||
[数据库] ── 返回自增 ID
|
||
│
|
||
▼ 逐层返回响应
|
||
[Result::success()] ── {code:0, ok:true, msg:"添加成功", data:{id:42}}
|
||
│
|
||
▼
|
||
[LogMiddleware] ── 记录操作日志（写操作）
|
||
│
|
||
▼
|
||
[浏览器] ← JSON 响应
|
||
```
|
||
|
||
## 异常处理链路
|
||
|
||
当链路中发生异常时，ExceptionHandle 统一捕获并返回标准响应：
|
||
|
||
| 异常类型 | 触发场景 | 响应 |
|
||
|---------|---------|------|
|
||
| `ValidateException` | 参数验证失败 | `{code:1, msg:"参数验证失败", data:{错误明细}}` |
|
||
| `ModelNotFoundException` | 数据不存在 | `{code:1, msg:"数据不存在"}` |
|
||
| `RuntimeException (401)` | JWT 过期/无效 | `{code:1, msg:"token已过期"}` |
|
||
| `HttpException` | HTTP 错误 | `{code:1, msg:"请求错误"}` |
|
||
| `Exception` | 未捕获异常 | `{code:1, msg:"操作失败"}`（生产环境隐藏详情） |
|
||
|
||
:::warning 异常处理原则
|
||
所有异常均返回 HTTP 200 状态码，通过响应体 `code` 字段区分业务成功（0）与失败（1/401/403/404/422）。前端统一按 `code` 判断，无需处理 HTTP 状态码差异。
|
||
:::
|
||
|
||
## 总结
|
||
|
||
一个 API 请求从浏览器到数据库经过 7 个阶段、15+ 个处理节点。中间件链负责横切关注点（认证、权限、租户、日志），控制器层负责参数获取和响应返回，逻辑层负责业务处理和数据加工，模型层负责数据库操作。这种分层设计使得每一层职责单一、可独立测试。 |