本文旨在解决 laravel 项目中控制器方法返回空值时，默认发送 200 ok 状态码的问题。我们将探讨如何通过创建一个响应中间件，在响应发送前拦截并检查其内容。如果响应体为空，中间件将自动将其 http 状态码修改为 204 no content，从而避免在每个控制器方法中手动添加 response()->nocontent()，实现更优雅、统一的空响应处理机制。
在构建 RESTful API 或处理某些特定业务逻辑时，我们经常会遇到控制器方法成功执行但无需返回任何内容的情况。例如，一个资源删除操作成功后，或者一个数据更新操作仅需确认成功而无需返回更新后的资源。在这种情况下，HTTP 协议规范推荐使用 204 No Content 状态码，表示请求已成功处理，但响应体不包含任何内容。然而，Laravel 框架默认行为是，当控制器方法返回 null 或 void 时，会发送一个 200 OK 状态码，并附带一个空响应体。
为了符合 204 No Content 的语义，开发者通常需要在每个相关的控制器方法中显式地调用 return response()->noContent();。这不仅增加了代码冗余，也使得代码维护变得复杂。一个常见的误区是尝试通过覆盖 Illuminate\Routing\Router::toResponse 方法来修改这一行为，但这种方法通常过于侵入性，且不易维护。
解决方案：使用响应中间件
Laravel 提供了一种更优雅、非侵入性的方式来处理响应：响应中间件（Response Middleware）。响应中间件在控制器方法执行完毕并生成初始响应之后，但在响应发送到客户端之前运行。这使得它成为检查和修改响应的理想场所。
我们可以创建一个简单的中间件，用于检查响应体是否为空。如果响应体为空，则将其 HTTP 状态码更改为 204 No Content。
创建中间件
首先，通过 Artisan 命令创建一个新的中间件：
php artisan make:middleware FixStatusCode
这将在 app/Http/Middleware 目录下生成 FixStatusCode.php 文件。接下来，编辑该文件，实现我们所需的逻辑：
<?php
namespace App\Http\Middleware;
use Closure;
use Illuminate\Http\Request;
use Symfony\Component\HttpFoundation\Response;
/**
* 确保内容为空的响应返回 204 状态码。
*
* 此中间件用于修正 Laravel 在控制器返回空值时默认发送 200 OK 的行为。
*/
class FixStatusCode
{
/**
* 处理传入请求。
*
* @param Request $request
* @param \Closure $next
* @return Response
*/
public function handle(Request $request, Closure $next): Response
{
/** @var Response $response */
// 调用下一个中间件或控制器，获取原始响应
$response = $next($request);
// 检查响应内容是否为空
// getContent() 方法返回响应体内容，empty() 判断是否为空
if (empty($response->getContent())) {
// 如果内容为空，则将状态码设置为 204 No Content
$response->setStatusCode(Response::HTTP_NO_CONTENT);
}
return $response;
}
}代码解析
- $response = $next($request);：这是中间件的核心。它将请求传递给应用程序的其余部分（包括控制器），并捕获控制器返回的响应。此时，如果控制器返回 null 或 void，Laravel 已经将其转换为一个 Symfony\Component\HttpFoundation\Response 实例，状态码为 200 OK，响应体为空。
- if (empty($response->getContent()))：我们通过 getContent() 方法获取响应体内容，并使用 empty() 函数判断其是否为空。
- $response->setStatusCode(Response::HTTP_NO_CONTENT);：如果响应体为空，我们就将响应的状态码设置为 204 No Content。Response::HTTP_NO_CONTENT 是 Symfony\Component\HttpFoundation\Response 类中定义的常量，代表 204。
注册中间件
创建中间件后，我们需要将其注册到 Laravel 应用程序中，以便它能够被执行。根据需求，你可以选择将其注册为全局中间件、路由组中间件或指定路由中间件。对于这种全局性的空响应处理，最常见且推荐的做法是将其注册为全局中间件。
打开 app/Http/Kernel.php 文件，在 $middleware 数组中添加 FixStatusCode 中间件：
<?php
namespace App\Http;
use Illuminate\Foundation\Http\Kernel as HttpKernel;
class Kernel extends HttpKernel
{
/**
* 应用程序的全局 HTTP 中间件栈。
*
* 这些中间件在每个请求期间运行。
*
* @var array<int, string>
*/
protected $middleware = [
// \App\Http\Middleware\TrustProxies::class,
// \Illuminate\Http\Middleware\HandleCors::class,
// \App\Http\Middleware\PreventRequestsDuringMaintenance::class,
// \Illuminate\Foundation\Http\Middleware\ValidatePostSize::class,
// \App\Http\Middleware\TrimStrings::class,
// \Illuminate\Foundation\Http\Middleware\ConvertEmptyStringsToNull::class,
\App\Http\Middleware\FixStatusCode::class, // 在此处添加你的中间件
];
// ... 其他中间件组和路由中间件定义
}将 \App\Http\Middleware\FixStatusCode::class 添加到 $middleware 数组中后，它将对所有进入应用程序的请求生效。这意味着，任何控制器方法返回空值时，都将自动触发此中间件，并将响应状态码修改为 204 No Content。
注意事项与最佳实践
- 全局影响： 将中间件注册为全局中间件意味着它会检查所有响应。请确保这是你期望的行为。如果只需要对特定路由或 API 组生效，可以将其注册到 $middlewareGroups 或 $routeMiddleware 中。
- 避免过度使用： 此方法适用于那些确实希望返回 204 No Content 而非 200 OK 的场景。如果某些空响应确实需要 200 OK 状态（例如，一个搜索结果为空但操作本身成功），则不应使用此全局中间件，或者在控制器中显式返回 response()->ok()。
- 清晰的语义： 204 No Content 明确表示请求已成功处理，但响应体是空的。这对于客户端（尤其是前端应用）来说，提供了清晰的语义，可以避免解析空响应体或不必要的渲染。
- 可维护性： 相较于修改 Laravel 核心路由逻辑，使用中间件是一种更符合框架设计哲学、更易于理解和维护的扩展方式。它将特定的业务逻辑或框架行为修正封装在一个独立的、可插拔的组件中。
总结
通过引入一个简单的响应中间件，我们成功地解决了 Laravel 在控制器方法返回空值时默认发送 200 OK 状态码的问题，实现了自动将此类响应转换为 204 No Content。这种方法不仅避免了在每个控制器中重复编写 return response()->noContent(); 的代码，还提升了代码的整洁性和可维护性，同时确保了 API 响应的语义准确性。这是一个在 Laravel 项目中处理空响应的优雅且推荐的解决方案。
