Laravel JSON:API请求校验揭秘ResourceRequest如何验证JSON:API文档并输出标准错误【免费下载链接】laravelJSON:API for Laravel applications项目地址: https://gitcode.com/gh_mirrors/laravel10/laravel如果你正在使用laravel-json-apiJSON:API for Laravel applications开发接口一定遇到过为什么我的请求返回 422的疑问。本文带你完整揭秘 **Laravel JSON:API 请求校验机制ResourceRequest如何按三步流水线验证请求从媒体类型检查、JSON:API 文档合规性检查到属性级校验规则最终输出带source pointer的标准 JSON:API 错误响应** 校验链全景4 个核心文件先认识一下文件角色src/Http/Requests/ResourceRequest.php请求校验核心文档验证、校验数据组装、错误输出src/Http/Requests/FormRequest.php基类识别 JSON:API 媒体类型与请求动作增删改查/关系src/Http/Requests/RequestResolver.php资源类型 → 你的 Request 类的定位器src/Exceptions/HttpUnsupportedMediaTypeException.php媒体类型错误时抛出的 415 异常RequestResolver的定位逻辑很直观先查你手动注册的自定义绑定否则就用当前 Schema 类名把Schema替换成Request例如PostSchema→PostRequest见 RequestResolver.php#L86-L111。这就是为什么每个资源的 Request 类和 Schema 类放在同一个目录里。 第一步媒体类型检查最快失败在真正校验数据之前prepareForValidation()会先检查请求头Content-Type是否为application/vnd.apijson见 ResourceRequest.php#L299-L308✅ 是 → 继续进入 JSON:API 文档合规性检查❌ 否 → 抛出HttpUnsupportedMediaTypeException客户端收到415 Unsupported Media Type这一步保证了只有说 JSON:API 语言的请求才会进入后续流程是典型的快速失败fail fast设计。 第二步JSON:API 文档合规性检查这是很多新手不知道的一步你的 JSON 请求体必须符合 JSON:API 规范而不只是能被解析。创建/更新资源时validateResourceDocument()用ResourceBuilder按路由的资源类型及资源 ID构建文档文档非法则抛出JsonApiException见 ResourceRequest.php#L549-L564修改关系时relationships子资源改用RelationBuilder校验关系文档见 ResourceRequest.php#L572-L586如果请求体连 JSON 都解码不了比如 POST 空请求体你会看到一条400 Invalid JSON的标准错误验收测试 RequestBodyContentTest.php#L42-L53 展示了完整结构{ jsonapi: { version: 1.0 }, errors: [{ detail: Expecting JSON to decode., status: 400, title: Invalid JSON }] } 第三步属性级校验规则你写 rules() 的地方文档合规通过后才轮到你熟悉的 Laravel 校验器上场。ResourceRequest按请求类型选择不同的校验器见 ResourceRequest.php#L350-L361删除请求→ 使用你定义的deleteRules()可配合metaForDelete()注入业务数据关系修改请求→ 只取rules()中属于当前关系字段名的规则见 ResourceRequest.php#L533-L541其他请求→ 走标准rules()方法官方示例 PostRequest.php#L25-L42 展示了完整写法public function rules(): array { return [ content [required, string], slug [required, string, $unique], tags JsonApiRule::toMany(), // 专用于 to-many 关系 ]; } 新建自己的 Request 类时可以用php artisan的make命令生成骨架对应模板 stubs/request.stub。 三种请求三种校验数据组装方式校验器校验的数据并非你的原始请求体而是validationData()精心组装的结果见 ResourceRequest.php#L210-L235请求类型校验数据来源关键细节创建POST请求体data直接取值只校验客户端提交的字段更新PATCH现有模型属性 提交字段合并遵循 JSON:API 规范缺省属性视为保持当前值而不是 null见 dataForUpdate#L432-L443关系修改包装成relationships.字段名.data结构见 validationDataForRelationship#L242-L251删除DELETE从模型提取属性可注入meta支持deleteRules()自定义业务校验见 dataForDelete#L474-L483⚠️ 一个容易踩坑的点更新请求的校验数据是合并后的所以required这类规则在 PATCH 请求中基本不会失败缺省值来自数据库你需要用update_if等条件规则来精确控制。⚠️ 标准错误输出422 错误背后的真相校验失败后failedValidation()并不会走 Laravel 默认的 HTML/JSON 错误格式而是调用 JSON:API 专属的校验错误工厂生成错误再抛出JsonApiException见 ResourceRequest.php#L313-L335删除请求走createErrorsForDeleteResource其余走createErrorsForResource。最终客户端收到的是标准 JSON:API 错误文档422 Unprocessable Entity每个错误都带source pointer精确定位到出错字段测试 CreateTest.php#L103-L116 就是很好的样例{ errors: [{ detail: The slug has already been taken., source: { pointer: /data/attributes/slug }, status: 422, title: Unprocessable Entity }] }pointer的值与请求体结构一一对应属性错误指向/data/attributes/xxx关系错误指向/data/relationships/xxx。前端只需解析errors数组即可逐字段提示用户无需关心具体框架细节 ✨ 常见校验问题速查表状态码触发原因排查方向400 Invalid JSON请求体不是合法 JSON / 空请求体检查是否遗漏请求体、Content-Length415 Unsupported Media TypeContent-Type不是application/vnd.apijson见 isJsonApi#L55-L58422 source.pointer属性校验规则未通过对照rules()与pointer定位字段422 文档结构错误JSON:API 文档不合规缺type/attributes等对照 JSON:API 规范修正请求体结构小结ResourceRequest的校验流水线可以概括为一句话先验语言媒体类型再验语法JSON:API 文档结构最后验内容属性规则任何一步失败都会输出统一的 JSON:API 标准错误。理解这条链路后无论是调试客户端请求还是为资源编写PostRequest这样的自定义校验类你都能快速定位问题所在 相关源码目录请求与校验 src/Http/Requests/、HTTP 异常 src/Exceptions/、路由与动作 src/Routing/【免费下载链接】laravelJSON:API for Laravel applications项目地址: https://gitcode.com/gh_mirrors/laravel10/laravel创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考