芒果小站

  1. 全球最具业界良心的主机 - Linode

    毫无疑问,目前做得最好的主机供应商

    猛击这里查看

  2. 芒果小站目前使用的主机 - Linode

    客服响应快,随时退款,XEN 架构稳定

    猛击这里查看

  3. 最好的日本东京线路主机 - Linode

    可选弗里蒙特、达拉斯、亚特兰大、纽瓦克、伦敦、东京机房

    猛击这里查看

  • 1
  • 2
  • 3
切换到精简模式
0

jsend – 更好的接口格式规范

作者 芒果/分类 教程/发布于 2015-01-15 20:11

日常和开发约定 JSON 接口,每次项目都按开发个人喜好给,各种字段定义和命名规范,没法满足我强烈的代码洁癖症。JSend 规范足够简单地描述了 JSON 接口结构,具备普遍适用性,推荐给大家。

———- 分割线 ———-

  • What? – 简而言之,JSend 是一个规范,规定了服务端响应 JSON 格式的规则。JSend 专注于应用程序级(相对于协议或传输级)信息传输,使得它非常适合在 REST 风格的应用或 API 中使用。
  • Why? – 大量的 Web 服务以 JSON 方式提供数据,并且每个服务都有自己的响应格式。为了能和服务端进行数据通信,前端开发者需要不断地重复造轮子。虽然有许多通用的模式进行来构建这个数据,但是缺少诸如命名或响应类型等方面的一致性。JSend 将助于促进前后端之间的接口统一,按通用的规则来进行数据交互。

如何工作?

一个基本的遵循 JSend 规范的响应,就这么简单:

{
    status : "success",
    data : {
        "post" : { "id" : 1, "title" : "A blog post", "body" : "Some useful content" }
     }
}

编写 JSON API 时,你需要不同的类型来描述各种调用和响应。JSend 将响应分成一些基本的类型,同时指定了必要的和可选的字段:

类型 描述 必要字段 可选字段
success 一切正常,并且(通常是)返回了一些数据 status, data
fail 提交的数据有问题,或者 API 调用的一些前提条件不满足 status, data
error 处理请求时出错,例如:一个异常被抛出 status, message code, data

响应类型示例

成功: 当 API 调用成功时,JSend 对象只对作简单包裹,使用 data 字段即可,例如:

GET /posts.json:

{
    status : "success",
    data : {
        "posts" : [
            { "id" : 1, "title" : "A blog post", "body" : "Some useful content" },
            { "id" : 2, "title" : "Another blog post", "body" : "More content" },
        ]
     }
}

GET /posts/2.json:

{
    status : "success",
    data : { "post" : { "id" : 2, "title" : "Another blog post", "body" : "More content" }}
}

DELETE /posts/2.json:

{
    status : "success",
    data : null
}

必要字段:

  • status: 应始终设置为 “success”。
  • data: 提供 API 调用返回数据的包裹,如果调用没有返回数据(如最后一个例子),该字段应被设置为 null。

失败: 当 API 调用由于无效数据或不满足调用条件而被拒绝时,JSend 对象定义了一个用于说明出错原因的字段,通常是字段验证错误。例如:

POST /posts.json: (假定请求数据为 body: "Trying to creating a blog post"

{
    "status" : "fail",
    "data" : { "title" : "A title is required" }
}

必要字段:

  • status: 应始终设置为 “fail”。
  • data: 提供请求失败的具体原因描述。如果失败的原因对应 POST 值,响应对象的字段应当和这些 POST 值一一对应。

错误: 当由于服务器的错误导致 API 调用失败时候,例如:

GET /posts.json:

{
    "status" : "error",
    "message" : "Unable to communicate with database"
}

必要字段:

  • status: 应始终设置为 “error”。
  • message: 提供有意义的、用户易读的信息,说明出错的原因。

可选字段:

  • code: 对应错误的数字代码(如果适用)。
  • data: 有关该错误的任何其他信息,例如:即引起错误,堆栈跟踪等条件。

为何不使用 HTTP?

你可能会问,HTTP 默认已经提供了响应状态,为什么不直接使用?

我们知道,在 HTTP 协议提供了 41 种状态码,以及每一种状态码的适用场景,但无法准确地描述服务端的信息状态。JSend 则从应用服务的层面,补充和规范了更多受限制的状态集合,指导用户界面交互中处理 JSON 数据的过程。

参考资料

版权所有,转载请注明出处。
转载自 <a href="http://mangguo.org/jsend-better-api-format-specification/" title="jsend – 更好的接口格式规范" rel="bookmark">jsend – 更好的接口格式规范 | 芒果小站</a>
如果喜欢这篇文章,欢迎订阅芒果小站以获得最新内容。

下面我简单说几句