如何在 Laravel 中自定义 API 验证错误响应格式-php教程-PHP中文网

如何在 Laravel 中自定义 API 验证错误响应格式

本文详解如何在 laravel 中为 api 请求定制结构化验证错误响应（如统一返回 code/message 格式），替代默认的 messages 数组，并通过手动验证器实现灵活控制。

本文详解如何在 laravel 中为 api 请求定制结构化验证错误响应（如统一返回 code/message 格式），替代默认的 messages 数组，并通过手动验证器实现灵活控制。

在 Laravel 中，$request->validate() 方法虽简洁，但其默认失败响应为 422 Unprocessable Entity + {"message":"...", "errors":{"username":["..."]}} 结构，不符合许多现代 API 要求的扁平化、带业务码（如 "code": 3）的 JSON 格式。要实现类似 {"code": 3, "message": "Usernames can be 3 to 20 characters long"} 的精准响应，需绕过自动验证，改用 手动实例化 Validator 并结合自定义消息与逻辑分支控制。

以下是一个完整、可直接集成的解决方案：

use Illuminate\Support\Facades\Validator;
use Illuminate\Http\Request;

public function UserCheck(Request $request)
{
    // 定义各验证规则对应的结构化错误响应
    $customMessages = [
        'required' => json_encode(['code' => 1, 'message' => 'A valid username is required.']),
        'string'   => json_encode(['code' => 1, 'message' => 'Username must be a string.']),
        'min'      => json_encode(['code' => 3, 'message' => 'Usernames can be 3 to 20 characters long']),
        'max'      => json_encode(['code' => 3, 'message' => 'Usernames can be 3 to 20 characters long']),
        'unique'   => json_encode(['code' => 2, 'message' => 'Username not appropriate for ' . config('app.name')]),
        'regex'    => json_encode(['code' => 2, 'message' => 'Username contains invalid characters.']),
    ];

    $validator = Validator::make($request->all(), [
        'username' => [
            'required',
            'string',
            'min:3',
            'max:20',
            'unique:users',
            'regex:/^[a-zA-Z0-9_]+$/u', // ✅ 修正：禁止开头/结尾下划线，且仅允许一个连续下划线（见下方说明）
        ],
    ], $customMessages);

    if ($validator->fails()) {
        // 提取首个错误并解码为数组（确保单条 error 响应）
        $firstError = json_decode($validator->errors()->first(), true) ?: ['code' => 1, 'message' => 'Validation failed'];
        return response()->json($firstError, 422);
    }

    return response()->json(['code' => 0, 'message' => 'Username is valid']);
}

✅ 关键说明与优化点：

正则表达式增强：原 regex:/^[a-zA-Z0-9_]*$/ 允许空用户名及多个连续下划线。若需“下划线仅可出现在中间、且最多出现一次”，推荐使用：
```
'regex:/^[a-zA-Z0-9]+_[a-zA-Z0-9]+$|^([a-zA-Z0-9]+)$/'
```
此模式匹配两种情形：① abc_def（单下划线居中）；② abcdef（无下划线）。如需更严格（如禁止首尾下划线 + 仅限 1 个），可进一步用 (?=^[^_].*[^_]$) 断言首尾非 _，再配合 ^(?=[^_]).*(?
错误聚合策略：上述示例仅返回首个验证失败项的结构化错误（符合提问中“返回对应 code 的一条消息”需求）。若需返回所有错误，可遍历 $validator->errors()->messages() 并逐条 json_decode 后合并为数组。
复用性建议：将 $customMessages 和验证逻辑抽离为独立服务类或 FormRequest 子类，配合 failedValidation() 重写，可全局统一 API 错误格式。
注意事项：
- json_encode 在消息中使用时，务必确保后续 json_decode(..., true) 成功，避免因引号转义导致解析失败；
- unique:users 规则默认检查 username 字段，若数据库字段名不同（如 user_name），需显式指定：unique:users,user_name；
- 生产环境建议添加 try/catch 捕获 ValidationException，防止未预期异常穿透。