本文探讨了在Laravel Jetstream项目中，如何利用单个控制器方法同时处理Inertia.js驱动的Web视图渲染和纯JSON格式的API数据响应。通过巧妙运用Laravel的request()->wantsJson()辅助函数，开发者可以高效地复用后端逻辑，为Web单页应用和移动客户端提供统一的数据源，极大简化代码结构并提升开发效率，避免不必要的代码重复。
背景与挑战
在使用Laravel Jetstream结合Inertia.js构建单页应用（SPA）时，我们通常会将前端逻辑与后端数据紧密结合在一个项目中。Inertia.js允许我们直接从Laravel控制器返回Vue、React或Svelte组件，并传递数据，从而实现无刷新的页面导航和数据渲染。例如，一个典型的用户列表控制器方法可能如下所示：
class UsersController extends Controller
{
public function index()
{
$users = User::active()
->orderByName()
->get(['id', 'name', 'email']);
return Inertia::render('Users', [
'users' => $users
]);
}
}通过路由 Route::get('users', [UserController::class, 'index']); 访问 /users 即可在浏览器中看到用户列表。
然而，在许多实际项目中，除了Web应用，我们还需要为移动应用程序或其他API客户端提供相同的数据。这意味着同一个用户列表数据可能需要以JSON格式返回。传统的做法是创建单独的API路由和控制器方法，或者在现有方法中添加复杂的条件判断来区分Inertia响应和JSON响应。这无疑增加了代码的冗余和维护的复杂性。
核心解决方案：条件式响应
Laravel提供了一个简洁而强大的方法来判断客户端期望的响应类型，即 request()->wantsJson()。这个辅助函数会检查HTTP请求头中的 Accept 字段是否包含 application/json。如果客户端期望JSON响应，它将返回 true；否则，返回 false。
利用这个特性，我们可以在同一个控制器方法中优雅地处理两种不同类型的响应：
use Inertia\Inertia;
use App\Models\User;
use Illuminate\Http\Request; // 确保引入Request类
class UsersController extends Controller
{
public function index(Request $request) // 注入Request实例是推荐做法
{
$users = User::active()
->orderByName()
->get(['id', 'name', 'email']);
// 判断客户端是否期望JSON响应
if ($request->wantsJson()) { // 使用$request实例调用wantsJson()
return response()->json($users); // 显式返回JSON响应
}
// 否则，返回Inertia页面渲染
return Inertia::render('Users', [
'users' => $users
]);
}
}代码解析：
- 数据获取: User::active()->orderByName()->get(['id', 'name', 'email']); 这部分是核心业务逻辑，负责从数据库获取用户数据。这部分逻辑对于Inertia和JSON响应是完全共享的。
- 条件判断: $request->wantsJson() 是关键。它检查当前请求是否通过 Accept: application/json 头表明期望JSON响应。
- JSON响应: 如果 $request->wantsJson() 为真，则执行 return response()->json($users);。Laravel会自动将 $users 集合序列化为JSON格式并返回。这里显式使用 response()->json() 是一个好习惯，尽管直接 return $users; 在多数情况下也能达到相同效果（Laravel会自动处理模型或集合的JSON转换）。
- Inertia响应: 如果 $request->wantsJson() 为假，则执行 return Inertia::render('Users', ['users' => $users]);。这将渲染名为 Users 的Inertia组件，并将 $users 数据作为 props 传递给前端。
实际应用场景与测试
- Web应用访问: 当用户通过浏览器访问 http://localhost:8000/users 时，浏览器通常不会发送 Accept: application/json 头（除非是XHR请求且明确设置）。因此，控制器会返回Inertia页面，渲染用户列表。
- 移动应用/API客户端访问: 当移动应用程序或Postman等API测试工具向 http://localhost:8000/users 发送请求，并在请求头中包含 Accept: application/json 时，控制器将检测到此头，并返回纯JSON格式的用户数据。
例如，使用cURL模拟API请求：
curl -H "Accept: application/json" http://localhost:8000/users
这将返回一个JSON数组，包含用户数据。
优势与注意事项
优势：
- 代码复用: 核心数据获取逻辑仅需编写一次，避免了为Inertia和API分别创建控制器或方法的冗余。
- 逻辑集中: 业务逻辑保持在同一个地方，便于理解和维护。
- 开发效率: 减少了重复开发的工作量，尤其是在项目初期。
- 一致性: 确保Web端和API端的数据源和处理逻辑保持一致。
注意事项：
- 路由定义: 尽管控制器方法相同，但在 web.php 和 api.php 中定义相同路由时，需要注意路由的优先级和中间件。通常，此方法更适用于Web路由，API客户端通过发送特定Accept头来获取JSON。
- 错误处理: Inertia有其自身的错误处理机制（例如重定向到登录页），而API通常需要返回标准的JSON错误响应（如HTTP状态码4xx/5xx及包含错误信息的JSON体）。在更复杂的场景下，可能需要更精细的错误处理逻辑，可能通过自定义异常处理器或中间件来实现。
- 认证与授权: 确保为两种请求类型（Web和API）都配置了适当的认证和授权中间件。例如，Web请求可能使用web守卫，而API请求可能使用sanctum或passport守卫。
- 数据序列化: 对于更复杂的数据结构或需要定制化输出的情况，建议结合使用Laravel API Resources。API Resources可以为JSON响应提供统一且可控的数据格式，即使Inertia响应直接传递Eloquent模型，API Resources也能确保API输出的规范性。
总结
通过利用Laravel的 request()->wantsJson() 辅助函数，开发者可以高效且优雅地在同一个控制器方法中实现Inertia.js驱动的Web视图渲染和JSON格式的API数据响应。这种策略极大地提升了代码的复用性、可维护性和开发效率，是构建混合型Web/移动应用项目的强大实践。在实施时，应同时考虑路由、错误处理、认证以及数据序列化等方面的最佳实践，以确保应用的健壮性和可扩展性。
