SuperAPI AI 工具集

laravel-jsonapi

编程与开发

查看项目

更新于 10-26 16:21

技能介绍

laravel-jsonapi 是一个针对 Laravel 13 中 JSON:API 资源开发的技能,核心目标是借助 Laravel 官方 JsonApiResource 基类,构建符合 JSON:API 规范的 API 端点。

用途 用于在 Laravel 13 项目中规范地输出 JSON:API 响应。技能强调不要自行编写 JSON:API 序列化逻辑,而应继承 JsonApiResource 基类,由基类处理规范中的边界情况,例如 null 与空 data 的区别。

主要能力 基类提供自动设置 Content-Type 为 application/vnd.api+json;支持稀疏字段集,例如 ?fields[posts]=title,created_at;支持关联包含,通过 ?include=author,comments 生成 included 数组;在关联中输出资源标识符,如 {"id":"1","type":"posts"};并可通过 toLinks() / toMeta() 覆写提供链接与元信息。资源类型默认由类名派生(PostResource 对应 posts),仅在必要时覆写 toType()。

使用方式 按技能给出的最小示例,可用 php artisan make:resource PostResource --json-api 生成资源类,继承 JsonApiResource,并通过 $attributes 声明属性、通过 $relationships 声明客户端可包含的关联白名单;控制器中返回 PostResource::collection(Post::with('author')->get())。技能要求使用 $attributes / toAttributes() 而非 toArray(),避免属性与标识符混用破坏合规性。客户端请求须携带 Accept: application/vnd.api+json。技能还规定了强制的代理工作流:实现前并行启动三个代理,分别清点待迁移的 JsonResource 类、核对 JSON:API v1.1 规范中的必需头与结构、拉取 Laravel Eloquent 资源文档示例;实现后运行校验代理。

适用场景 适合需要为 Laravel 应用提供标准 JSON:API 接口、需要字段筛选与关联包含能力、以及需要将现有 JsonResource 迁移到规范资源类的开发工作。参考资料涵盖资源基类、稀疏字段集、关联关系等主题,并提供 PostResource(belongsTo + hasMany)与 UserResource(稀疏字段)模板。

限制与注意事项 关联必须显式加入 $relationships 白名单,未声明的关联会被静默忽略;在 include 中使用关联时应预加载以避免 N+1 查询;绕过资源类返回自定义错误时仍需设置正确的 Content-Type。关于收费、支持平台与效果指标,资料暂未提供。