怎么对 JSON 表现格式建模

原文链接：How to Model JSON Representation Format - 原文作者：Ramesh Fadatare

本文采用意译的方式

JSON 有很多种表现格式，但是在本文，我们主要讲最流行的 JSON 表现格式。

很多的时候，我们都使用 JSON 格式来展示资源。我们来了解下什么是 JSON 字段名称的命名约定。

JSON 字段名

我们推荐使用 lower camel case（小写驼峰式）作为 JSON 字段名。我们应该考虑到它们在 JavaScript 中的兼容，我们可以假定 JavaScript 为客户端的应用程序。如下面给出的 JSON 样品的小写驼峰式字段命名。在 lower camel case 中，第一个字母是小写，然后子序列的单词开头第一个字母是大写。

{
  "memberId": "M000000001"
}

NULL 和空白字符

我们建议将 NULL 和空白字符区分为 JSON 值。虽然，在应用程序的过程中，NULL 和空白字符通常被认为相等，因为值是被设定到 JSON 中的，我们还是推荐区分 NULL 和空白字符。

例子：JSON 样例中 NULL 和空白字符的区别。

{
  "dateOfBirth": null,
  "address1": ""
}

日期格式

我们推荐使用扩展的 ISO-8601 格式作为 JSON 日期字段格式。当然可以使用扩展 ISO-8601 格式以外的格式。然而，没有特殊的原因，我们推荐使用扩展的 ISO-8601 格式。在 ISO-8601 中有两种格式，基本格式和扩展格式，然而在扩展格式中，其可读性更高。其基本上有以下三种格式：

1. yyyy-MM-dd

{
  "dateOfBirth" : "1977-03-12"
}

2. yyy-MM-dd’T’HH:mm:ss.SSSZ

{
  "lastModifiedAt" : "2014-03-12T22:22:36.637+09:00"
}

3. yyyy-MM-dd’T’HH:mm:ss.SSS’Z’ (format for UTC)

{
  "lastModifiedAt" : "2014-03-12T13:11:27.356Z"
}

超媒体链接格式

我们推荐使用下面这种格式创建 hypermedia link（超媒体链接）。

{
  "links" : [
    {
      "rel" : "ownerMember",
      "href" : "http://example.com/api/v1/memebers/M000000001"
     }
  ]
}

• 链接对象由两个字段组成 - "rel" 和 "href"
• 链接的名称在字段 rel 表明
• 在字段 href 指明可以获取到的 URI
• "links" 是包含集合格式中链接对象的字段

错误响应时的格式

下面是一个当错误被检测到，返回的响应格式的例子。

{
  "code" : "e.ex.fw.7001",
  "message" : "Validation error occurred on item in the request body.",
  "details" : [ {
    "code" : "ExistInCodeList",
    "message" : ""genderCode" must exist in code list of CL_GENDER.",
    "target" : "genderCode"
  } ]
}

在上面的例子中

• 错误代码(code)
• 错误信息(message)
• 错误详情列表(details)是提供错误相应格式。假设发生输入验证错误时候使用错误详情列表。它是一种可以保留发生错误的字段和错误信息的格式。

JSON 表示样例

下面是正常返回数据的案例

{
  "links" : [ {
    "rel" : "self",
    "href" : "http://localhost:8080/rest-api-web/api/v1/members/M000000001"
  } ],
  "memberId" : "M000000001",
  "firstName" : "John",
  "lastName" : "Smith",
  "genderCode" : "1",
  "dateOfBirth" : "2013-03-14",
  "emailAddress" : "user1394794959984@test.com",
  "telephoneNumber" : "09012345678",
  "zipCode" : "1710051",
  "address" : "Tokyo",
  "credential" : {
    "signId" : "user1394794959984@test.com",
    "passwordLastChangedAt" : "2014-03-14T11:02:41.477Z",
    "lastModifiedAt" : "2014-03-14T11:02:41.477Z"
  },
  "createdAt" : "2014-03-14T11:02:41.477Z",
  "lastModifiedAt" : "2014-03-14T11:02:41.477Z"
}

总结

在本文中，我们学习了怎么对 JSON 表现格式建模。