json - REST API 状态是整数还是字符串？

Question

我和我的同事正在研究 REST API。我们一直在争论资源/项目的状态应该是字符串还是整数——我们都需要阅读、理解和修改该资源(使用单独的应用程序)。由于这是一个非常笼统的主题，谷歌没有帮助解决这个争论。我想知道你的经验是什么，哪种方式更好。

例如，假设我们有Job 资源，可以通过URI http://example.com/api/jobs/someid 访问它。它具有以下存储在 NoSQL DB 中的 JSON 表示形式:

JOB A:
{
   "id": "someid",
   "name": "somename",
   "status": "finished"  // or "created", "failed", "compile_error"
}

所以我的问题是 - 也许它应该更像是跟随？

JOB B:
{
   "id": "someid",
   "name": "somename",
   "status": 0  // or 1, 2, 3, ...
}

在这两种情况下，我们每个人都必须创建一个 map ，我们用它来理解我们应用程序逻辑中的状态。但我自己倾向于第一个，因为它更具可读性......您也可以轻松混淆 '0'(字符串)和 0(数字)。

但是，由于 API 由机器使用，因此可读性并不那么重要。使用数字还有其他一些优点 - 在控制台中使用应用程序时它被广泛接受，并且当你想包含任意新的失败状态时它会很有用，比如:

• status == 50 - 表示您的网络组件 X 有问题，
• status > 100 - 表示一些多个特殊情况。

当你有数字时，你不需要为它们组成所有那些字符串名称。那么您认为哪种方式最好？也许我们需要多个字段(这可能会使事情变得有点困惑):

JOB C:
{
   "id": "someid",
   "name": "somename",
   "status": 0, // or 1, 2, 3...
   "error_type": "compile_error",
   "error_message": "You coding skill has failed. Please go away"
}

Answer 1

就我个人而言，我会考虑结合使用您提到的两种方法来处理这种情况。我会将状态作为整数存储在数据库中，但会创建一个枚举或常量类以将状态名称映射到数字状态值。

例如(在 C# 中):

public enum StatusType
{
    Created = 0,
    Failed = 1,
    Compile_Error = 2,

    // Add any further statuses here.
}

然后您可以将存储在数据库中的数字状态转换为该枚举的一个实例，并在整个代码中使用它进行决策。

例如(在 C# 中):

StatusType status = (StatusType) storedStatus;

if(status == StatusType.Created)
{
    // Status is created.
}
else
{
   // Handle any other statuses here.
}

如果你很迂腐，你也可以将这些映射存储在你的数据库中。

要通过 API 进行访问，您可以根据自己的要求选择任何一种方式。您甚至可以返回包含状态编号和状态文本的结果:

object YourObject
{
    status_code = 0,
    status = "Failed"
}

您还可以创建一个 API 来从代码中检索状态名称。但是，从性能的角度来看，在 API 中返回状态代码和名称是最好的。