日常和开发约定 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 数据的过程。

参考资料

• JSend – http://labs.omniti.com/labs/jsend