Question

使用JSON格式化响应的正确方法是什么？为什么？我看过不同的服务有两种方式，考虑一个简单的GET /users资源：

{
    "success": true,
    "message": "User created successfully",
    "data": [
        {"id": 1, "name": "John"},
        {"id": 2, "name": "George"},
        {"id": 3, "name": "Bob"},
        {"id": 4, "name": "Jane"}
    ]
}

这就是我通常这样做的方式。我有一些抽象的辅助字段，如success和message，可能还有更多，但问题是我是否应该将data字段中的数据嵌套到一个名为资源 - users：

{
    "success": true,
    "message": "User created successfully",
    "data": {
        "users": [
            {"id": 1, "name": "John"},
            {"id": 2, "name": "George"},
            {"id": 3, "name": "Bob"},
            {"id": 4, "name": "Jane"}
        ]
    }
}

即使我们不使用抽象：

{
    "users": [
        {"id": 1, "name": "John"},
        {"id": 2, "name": "George"},
        {"id": 3, "name": "Bob"},
        {"id": 4, "name": "Jane"}
    ]
}

似乎users密钥已过时，因为任何客户端都会知道他们调用的路由，其中包含/users，其中提到了用户，以及客户端代码，如

$users = $request->perform('http://this.api/users')->body()->json_decode();

看起来比

好多了

$users = $request->perform('http://this.api/users')->body()->json_decode()->users;

因为它避免重复users。

Answer 1

为了获得同一页面，data是JSON对象中的一个字段。在第一个示例中，data的值是一个数组。在第二个示例中，data的值是一个对象。

要么是有效的，那么要回答你的问题：不需要在命名对象中嵌套命名对象。必须命名对象的所有字段，但您可以在对象中嵌套数组。

这实际上取决于处理器的期望。如果data可以是任何东西，那么第一种方法就可以了。如果代码期望data字段的值是一个对象，那么你必须使用类似第二个例子的东西。

Answer 2

信封有用的一个用例是当您希望处理大型列表并需要进行分页以防止大量响应有效负载时。信封是放置分页元数据的好地方：

{
    "users": [...],
    "offset": 0,
    "limit": 50,
    "total": 10000
}

（这是我们在RESTful API中所做的工作）

显然，这仅适用于返回事物列表的请求（例如/users/），而不适用于返回单个实体的请求（例如/users/42），甚至对于返回列表的请求，您也不会t 使用信封 - 一种替代方法是使用此元数据的响应标头。

PS。如果你有一个具体的用例，我只建议你有一个success和message字段。否则不要打扰，他们根本就没必要。

Answer 3

根据您在第一条评论中添加的评论：更多描述性数据是更好的数据，因为每个信息对您的API - REST端点的消费者都有用。因此，如果您知道内容是用户或其他内容，最好在架构或端点网址中使用它。

更好的描述=更好的消费： - ）

是否有必要将一组对象嵌套在命名对象中

3 个答案: