Laravel HTTP单元测试中自定义异常的测试与最佳实践

一、单元测试expectException该指定哪个类？ #

你在控制器里已经手动捕获了KeyIsNotProvidedException并返回了JSON响应，这意味着这个异常已经被“消化”了，不会向上抛出到测试框架层面。所以此时用expectException(KeyIsNotProvidedException::class)是不会生效的。

正确的做法是直接测试HTTP响应的状态码和返回内容，不用捕获异常。示例代码：

public function test_missing_key_returns_500_response()
{
    $response = $this->postJson('/your-endpoint', []); // 不传触发异常的必要key

    $response->assertStatus(500)
             ->assertJson([
                 'message' => '密钥未提供', // 对应你返回的错误信息
                 // 可添加自定义错误码等字段
             ]);
}

如果你的自定义异常是在服务层抛出、控制器仅调用服务层，那可以单独写服务层的单元测试，在那里用expectException(KeyIsNotProvidedException::class)验证异常是否被正确抛出。

二、控制器与测试中返回500状态码的最佳实践 #

控制器端 #

1. 区分异常类型，谨慎使用500
   500是「服务器内部错误」的标准状态码，适合处理非预期、服务器端无法恢复的错误。如果KeyIsNotProvidedException是因为客户端未传必要参数导致的，其实更适合返回400 Bad Request或422 Unprocessable Content（Laravel默认验证失败返回422）；但如果这个key是服务器内部流程必须的配置项缺失，返回500是合理的。

2. 统一异常处理，避免重复代码
   不要在每个控制器里都写try-catch，可以在app/Exceptions/Handler.php中注册自定义异常的全局处理逻辑，示例：

   use App\Exceptions\KeyIsNotProvidedException;
   
   public function register()
   {
       $this->renderable(function (KeyIsNotProvidedException $e, $request) {
           if ($request->wantsJson()) {
               return response()->json([
                   'message' => $e->getMessage(),
                   'error_code' => 'KEY_NOT_PROVIDED'
               ], 500);
           }
       });
   }
   

   这样控制器里直接抛出异常即可，不用手动捕获，代码更简洁统一。

3. 返回清晰的错误结构
   返回的JSON响应至少要包含message字段说明错误原因，也可以加上自定义error_code，方便前端或调用方快速识别错误类型。

测试端 #

1. 重点验证响应状态和内容
   既然异常被处理成了HTTP响应，测试的核心就是验证状态码是否正确，返回的JSON结构和内容是否符合预期，而非捕获异常。

2. 覆盖所有异常触发场景
   确保测试用例覆盖所有会触发该异常的场景，比如不传key、传无效key等，分别验证对应的响应。

3. 单独测试异常抛出逻辑
   若要验证「异常是否在正确时机被抛出」，不要在控制器HTTP测试里做，而是写对应的服务层/逻辑层单元测试，直接调用抛出异常的方法，示例：

   public function test_missing_key_triggers_exception()
   {
       $this->expectException(KeyIsNotProvidedException::class);
       $this->expectExceptionMessage('必须提供API密钥');
   
       $service = new YourService();
       $service->process(null); // 不传key触发异常
   }
   

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