Laravel事件异常处理：回滚数据库、反馈用户及测试方案问询

针对你遇到的Laravel事件链中附件缺失导致的异常处理问题，咱们一步步拆解解决：

一、核心方案：用数据库事务包裹完整业务流程 #

你的第二个思路方向是对的，但需要调整细节——因为同步事件的数据库操作会共享控制器开启的事务，所以只要把store方法的逻辑包裹在事务中，一旦事件链中抛出异常，就能回滚所有变更（包括新建的ApplicationAction、Application的status修改）。

1. 自定义精准异常 #

首先创建一个自定义异常，用来区分“附件缺失”这个特定场景，避免和其他FileNotFoundException混淆：

// app/Exceptions/EmailAttachmentMissingException.php
namespace App\Exceptions;

use Exception;

class EmailAttachmentMissingException extends Exception
{
    protected $message = '邮件附件文件不存在，操作已取消';

    public function __construct(string $fileName = null)
    {
        if ($fileName) {
            $this->message = "邮件附件 {$fileName} 不存在，操作已取消";
        }
        parent::__construct($this->message);
    }
}

2. 在Mailable中检查文件并抛出自定义异常 #

在动态Mailable类中，先检查文件是否存在，不存在就抛出咱们自定义的异常：

public function build() {
    // ... 其他代码
    $documents = $this->application->documents->whereIn('type', ['some-document', 'some-other-document']);
    $documents->each(function ($document, $key) {
        $filePath = storage_path($document->file_path);
        if (!file_exists($filePath)) {
            throw new \App\Exceptions\EmailAttachmentMissingException(basename($filePath));
        }
        $this->attach($filePath);
    });
    return $this->from($from)->view($view);
}

3. 控制器中用事务包裹并捕获异常 #

修改ActionController的store方法，开启事务并捕获自定义异常：

use App\Exceptions\EmailAttachmentMissingException;
use Illuminate\Support\Facades\DB;

public function store(StoreActionFormRequest $request) {
    DB::beginTransaction();
    try {
        $actionDetails = (new ApplicationAction)->createFromRequest($request);
        DB::commit();
        
        return redirect()->back()->with('success', '操作已成功执行');
    } catch (EmailAttachmentMissingException $e) {
        DB::rollback();
        // 把错误信息传递给前端，用户留在原页面查看提示
        return redirect()->back()->withErrors(['error' => $e->getMessage()])->withInput();
    } catch (\Exception $e) {
        DB::rollback();
        // 处理其他未知异常
        return redirect()->back()->withErrors(['error' => '操作失败，请稍后重试'])->withInput();
    }
}

如果偏好用异常处理器返回自定义错误页面，也可以修改Handler.php：

use App\Exceptions\EmailAttachmentMissingException;

public function render($request, Exception $exception) {
    if ($exception instanceof EmailAttachmentMissingException) {
        return response()->view('errors.attachment_missing', [
            'message' => $exception->getMessage()
        ], 422); // 用422（验证错误）比500更合适，因为是业务逻辑上的问题
    }
    return parent::render($request, $exception);
}

此时控制器里捕获异常后直接throw $e;即可。

二、测试编写：覆盖正常与异常场景 #

1. 正常场景测试 #

用Laravel的测试工具，模拟请求，断言数据库变更和邮件发送：

use Illuminate\Support\Facades\Mail;
use App\Models\Application;
use App\Models\Applicant;
use App\Models\User;

public function test_action_created_and_email_sent_successfully()
{
    // 准备测试数据：创建Applicant、Application、存在的附件Document
    $user = User::factory()->create();
    $applicant = Applicant::factory()->create(['user_id' => $user->id]);
    $application = Application::factory()->create(['applicant_id' => $applicant->id]);
    // 创建存在的测试文件
    $filePath = storage_path('test-document.pdf');
    file_put_contents($filePath, 'test content');
    $application->documents()->create([
        'type' => 'some-document',
        'file_path' => str_replace(storage_path(), '', $filePath)
    ]);

    Mail::fake();
    
    // 模拟请求
    $this->actingAs($user)->post(route('actions.store'), [
        'application_id' => $application->id,
        'action' => 'reject',
        'details' => '测试拒绝'
    ]);

    // 断言ApplicationAction已创建
    $this->assertDatabaseHas('application_actions', [
        'application_id' => $application->id,
        'action' => 'reject'
    ]);
    // 断言Application状态已更新
    $application->refresh();
    $this->assertEquals('rejected', $application->status);
    // 断言邮件已发送
    Mail::assertSent(function ($mail) use ($application) {
        return $mail->application->id === $application->id;
    });

    // 清理测试文件
    unlink($filePath);
}

2. 异常场景测试 #

模拟附件不存在的情况，断言事务回滚：

use Illuminate\Support\Facades\Mail;
use App\Models\Application;
use App\Models\Applicant;
use App\Models\User;

public function test_missing_attachment_rolls_back_database_changes()
{
    $user = User::factory()->create();
    $applicant = Applicant::factory()->create(['user_id' => $user->id]);
    $application = Application::factory()->create(['applicant_id' => $applicant->id, 'status' => 'pending']);
    // 创建指向不存在文件的Document
    $application->documents()->create([
        'type' => 'some-document',
        'file_path' => 'non-existent-file.pdf'
    ]);

    Mail::fake();
    
    // 模拟请求
    $response = $this->actingAs($user)->post(route('actions.store'), [
        'application_id' => $application->id,
        'action' => 'reject',
        'details' => '测试拒绝'
    ]);

    // 断言错误信息已返回
    $response->assertSessionHasErrors(['error' => '邮件附件 non-existent-file.pdf 不存在，操作已取消']);
    // 断言ApplicationAction未创建
    $this->assertDatabaseMissing('application_actions', [
        'application_id' => $application->id,
        'action' => 'reject'
    ]);
    // 断言Application状态未变更
    $application->refresh();
    $this->assertEquals('pending', $application->status);
    // 断言邮件未发送
    Mail::assertNotSent(function ($mail) use ($application) {
        return $mail->application->id === $application->id;
    });
}

三、额外优化建议 #

• 文件存储用Laravel文件系统：不要直接用storage_path()，改用Storage::disk('local')->exists($document->file_path)，这样更符合Laravel的规范，也方便后续切换存储驱动（比如S3）。
• 事件队列（可选）：如果邮件发送耗时较长，可以把NotifyApplicationWasUpdated监听器改成异步队列，但此时事务回滚需要注意——因为队列是异步的，事务提交后队列才会执行，所以如果队列中抛出异常，已经提交的DB变更无法回滚。这种情况需要额外的补偿机制（比如记录失败日志，手动回滚），但你的场景是同步事件，所以当前方案没问题。

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