怎么对 JSON 表现格式建模

原文链接：How to Model JSON Representation Format - 原文作者：Ramesh Fadatare
本文采用意译的方式

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

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

JSON 字段名

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

json 复制代码

{
  "memberId": "M000000001"
}

NULL 和空白字符

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

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

json 复制代码

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

日期格式

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

1. yyyy-MM-dd

json 复制代码

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

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

json 复制代码

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

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

json 复制代码

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

超媒体链接格式

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

json 复制代码

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

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

错误响应时的格式

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

json 复制代码

{
  "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 表示样例

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

bash 复制代码

{
  "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" : "[email protected]",
  "telephoneNumber" : "09012345678",
  "zipCode" : "1710051",
  "address" : "Tokyo",
  "credential" : {
    "signId" : "[email protected]",
    "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 表现格式建模。