告别API响应混乱：如何用tobscure/json-api构建规范化的PHPJSON-API服务

<code class="bash">composer require tobscure/json-api</code>

<pre class="brush:php;toolbar:false;"><?php

namespace App\Serializers;

use Tobscure\JsonApi\AbstractSerializer;
use Tobscure\JsonApi\Collection;
use Tobscure\JsonApi\Relationship;

class PostSerializer extends AbstractSerializer
{
    protected $type = 'posts'; // 定义资源类型

    // 获取资源ID，默认为模型id属性
    public function getId($post)
    {
        return $post->id;
    }

    // 获取资源属性
    public function getAttributes($post, array $fields = null)
    {
        return [
            'title'      => $post->title,
            'body'       => $post->body,
            'created_at' => $post->created_at->toDateTimeString(),
            'updated_at' => $post->updated_at->toDateTimeString(),
        ];
    }

    // 定义与作者的关联关系 (has-one)
    public function author($post)
    {
        // 假设 $post->author 是一个 User 模型实例
        $element = new \Tobscure\JsonApi\Resource($post->author, new UserSerializer());
        return new Relationship($element);
    }

    // 定义与评论的关联关系 (has-many)
    public function comments($post)
    {
        // 假设 $post->comments 是一个 Comment 模型集合
        $element = new Collection($post->comments, new CommentSerializer());
        return new Relationship($element);
    }

    // 可以为每个资源添加链接
    public function getLinks($post)
    {
        return ['self' => '/posts/' . $post->id];
    }
}

<pre class="brush:php;toolbar:false;"><?php

namespace App\Http\Controllers;

use App\Models\Post; // 假设你的Post模型
use App\Serializers\PostSerializer;
use Tobscure\JsonApi\Collection;
use Tobscure\JsonApi\Document;
use Illuminate\Http\JsonResponse; // Laravel框架的JSON响应

class PostController extends Controller
{
    public function index()
    {
        // 假设我们从数据库获取所有文章，并预加载作者和评论
        $posts = Post::with(['author', 'comments'])->get();

        // 1. 创建一个集合元素，使用PostSerializer序列化每篇文章
        $collection = (new Collection($posts, new PostSerializer()))
            // 2. 指定需要包含的关联关系。客户端可以通过 ?include=author,comments 来请求
            ->with(['author', 'comments']); 

        // 3. 创建一个JSON-API文档，将集合作为主数据
        $document = new Document($collection);

        // 4. 添加文档级别的元数据和链接
        $document->addMeta('total', $posts->count());
        $document->addLink('self', url('/api/posts'));
        // 还可以添加分页链接
        // $document->addPaginationLinks(url('/api/posts'), request()->query(), $offset, $limit, $total);

        // 5. 将文档输出为JSON
        return new JsonResponse($document, 200, [
            'Content-Type' => 'application/vnd.api+json' // 重要的JSON-API内容类型
        ]);
    }

    public function show($id)
    {
        $post = Post::with(['author', 'comments'])->findOrFail($id);

        $resource = (new \Tobscure\JsonApi\Resource($post, new PostSerializer()))
            ->with(['author', 'comments']);

        $document = new Document($resource);
        $document->addLink('self', url('/api/posts/' . $id));

        return new JsonResponse($document, 200, [
            'Content-Type' => 'application/vnd.api+json'
        ]);
    }
}

<pre class="brush:php;toolbar:false;">{
    "data": [
        {
            "type": "posts",
            "id": "1",
            "attributes": {
                "title": "我的第一篇文章",
                "body": "文章内容...",
                "created_at": "2023-01-01T12:00:00",
                "updated_at": "2023-01-01T12:00:00"
            },
            "relationships": {
                "author": {
                    "data": { "type": "users", "id": "101" }
                },
                "comments": {
                    "data": [
                        { "type": "comments", "id": "201" },
                        { "type": "comments", "id": "202" }
                    ]
                }
            },
            "links": {
                "self": "/posts/1"
            }
        }
        // ... 更多文章
    ],
    "included": [
        {
            "type": "users",
            "id": "101",
            "attributes": {
                "name": "张三",
                "email": "zhangsan@example.com"
            },
            "links": {
                "self": "/users/101"
            }
        },
        {
            "type": "comments",
            "id": "201",
            "attributes": {
                "content": "这是一条评论。",
                "created_at": "2023-01-01T13:00:00"
            },
            "links": {
                "self": "/comments/201"
            }
        }
        // ... 更多 included 资源
    ],
    "meta": {
        "total": 10
    },
    "links": {
        "self": "http://example.com/api/posts"
    }
}