Rest API 最佳实践返回单个字符串与将其包装在 JSON ZA8CFDE6331BD1C49EB2AC96F861

Question

我有一个可以返回几种状态之一的端点，例如“活动”、“取消”等。

在响应中将其作为字符串返回是不好的做法，例如：

"Active"

或者我应该将它包装在 JSON object 中，例如：

{
    "status": "Active"
}

Answer 1

JSON 当前 注册的参考是RFC 8259

JSON 值必须是 object、数组、数字或字符串，或以下三个文字名称之一：

• 错误的
• null
• 真的

因此，当这是您的资源的自然表示时，返回带引号的字符串很好。

---

事情有可能变得复杂：稍后发现资源的自然表示是消息，而不是字符串。

使用 object 的理由是，它使我们能够灵活地向模式引入向后兼容的更改，以便我们可以包含更多信息，而不会破坏只知道原始模式的客户端。 当您的表示“只是”一个字符串时，这要困难得多。

但这是一种折衷：当您只需要一根弦时，您为未来的灵活性付出的代价是稍微不方便处理。

如果您控制了所有 API 消费者，并且可以与模式同步更改消费者，那么您可以从简单的答案开始，如果您需要更复杂的表示，则可以着手解决所有问题。

如果您无法控制客户，或者进行同步更改成本高昂，那么这个计划就没有那么吸引人了。

如果您正在创建一个外部暴露的 API，那么您不太可能控制所有客户端。

也就是说，通过精心设计，您还可以选择仅引入新资源来涵盖您实际需要具有多个值的消息的情况。

我在这里最强烈的建议：无论你走哪条路，都要留下纸迹。 记录您在做出选择时所知道的一切，以及您预计未来的风险和并发症。 这样，将来您将能够恢复您的决定的上下文。