API请求必须是JSON格式，否则直接拒绝；需用中间件统一拦截非JSON请求，验证JSON结构应先用required|json确保合法性，再校验内部字段，测试时需显式编码且注意BOM/尾逗号导致静默失败。
API请求必须是JSON格式，否则直接拒绝
Laravel 默认不强制请求体为 JSON，但如果你的 API 设计只接受 application/json，就得主动拦截非 JSON 请求。否则用户发个 application/x-www-form-urlencoded 或空 body，$request->json() 会返回 null，后续取值全崩，还容易漏掉错误提示。
实操建议：
- 在中间件或控制器开头加判断：
if (!$request->isJson()) { return response()->json(['message' => 'Content-Type must be application/json'], 400); } - 更稳妥的做法是用
ValidateJsonMiddleware统一拦截，避免每个接口重复写 - 注意：Nginx/Apache 反向代理时可能吞掉
Content-Type，要确认 header 真的透传到了 Laravel
验证 JSON 结构用 json.validate 规则最直接
Laravel 9+ 原生支持 json 验证规则，能校验字段是否为合法 JSON 字符串；但真正要校验「JSON 内部结构」，得靠 json.validate —— 它其实是 required|json + 自定义逻辑的组合，不是内置规则，需要手动实现或借助包。
实操建议：
- 简单场景：用
required|json确保字段存在且可解析，再用json_decode($request->input('data'), true)后做数组级验证 - 复杂嵌套结构：推荐用
spatie/laravel-json-api或自定义JsonStructureRule类，把 schema 写成 PHP 数组，比写一堆*.0.name.required清晰得多 - 别依赖
json.last_name.required这类写法——Laravel 不识别点号路径在 JSON 字段里，会静默失效
validate 和 validateWithBag 对 JSON 字段的处理没区别
很多人以为换方法就能让 JSON 错误提示更友好，其实不然。validate 和 validateWithBag 差异只在错误包名，底层都走同一个验证管道。JSON 字段出错时，报错信息还是取决于你写的规则，比如 'data.*.email' => 'required|email' 能定位到嵌套 email，但前提是 data 先通过 json 校验。
实操建议：
- 先校验顶层 JSON 合法性（
'data' => 'required|json'），再展开校验子字段，顺序不能反 - 如果
data是可选字段，用'data' => 'nullable|json'，否则nullable会让json规则跳过 - 错误消息里别硬写
"data must be valid JSON"，Laravel 默认提示已经够清楚，改它反而增加维护成本
测试非标准 JSON 输入时，Http::asJson() 会自动设 header，但 body 不自动编码
用 Laravel 的 Http 测试工具发请求时，asJson() 只设置 Content-Type: application/json，并不帮你把数组转成 JSON 字符串。如果直接传数组，底层会调 json_encode，但遇到资源、对象或循环引用就挂了，而且错误堆栈指向 HTTP 客户端，不是你的验证逻辑。
实操建议：
- 测试时显式调用
json_encode：Http::asJson()->post('/api/users', json_encode(['name' => ''])) - 用
TestCase::json('POST', '/api/users', ['name' => ''])更省心，它内部已处理编码和 header - 特别注意：
json('POST', ...)发的请求，$request->header('Content-Type')是application/json，但$request->getContent()是原始字符串，不是自动解析后的数组
最容易被忽略的是前端发请求时带 BOM 头或尾部逗号，PHP json_decode 会静默失败，$request->json() 返回 null，但验证器不会报“JSON 解析失败”，只会报“字段缺失”。这种问题只能靠日志里打 $request->getContent() 才能发现。
