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

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

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

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

（这是我们在我正在开发的 RESTful API 中所做的）

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

PS。如果您有具体的用例，我只会建议使用 success 和 message 字段。否则不要打扰，它们根本没有必要。

Answer 2

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

两者都是有效的，所以要回答你的问题：不，没有必要将命名对象嵌套在命名对象中。对象的所有字段都必须命名，但您可以在对象中随意嵌套数组。

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

Answer 3

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

更好的描述 = 更好的消费 :-)