是否存在从API构建JSON响应的标准或最佳实践?显然,每个应用程序的数据都是不同的,所以我不太关心,而是“响应样板”,如果你愿意的话。我的意思是:
成功的请求:
{
"success": true,
"payload": {
/* Application-specific data would go here. */
}
}
失败的请求:
{
"success": false,
"payload": {
/* Application-specific data would go here. */
},
"error": {
"code": 123,
"message": "An error occurred!"
}
}
假设您的问题是关于REST Web服务设计,更准确地说是关于成功/错误。
我认为有三种不同类型的设计。
仅使用HTTP状态代码来指示是否存在错误,并尝试将自己限制在标准状态(通常这就足够了)。优点:它是一个独立于api的标准。缺点:关于真实发生的事情的信息较少。使用HTTP Status+json主体(即使是错误)。为错误定义一个统一的结构(例如:代码、消息、原因、类型等),并将其用于错误,如果成功,则返回预期的json响应。优点:仍然是标准的,因为您使用现有的HTTP状态代码,并返回一个描述错误的json(您提供了有关发生的更多信息)。缺点:输出json会因错误或成功而有所不同。忘记http状态(例如:always status 200),始终使用json,并在响应的根位置添加一个布尔responseValid和一个错误对象(代码、消息等),如果是错误,将填充该对象,否则将填充其他字段(成功)。优点:客户端只处理作为json字符串的响应主体,而忽略状态(?)。缺点:标准越低。
这取决于您的选择:)
根据API的不同,我会选择2或3(对于json rest API,我更喜欢2)。我在设计RESTApi时经历的另一件事是每个资源(url)的文档的重要性:参数、主体、响应、头等+示例。
我还建议您使用jersey(jax-rs实现)+genson(java/json数据绑定库)。您只需在类路径中删除genson+jersey,就会自动支持json。
编辑:
解决方案2是最难实现的,但它的优点是,您可以很好地处理异常,而不仅仅是业务错误,最初的努力更重要,但从长远来看,您会赢得胜利。解决方案3在服务器端和客户端都很容易实现,但它并不是很好,因为您必须将要返回的对象封装在包含responseValid+错误的响应对象中。
我想事实上的标准还没有真正出现(可能永远不会)。但无论如何,我的看法是:
成功的请求:
{
"status": "success",
"data": {
/* Application-specific data would go here. */
},
"message": null /* Or optional success message */
}
失败的请求:
{
"status": "error",
"data": null, /* or optional error payload */
"message": "Error xyz has occurred"
}
优势:成功和错误案例中的顶级元素相同
缺点:没有错误代码,但如果您愿意,您可以将状态更改为(成功或失败)代码,或者-您可以添加另一个名为“代码”的顶级项。