1013 lines
23 KiB
Markdown
1013 lines
23 KiB
Markdown
# 全局异常处理开发文档
|
||
|
||
## 概述
|
||
|
||
本文档详细介绍了基于Laravel 12实现的全局异常处理系统，确保所有API请求的错误响应都采用统一的JSON格式，提供完善的错误信息和调试支持。
|
||
|
||
## 系统架构
|
||
|
||
### 1. 整体结构
|
||
|
||
```
|
||
全局异常处理系统
|
||
├── 异常处理器 (Handler)
|
||
│ ├── JSON异常渲染
|
||
│ ├── 异常分类处理
|
||
│ └── 统一响应格式
|
||
├── 业务异常 (BusinessException)
|
||
│ ├── 自定义错误码
|
||
│ ├── 错误消息
|
||
│ └── 业务逻辑异常
|
||
├── 日志异常 (LogException)
|
||
│ ├── 安全日志记录
|
||
│ ├── 多通道尝试
|
||
│ └── 权限检查修复
|
||
├── 响应枚举 (ResponseEnum)
|
||
│ ├── 标准错误码
|
||
│ ├── HTTP状态码映射
|
||
│ └── 错误消息定义
|
||
└── 全局配置 (bootstrap/app.php)
|
||
├── 异常处理注册
|
||
├── 报告策略
|
||
└── 渲染策略
|
||
```
|
||
|
||
### 2. 文件结构
|
||
|
||
```
|
||
app/
|
||
├── Exceptions/
|
||
│ ├── Handler.php # 主异常处理器
|
||
│ ├── BusinessException.php # 业务异常类
|
||
│ └── LogException.php # 日志异常处理类
|
||
├── Helpers/
|
||
│ └── ResponseEnum.php # 响应码枚举
|
||
└── Http/Controllers/
|
||
└── BaseController.php # 控制器基类
|
||
|
||
bootstrap/
|
||
└── app.php # 应用启动配置
|
||
|
||
docs/
|
||
└── 全局异常处理开发文档.md # 本文档
|
||
```
|
||
|
||
## 核心组件详细说明
|
||
|
||
### 1. Handler 异常处理器
|
||
|
||
**位置**: `app/Exceptions/Handler.php`
|
||
|
||
**职责**:
|
||
- 统一处理所有应用异常
|
||
- 区分API和Web请求
|
||
- 提供统一的JSON响应格式
|
||
- 支持开发和生产环境的不同处理策略
|
||
|
||
**主要方法**:
|
||
|
||
#### render() - 异常渲染入口
|
||
- **功能**: 判断请求类型，选择处理方式
|
||
- **逻辑**: admin/* 路径和期望JSON的请求返回JSON格式
|
||
- **输出**: JsonResponse 或 标准Response
|
||
|
||
#### renderJsonException() - JSON异常处理
|
||
- **功能**: 处理API请求的异常
|
||
- **支持的异常类型**:
|
||
- `AuthenticationException` - 认证失败
|
||
- `AccessDeniedHttpException` - 权限不足
|
||
- `ValidationException` - 参数验证失败
|
||
- `MethodNotAllowedHttpException` - 请求方法不允许
|
||
- `ModelNotFoundException` - 模型未找到
|
||
- `NotFoundHttpException` - 路由未找到
|
||
- `TooManyRequestsHttpException` - 请求频率超限
|
||
- `BusinessException` - 业务逻辑异常
|
||
|
||
#### renderSystemException() - 系统异常处理
|
||
- **功能**: 处理未预期的系统异常
|
||
- **生产环境**: 隐藏敏感信息，返回通用错误
|
||
- **开发环境**: 显示详细调试信息
|
||
|
||
#### jsonResponse() - 统一JSON响应
|
||
- **功能**: 生成标准格式的JSON响应
|
||
- **格式**:
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "错误描述",
|
||
"code": 错误代码,
|
||
"data": null,
|
||
"errors": {} // 仅验证错误时存在
|
||
}
|
||
```
|
||
|
||
**辅助方法**:
|
||
- `throwError()` - 快速抛出自定义异常
|
||
- `throwParamError()` - 抛出参数错误
|
||
- `throwNotFound()` - 抛出数据不存在异常
|
||
- `throwDataExist()` - 抛出数据已存在异常
|
||
|
||
### 2. BusinessException 业务异常
|
||
|
||
**位置**: `app/Exceptions/BusinessException.php`
|
||
|
||
**职责**:
|
||
- 处理业务逻辑相关的异常
|
||
- 支持自定义错误码和消息
|
||
- 继承标准Exception类
|
||
|
||
**构造函数**:
|
||
```php
|
||
public function __construct(array $codeResponse, $info = '')
|
||
```
|
||
|
||
**使用示例**:
|
||
```php
|
||
// 使用预定义错误码
|
||
throw new BusinessException(ResponseEnum::DATA_NOT_FOUND_ERROR);
|
||
|
||
// 自定义错误信息
|
||
throw new BusinessException(ResponseEnum::CLIENT_PARAMETER_ERROR, '用户名不能为空');
|
||
|
||
// 完全自定义
|
||
throw new BusinessException([400001, '自定义错误消息']);
|
||
```
|
||
|
||
### 3. LogException 日志异常处理
|
||
|
||
**位置**: `app/Exceptions/LogException.php`
|
||
|
||
**职责**:
|
||
- 安全记录异常到日志系统
|
||
- 处理日志系统本身的异常
|
||
- 提供多种日志记录策略
|
||
|
||
**主要方法**:
|
||
|
||
#### safeLog() - 安全日志记录
|
||
- **功能**: 防止日志记录失败影响主业务
|
||
- **策略**: 多通道尝试记录
|
||
- **兜底**: 系统错误日志
|
||
|
||
#### tryLogToChannels() - 多通道尝试
|
||
- **支持通道**: single, daily, errorlog
|
||
- **逻辑**: 依次尝试，成功即返回
|
||
|
||
#### checkAndFixLogPermissions() - 权限检查修复
|
||
- **功能**: 检查并修复日志文件权限问题
|
||
- **自动修复**: 创建目录、设置权限
|
||
|
||
### 4. ResponseEnum 响应码枚举
|
||
|
||
**位置**: `app/Helpers/ResponseEnum.php`
|
||
|
||
**职责**:
|
||
- 定义标准错误码和消息
|
||
- 提供HTTP状态码映射
|
||
- 统一错误信息管理
|
||
|
||
**错误码分类**:
|
||
- `100-199`: 信息提示
|
||
- `200xxx`: 操作成功/失败
|
||
- `400xxx`: 客户端错误
|
||
- `500xxx`: 服务器错误
|
||
|
||
**常用错误码**:
|
||
```php
|
||
const HTTP_OK = [200001, '操作成功'];
|
||
const CLIENT_PARAMETER_ERROR = [400200, '参数错误'];
|
||
const DATA_NOT_FOUND_ERROR = [400202, '数据不存在'];
|
||
const CLIENT_HTTP_UNAUTHORIZED = [401, '授权失败，请先登录'];
|
||
const SYSTEM_ERROR = [500001, '服务器错误'];
|
||
```
|
||
|
||
## 异常处理流程
|
||
|
||
### 1. 请求异常处理流程
|
||
|
||
```mermaid
|
||
graph TD
|
||
A[应用异常发生] --> B{请求类型判断}
|
||
B -->|admin/* 或 expectsJson| C[JSON异常处理]
|
||
B -->|普通Web请求| D[默认处理]
|
||
|
||
C --> E{异常类型判断}
|
||
E -->|认证异常| F[返回401 JSON]
|
||
E -->|验证异常| G[返回422 JSON + errors]
|
||
E -->|业务异常| H[返回200 JSON + code]
|
||
E -->|系统异常| I{环境判断}
|
||
E -->|其他HTTP异常| J[返回对应状态码JSON]
|
||
|
||
I -->|生产环境| K[隐藏错误详情]
|
||
I -->|开发环境| L[显示调试信息]
|
||
|
||
F --> M[统一JSON格式]
|
||
G --> M
|
||
H --> M
|
||
J --> M
|
||
K --> M
|
||
L --> M
|
||
```
|
||
|
||
### 2. 业务异常抛出流程
|
||
|
||
```mermaid
|
||
graph TD
|
||
A[业务逻辑检查] --> B{条件判断}
|
||
B -->|正常| C[继续执行]
|
||
B -->|异常| D[选择异常类型]
|
||
|
||
D --> E[Handler::throwParamError()]
|
||
D --> F[Handler::throwNotFound()]
|
||
D --> G[Handler::throwDataExist()]
|
||
D --> H[new BusinessException()]
|
||
|
||
E --> I[抛出BusinessException]
|
||
F --> I
|
||
G --> I
|
||
H --> I
|
||
|
||
I --> J[Handler捕获处理]
|
||
J --> K[返回JSON响应]
|
||
```
|
||
|
||
### 3. 日志记录流程
|
||
|
||
```mermaid
|
||
graph TD
|
||
A[异常发生] --> B[Handler.register()]
|
||
B --> C[LogException::safeLog()]
|
||
C --> D[尝试single通道]
|
||
D --> E{记录成功?}
|
||
E -->|是| F[记录完成]
|
||
E -->|否| G[尝试daily通道]
|
||
G --> H{记录成功?}
|
||
H -->|是| F
|
||
H -->|否| I[尝试errorlog通道]
|
||
I --> J{记录成功?}
|
||
J -->|是| F
|
||
J -->|否| K[系统error_log兜底]
|
||
```
|
||
|
||
## 使用方法
|
||
|
||
### 1. 控制器中抛出业务异常
|
||
|
||
```php
|
||
<?php
|
||
|
||
namespace App\Http\Controllers\Admin;
|
||
|
||
use App\Http\Controllers\BaseController;
|
||
use App\Exceptions\Handler;
|
||
use App\Helpers\ResponseEnum;
|
||
use Illuminate\Http\Request;
|
||
|
||
class UserController extends BaseController
|
||
{
|
||
public function show(Request $request, $id)
|
||
{
|
||
// 方法1: 使用辅助方法
|
||
if (empty($id)) {
|
||
Handler::throwParamError('用户ID不能为空');
|
||
}
|
||
|
||
$user = User::find($id);
|
||
if (!$user) {
|
||
Handler::throwNotFound('用户不存在');
|
||
}
|
||
|
||
// 方法2: 直接抛出BusinessException
|
||
if ($user->status === 0) {
|
||
throw new \App\Exceptions\BusinessException(
|
||
ResponseEnum::CLIENT_HTTP_UNAUTHORIZED,
|
||
'用户已被禁用'
|
||
);
|
||
}
|
||
|
||
return $this->SuccessObject($user);
|
||
}
|
||
|
||
public function store(Request $request)
|
||
{
|
||
$username = $request->input('username');
|
||
|
||
// 检查用户名是否已存在
|
||
if (User::where('username', $username)->exists()) {
|
||
Handler::throwDataExist('用户名已存在');
|
||
}
|
||
|
||
// 创建用户逻辑...
|
||
$user = User::create($request->all());
|
||
|
||
return $this->SuccessObject($user);
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2. 服务类中使用异常
|
||
|
||
```php
|
||
<?php
|
||
|
||
namespace App\Services;
|
||
|
||
use App\Exceptions\Handler;
|
||
use App\Models\User;
|
||
|
||
class UserService
|
||
{
|
||
public function updateUser($id, array $data)
|
||
{
|
||
$user = User::find($id);
|
||
if (!$user) {
|
||
Handler::throwNotFound('用户不存在');
|
||
}
|
||
|
||
// 检查权限
|
||
if (!$this->canUpdate($user)) {
|
||
Handler::throwError('无权修改此用户', 403001);
|
||
}
|
||
|
||
// 更新逻辑
|
||
$user->update($data);
|
||
|
||
return $user;
|
||
}
|
||
|
||
private function canUpdate(User $user): bool
|
||
{
|
||
// 权限检查逻辑
|
||
return true;
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3. 中间件中使用异常
|
||
|
||
```php
|
||
<?php
|
||
|
||
namespace App\Http\Middleware;
|
||
|
||
use App\Exceptions\Handler;
|
||
use Closure;
|
||
use Illuminate\Http\Request;
|
||
|
||
class CheckApiQuota
|
||
{
|
||
public function handle(Request $request, Closure $next)
|
||
{
|
||
$user = $request->user();
|
||
|
||
if (!$user) {
|
||
Handler::throwError('用户未认证', 401);
|
||
}
|
||
|
||
// 检查API调用额度
|
||
if ($this->exceedsQuota($user)) {
|
||
Handler::throwError('API调用次数已达上限', 429001);
|
||
}
|
||
|
||
return $next($request);
|
||
}
|
||
|
||
private function exceedsQuota($user): bool
|
||
{
|
||
// 额度检查逻辑
|
||
return false;
|
||
}
|
||
}
|
||
```
|
||
|
||
### 4. 模型中使用异常
|
||
|
||
```php
|
||
<?php
|
||
|
||
namespace App\Models;
|
||
|
||
use App\Exceptions\Handler;
|
||
use Illuminate\Database\Eloquent\Model;
|
||
|
||
class User extends Model
|
||
{
|
||
public function changeStatus($status)
|
||
{
|
||
// 状态验证
|
||
if (!in_array($status, [0, 1])) {
|
||
Handler::throwParamError('无效的用户状态');
|
||
}
|
||
|
||
// 检查是否可以修改
|
||
if ($this->is_admin && $status === 0) {
|
||
Handler::throwError('不能禁用管理员账户', 403002);
|
||
}
|
||
|
||
$this->status = $status;
|
||
$this->save();
|
||
}
|
||
}
|
||
```
|
||
|
||
## 响应格式规范
|
||
|
||
### 1. 成功响应格式
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "success",
|
||
"code": 200,
|
||
"data": {
|
||
// 具体数据
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2. 错误响应格式
|
||
|
||
#### 基本错误响应
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "错误描述",
|
||
"code": 400200,
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
#### 参数验证错误
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "参数错误",
|
||
"code": 400200,
|
||
"data": null,
|
||
"errors": {
|
||
"username": ["用户名不能为空"],
|
||
"email": ["邮箱格式不正确"]
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 开发环境系统错误
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "具体错误信息",
|
||
"code": 500001,
|
||
"data": {
|
||
"exception": "Illuminate\\Database\\QueryException",
|
||
"file": "/path/to/file.php",
|
||
"line": 123,
|
||
"trace": "异常堆栈信息..."
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 生产环境系统错误
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "服务器错误",
|
||
"code": 500001,
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
## 错误码规范
|
||
|
||
### 1. 错误码结构
|
||
|
||
```
|
||
错误码格式：XYYZZZ
|
||
- X: 错误类别 (4=客户端错误, 5=服务器错误)
|
||
- YY: 业务模块 (00=通用, 01=用户, 02=订单等)
|
||
- ZZZ: 具体错误 (001, 002, 003...)
|
||
```
|
||
|
||
### 2. 常用错误码
|
||
|
||
| 错误码 | HTTP状态码 | 说明 | 使用场景 |
|
||
|--------|------------|------|----------|
|
||
| 200001 | 200 | 操作成功 | 正常业务响应 |
|
||
| 400200 | 422 | 参数错误 | 请求参数验证失败 |
|
||
| 400201 | 409 | 数据已存在 | 创建重复数据 |
|
||
| 400202 | 404 | 数据不存在 | 查询不到数据 |
|
||
| 401 | 401 | 授权失败 | Token无效或过期 |
|
||
| 403 | 403 | 权限不足 | 没有操作权限 |
|
||
| 404 | 404 | 页面不存在 | 路由不存在 |
|
||
| 405 | 405 | 请求方法错误 | HTTP方法不允许 |
|
||
| 429 | 429 | 请求频率超限 | 触发限流 |
|
||
| 500001 | 500 | 服务器错误 | 系统异常 |
|
||
|
||
### 3. 自定义错误码示例
|
||
|
||
```php
|
||
// 在ResponseEnum中添加新的错误码
|
||
const USER_NOT_VERIFIED = [400101, '用户未验证'];
|
||
const USER_LOCKED = [400102, '用户账户已锁定'];
|
||
const ORDER_EXPIRED = [400201, '订单已过期'];
|
||
const PAYMENT_FAILED = [400301, '支付失败'];
|
||
const API_QUOTA_EXCEEDED = [429001, 'API调用次数超限'];
|
||
```
|
||
|
||
## 配置说明
|
||
|
||
### 1. 异常处理配置
|
||
|
||
**文件**: `bootstrap/app.php`
|
||
|
||
```php
|
||
->withExceptions(function (Exceptions $exceptions): void {
|
||
// 配置不需要报告的异常类型
|
||
$exceptions->dontReport([
|
||
\App\Exceptions\BusinessException::class,
|
||
]);
|
||
|
||
// 全局API异常处理
|
||
$exceptions->render(function (Throwable $e, $request) {
|
||
if ($request->expectsJson() || $request->is('admin/*')) {
|
||
$handler = app(\App\Exceptions\Handler::class);
|
||
return $handler->render($request, $e);
|
||
}
|
||
});
|
||
})
|
||
```
|
||
|
||
### 2. 日志配置
|
||
|
||
**文件**: `config/logging.php`
|
||
|
||
```php
|
||
'channels' => [
|
||
'single' => [
|
||
'driver' => 'single',
|
||
'path' => storage_path('logs/laravel.log'),
|
||
'level' => env('LOG_LEVEL', 'debug'),
|
||
],
|
||
|
||
'daily' => [
|
||
'driver' => 'daily',
|
||
'path' => storage_path('logs/laravel.log'),
|
||
'level' => env('LOG_LEVEL', 'debug'),
|
||
'days' => 14,
|
||
],
|
||
|
||
'errorlog' => [
|
||
'driver' => 'errorlog',
|
||
'level' => env('LOG_LEVEL', 'debug'),
|
||
],
|
||
],
|
||
```
|
||
|
||
### 3. 环境变量
|
||
|
||
**.env 文件**:
|
||
```env
|
||
# 应用调试模式
|
||
APP_DEBUG=true # 开发环境
|
||
APP_DEBUG=false # 生产环境
|
||
|
||
# 日志级别
|
||
LOG_LEVEL=debug # 开发环境
|
||
LOG_LEVEL=error # 生产环境
|
||
|
||
# 错误报告
|
||
LOG_CHANNEL=daily
|
||
```
|
||
|
||
## 测试方法
|
||
|
||
### 1. 单元测试
|
||
|
||
```php
|
||
<?php
|
||
|
||
namespace Tests\Unit;
|
||
|
||
use App\Exceptions\BusinessException;
|
||
use App\Exceptions\Handler;
|
||
use App\Helpers\ResponseEnum;
|
||
use Tests\TestCase;
|
||
|
||
class ExceptionHandlerTest extends TestCase
|
||
{
|
||
public function test_business_exception_response()
|
||
{
|
||
$this->expectException(BusinessException::class);
|
||
|
||
Handler::throwParamError('测试参数错误');
|
||
}
|
||
|
||
public function test_api_error_response()
|
||
{
|
||
$response = $this->postJson('/admin/auth/login', []);
|
||
|
||
$response->assertStatus(422)
|
||
->assertJson([
|
||
'success' => false,
|
||
'code' => 400200,
|
||
])
|
||
->assertJsonStructure([
|
||
'success',
|
||
'message',
|
||
'code',
|
||
'data',
|
||
'errors'
|
||
]);
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2. 集成测试
|
||
|
||
```php
|
||
public function test_authentication_error()
|
||
{
|
||
$response = $this->getJson('/admin/auth/me');
|
||
|
||
$response->assertStatus(401)
|
||
->assertJson([
|
||
'success' => false,
|
||
'code' => 401,
|
||
'message' => '授权失败，请先登录'
|
||
]);
|
||
}
|
||
|
||
public function test_not_found_error()
|
||
{
|
||
$response = $this->getJson('/admin/nonexistent');
|
||
|
||
$response->assertStatus(404)
|
||
->assertJson([
|
||
'success' => false,
|
||
'code' => 404
|
||
]);
|
||
}
|
||
```
|
||
|
||
### 3. 手动测试
|
||
|
||
#### 测试参数验证错误
|
||
```bash
|
||
curl -X POST http://localhost:8000/admin/auth/login \
|
||
-H "Content-Type: application/json" \
|
||
-d '{}'
|
||
```
|
||
|
||
预期响应：
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "参数错误",
|
||
"code": 400200,
|
||
"data": null,
|
||
"errors": {
|
||
"username": ["The username field is required."],
|
||
"password": ["The password field is required."]
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 测试认证错误
|
||
```bash
|
||
curl -X GET http://localhost:8000/admin/auth/me \
|
||
-H "Authorization: Bearer invalid_token"
|
||
```
|
||
|
||
预期响应：
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "授权失败，请先登录",
|
||
"code": 401,
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
## 性能优化
|
||
|
||
### 1. 异常处理性能
|
||
|
||
**避免过度异常处理**:
|
||
```php
|
||
// ❌ 不好的做法 - 用异常控制正常流程
|
||
try {
|
||
$user = User::findOrFail($id);
|
||
} catch (ModelNotFoundException $e) {
|
||
return $this->Field('用户不存在');
|
||
}
|
||
|
||
// ✅ 好的做法 - 正常判断
|
||
$user = User::find($id);
|
||
if (!$user) {
|
||
Handler::throwNotFound('用户不存在');
|
||
}
|
||
```
|
||
|
||
**缓存异常信息**:
|
||
```php
|
||
// 对于频繁抛出的业务异常，可以考虑缓存错误信息
|
||
class CachedBusinessException extends BusinessException
|
||
{
|
||
private static array $messageCache = [];
|
||
|
||
public function __construct(array $codeResponse, $info = '')
|
||
{
|
||
$key = md5(serialize($codeResponse) . $info);
|
||
if (!isset(self::$messageCache[$key])) {
|
||
self::$messageCache[$key] = $info ?: $codeResponse[1];
|
||
}
|
||
|
||
parent::__construct($codeResponse, self::$messageCache[$key]);
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2. 日志性能优化
|
||
|
||
**异步日志记录**:
|
||
```php
|
||
// 在config/logging.php中配置
|
||
'async' => [
|
||
'driver' => 'custom',
|
||
'via' => App\Logging\AsyncLoggerFactory::class,
|
||
'channel' => 'daily',
|
||
],
|
||
```
|
||
|
||
**日志分级**:
|
||
```php
|
||
// 只在必要时记录详细信息
|
||
if (config('app.debug')) {
|
||
LogException::safeLog('详细调试信息', $e, $context);
|
||
} else {
|
||
LogException::safeLog('简化错误信息', $e);
|
||
}
|
||
```
|
||
|
||
## 监控和报警
|
||
|
||
### 1. 错误监控
|
||
|
||
**统计异常频率**:
|
||
```php
|
||
// 可以添加到Handler中
|
||
protected function reportException(Throwable $e): void
|
||
{
|
||
// 统计异常类型和频率
|
||
$type = get_class($e);
|
||
Cache::increment("exception_count:{$type}");
|
||
|
||
// 记录异常趋势
|
||
$hour = now()->format('Y-m-d-H');
|
||
Cache::increment("exception_hourly:{$hour}");
|
||
|
||
parent::report($e);
|
||
}
|
||
```
|
||
|
||
**关键异常报警**:
|
||
```php
|
||
protected function shouldAlert(Throwable $e): bool
|
||
{
|
||
// 系统异常立即报警
|
||
if (!($e instanceof BusinessException)) {
|
||
return true;
|
||
}
|
||
|
||
// 高频业务异常报警
|
||
$count = Cache::get("exception_count:" . get_class($e), 0);
|
||
return $count > 100; // 超过100次/小时报警
|
||
}
|
||
```
|
||
|
||
### 2. 性能监控
|
||
|
||
**响应时间监控**:
|
||
```php
|
||
class ExceptionMiddleware
|
||
{
|
||
public function handle($request, Closure $next)
|
||
{
|
||
$start = microtime(true);
|
||
|
||
try {
|
||
return $next($request);
|
||
} catch (Throwable $e) {
|
||
$duration = microtime(true) - $start;
|
||
|
||
// 记录异常处理时间
|
||
Log::info('Exception handling time', [
|
||
'duration' => $duration,
|
||
'exception' => get_class($e)
|
||
]);
|
||
|
||
throw $e;
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## 安全考虑
|
||
|
||
### 1. 信息泄露防护
|
||
|
||
**生产环境信息过滤**:
|
||
```php
|
||
protected function filterSensitiveInfo(Throwable $e): array
|
||
{
|
||
if (!config('app.debug')) {
|
||
return [
|
||
'message' => '服务器内部错误',
|
||
'code' => 500001
|
||
];
|
||
}
|
||
|
||
// 过滤敏感路径
|
||
$file = str_replace(base_path(), '', $e->getFile());
|
||
|
||
return [
|
||
'message' => $e->getMessage(),
|
||
'file' => $file,
|
||
'line' => $e->getLine()
|
||
];
|
||
}
|
||
```
|
||
|
||
### 2. 日志安全
|
||
|
||
**敏感信息脱敏**:
|
||
```php
|
||
protected function sanitizeLogData(array $context): array
|
||
{
|
||
$sensitive = ['password', 'token', 'secret', 'key'];
|
||
|
||
foreach ($context as $key => $value) {
|
||
if (in_array(strtolower($key), $sensitive)) {
|
||
$context[$key] = '***';
|
||
}
|
||
}
|
||
|
||
return $context;
|
||
}
|
||
```
|
||
|
||
## 注意事项
|
||
|
||
### 1. 开发注意事项
|
||
|
||
**异常分类原则**:
|
||
- **业务异常**: 可预期的业务逻辑错误，使用BusinessException
|
||
- **系统异常**: 不可预期的技术错误，让系统自动处理
|
||
- **验证异常**: 参数格式错误，使用Laravel验证器
|
||
|
||
**性能考虑**:
|
||
- 避免在循环中频繁抛出异常
|
||
- 合理使用异常，不要用异常控制正常业务流程
|
||
- 异常信息要清晰明确，便于调试
|
||
|
||
### 2. 部署注意事项
|
||
|
||
**环境配置**:
|
||
- 生产环境必须关闭DEBUG模式
|
||
- 配置适当的日志轮转策略
|
||
- 设置日志文件权限
|
||
|
||
**监控设置**:
|
||
- 配置异常报警阈值
|
||
- 监控错误率和响应时间
|
||
- 定期检查日志文件大小
|
||
|
||
### 3. 维护注意事项
|
||
|
||
**错误码管理**:
|
||
- 统一错误码命名规范
|
||
- 定期清理无用的错误码
|
||
- 保持错误信息的一致性
|
||
|
||
**日志管理**:
|
||
- 定期清理旧日志文件
|
||
- 监控磁盘空间使用
|
||
- 备份重要错误日志
|
||
|
||
## 扩展开发
|
||
|
||
### 1. 自定义异常类型
|
||
|
||
```php
|
||
<?php
|
||
|
||
namespace App\Exceptions;
|
||
|
||
class ValidationException extends BusinessException
|
||
{
|
||
public function __construct(array $errors, string $message = '参数验证失败')
|
||
{
|
||
$this->errors = $errors;
|
||
parent::__construct([422, $message]);
|
||
}
|
||
|
||
public function getErrors(): array
|
||
{
|
||
return $this->errors;
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2. 异常处理中间件
|
||
|
||
```php
|
||
<?php
|
||
|
||
namespace App\Http\Middleware;
|
||
|
||
class ExceptionHandlingMiddleware
|
||
{
|
||
public function handle($request, Closure $next)
|
||
{
|
||
try {
|
||
return $next($request);
|
||
} catch (BusinessException $e) {
|
||
// 业务异常特殊处理
|
||
return response()->json([
|
||
'success' => false,
|
||
'message' => $e->getMessage(),
|
||
'code' => $e->getCode(),
|
||
'timestamp' => now()->toISOString()
|
||
]);
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3. 异常通知系统
|
||
|
||
```php
|
||
<?php
|
||
|
||
namespace App\Services;
|
||
|
||
class ExceptionNotificationService
|
||
{
|
||
public function notify(Throwable $e): void
|
||
{
|
||
// 邮件通知
|
||
if ($this->shouldEmailNotify($e)) {
|
||
Mail::to(config('app.admin_email'))
|
||
->send(new ExceptionNotification($e));
|
||
}
|
||
|
||
// 钉钉/企微通知
|
||
if ($this->shouldInstantNotify($e)) {
|
||
$this->sendInstantMessage($e);
|
||
}
|
||
}
|
||
|
||
private function shouldEmailNotify(Throwable $e): bool
|
||
{
|
||
return !($e instanceof BusinessException) && config('app.env') === 'production';
|
||
}
|
||
}
|
||
```
|
||
|
||
## 技术支持
|
||
|
||
### 1. 常见问题
|
||
|
||
**Q: 如何添加新的异常类型？**
|
||
A: 在Handler的`renderJsonException`方法中添加新的异常处理逻辑，或者继承BusinessException创建自定义异常类。
|
||
|
||
**Q: 如何修改异常响应格式？**
|
||
A: 修改Handler的`jsonResponse`方法，调整返回的JSON结构。
|
||
|
||
**Q: 生产环境异常信息太少，如何调试？**
|
||
A: 检查日志文件，或者临时开启DEBUG模式进行调试。
|
||
|
||
### 2. 调试技巧
|
||
|
||
**查看详细异常信息**:
|
||
```bash
|
||
# 查看最新的异常日志
|
||
tail -f storage/logs/laravel.log
|
||
|
||
# 搜索特定异常
|
||
grep "Exception" storage/logs/laravel-*.log
|
||
```
|
||
|
||
**临时调试模式**:
|
||
```php
|
||
// 在特定方法中临时启用详细错误
|
||
if ($request->input('debug') === 'true' && auth()->user()->is_admin) {
|
||
config(['app.debug' => true]);
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
**文档版本**: v1.0
|
||
**最后更新**: 2024年12月
|
||
**作者**: 开发团队
|
||
**审核**: 技术负责人 |