res.api用法说明(支持express和koa)
发布于 19天前 作者 i5ting 464 次浏览 来自 分享

res.api

res.api is an express middleware for render json api , it convention over api format like this :

{
  data: {

  },
  status: {
    code : x,
    msg  : 'some message'
  }
}

more see at cnodejs 客户端 API 开发总结

Install

npm install --save res.api

Usages

var express       = require('express');
var res_api       = require('res.api');

var app = new express();
app.use(res_api);

then in some route

way 1

return res.api(404 ,err, {
  code : 1,
  msg  : 'delete failed!'
});

the response header is :

HTTP/1.1 404 Not Found
X-Powered-By: Express
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST
Access-Control-Allow-Headers: X-Requested-With,content-type, Authorization
Content-Type: application/json; charset=utf-8
Content-Length: 239
ETag: W/"ef-6e66e2da"
set-cookie: connect.sid=s%3ApwL-xMS2tCh3qgqp_wyIqukbUKFeJv6S.2EB4449yTlxRWZrRyBXRc9J6Pv%2BNz4M7j35VLIlxE6M; Path=/; Expires=Wed, 17 Jun 2015 15:11:28 GMT; HttpOnly
Date: Wed, 17 Jun 2015 14:41:28 GMT
Connection: keep-alive

response json data

{
  "data": {
    "message": "Cast to ObjectId failed for value \"557a3e326221681d474cf078sdsds\" at path \"_id\"",
    "name": "CastError",
    "kind": "ObjectId",
    "value": "557a3e326221681d474cf078sdsds",
    "path": "_id"
  },
  "status": {
    "code": 1,
    "msg": "delete failed!"
  }
}

way 2

return res.api(data, {
  code : 1,
  msg  : 'delete failed!'
});

the response header is :

HTTP/1.1 200 Ok
X-Powered-By: Express
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST
Access-Control-Allow-Headers: X-Requested-With,content-type, Authorization
Content-Type: application/json; charset=utf-8
Content-Length: 239
ETag: W/"ef-6e66e2da"
set-cookie: connect.sid=s%3ApwL-xMS2tCh3qgqp_wyIqukbUKFeJv6S.2EB4449yTlxRWZrRyBXRc9J6Pv%2BNz4M7j35VLIlxE6M; Path=/; Expires=Wed, 17 Jun 2015 15:11:28 GMT; HttpOnly
Date: Wed, 17 Jun 2015 14:41:28 GMT
Connection: keep-alive

response json data

{
  "data": {
    "message": "Cast to ObjectId failed for value \"557a3e326221681d474cf078sdsds\" at path \"_id\"",
    "name": "CastError",
    "kind": "ObjectId",
    "value": "557a3e326221681d474cf078sdsds",
    "path": "_id"
  },
  "status": {
    "code": 1,
    "msg": "delete failed!"
  }
}

way 3

return res.api(data);

the response header is :

HTTP/1.1 200 Ok
X-Powered-By: Express
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST
Access-Control-Allow-Headers: X-Requested-With,content-type, Authorization
Content-Type: application/json; charset=utf-8
Content-Length: 239
ETag: W/"ef-6e66e2da"
set-cookie: connect.sid=s%3ApwL-xMS2tCh3qgqp_wyIqukbUKFeJv6S.2EB4449yTlxRWZrRyBXRc9J6Pv%2BNz4M7j35VLIlxE6M; Path=/; Expires=Wed, 17 Jun 2015 15:11:28 GMT; HttpOnly
Date: Wed, 17 Jun 2015 14:41:28 GMT
Connection: keep-alive

response json data

{
  "data": {
    "message": "Cast to ObjectId failed for value \"557a3e326221681d474cf078sdsds\" at path \"_id\"",
    "name": "CastError",
    "kind": "ObjectId",
    "value": "557a3e326221681d474cf078sdsds",
    "path": "_id"
  },
  "status": {
    "code": 0,
    "msg": "deleterequest success!"
  }
}

way 4:快捷错误处理

return res.api_error(err);

the response header is :

HTTP/1.1 200 Ok
X-Powered-By: Express
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST
Access-Control-Allow-Headers: X-Requested-With,content-type, Authorization
Content-Type: application/json; charset=utf-8
Content-Length: 239
ETag: W/"ef-6e66e2da"
set-cookie: connect.sid=s%3ApwL-xMS2tCh3qgqp_wyIqukbUKFeJv6S.2EB4449yTlxRWZrRyBXRc9J6Pv%2BNz4M7j35VLIlxE6M; Path=/; Expires=Wed, 17 Jun 2015 15:11:28 GMT; HttpOnly
Date: Wed, 17 Jun 2015 14:41:28 GMT
Connection: keep-alive

response json data

{
  "data": {
    "message": "Cast to ObjectId failed for value \"557a3e326221681d474cf078sdsds\" at path \"_id\"",
    "name": "CastError",
    "kind": "ObjectId",
    "value": "557a3e326221681d474cf078sdsds",
    "path": "_id"
  },
  "status": {
    "code": -1,
    "msg": "api error"
  }
}

video

录了一段7分钟的视频:

http://pan.baidu.com/s/1eQo4xqi

一直想写,今天终于写出来了,懒人还是有救的

另外Koa支持见12楼

15 回复

如果想参考 HTTP API design guide extracted from work on the Heroku Platform API,也不冲突

https://github.com/interagent/http-api-design#generate-structured-errors

录了一段7分钟的视频:

http://pan.baidu.com/s/1eQo4xqi

自取

我了个去,竟然可以直接播放

我觉得吧,可以再精简,把status 去掉,只复用和扩展http状态码。比如: 七牛api

发来发去这些内容啊,too simple,sometime naive

@captainblue2013 这确实是科普的,入门级,我的目的也是这个,另外还有个目的是招人

你想来点啥高深的,我来回你,ok么?

@hezedu 扩展http状态码并不见得是好的方式,这个问题已经争论很久了

https://cnodejs.org/topic/552b3b9382388cec50cf6d95

这里会有对应的总结

另外业务代码很多的时候,3位根本是不够的

@i5ting Koa里能直接用吗?

@SoaringTiger 可以的

https://github.com/moajs/koa.res.api

Install

npm install --save koa.res.api

Usages

var koa     = require('koa');
var app     = koa();    
var res_api = require('koa.res.api');

app.use(res_api());

then in some route

way 1:最通用的api接口

this.api(404 , err, {
  code : 1,
  msg  : 'delete failed!'
});

the response header is :

HTTP/1.1 404 Not Found
X-Powered-By: Express
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST
Access-Control-Allow-Headers: X-Requested-With,content-type, Authorization
Content-Type: application/json; charset=utf-8
Content-Length: 239
ETag: W/"ef-6e66e2da"
set-cookie: connect.sid=s%3ApwL-xMS2tCh3qgqp_wyIqukbUKFeJv6S.2EB4449yTlxRWZrRyBXRc9J6Pv%2BNz4M7j35VLIlxE6M; Path=/; Expires=Wed, 17 Jun 2015 15:11:28 GMT; HttpOnly
Date: Wed, 17 Jun 2015 14:41:28 GMT
Connection: keep-alive

response json data

{
  "data": {
    "message": "Cast to ObjectId failed for value \"557a3e326221681d474cf078sdsds\" at path \"_id\"",
    "name": "CastError",
    "kind": "ObjectId",
    "value": "557a3e326221681d474cf078sdsds",
    "path": "_id"
  },
  "status": {
    "code": 1,
    "msg": "delete failed!"
  }
}

way 2:返回成功带有状态的json数据

this.api(data, {
  code : 1,
  msg  : 'delete failed!'
});

the response header is :

HTTP/1.1 200 Ok
X-Powered-By: Express
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST
Access-Control-Allow-Headers: X-Requested-With,content-type, Authorization
Content-Type: application/json; charset=utf-8
Content-Length: 239
ETag: W/"ef-6e66e2da"
set-cookie: connect.sid=s%3ApwL-xMS2tCh3qgqp_wyIqukbUKFeJv6S.2EB4449yTlxRWZrRyBXRc9J6Pv%2BNz4M7j35VLIlxE6M; Path=/; Expires=Wed, 17 Jun 2015 15:11:28 GMT; HttpOnly
Date: Wed, 17 Jun 2015 14:41:28 GMT
Connection: keep-alive

response json data

{
  "data": {
    "message": "Cast to ObjectId failed for value \"557a3e326221681d474cf078sdsds\" at path \"_id\"",
    "name": "CastError",
    "kind": "ObjectId",
    "value": "557a3e326221681d474cf078sdsds",
    "path": "_id"
  },
  "status": {
    "code": 1,
    "msg": "delete failed!"
  }
}

way 3:最常用的成功返回json数据

this.api(data);

the response header is :

HTTP/1.1 200 Ok
X-Powered-By: Express
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST
Access-Control-Allow-Headers: X-Requested-With,content-type, Authorization
Content-Type: application/json; charset=utf-8
Content-Length: 239
ETag: W/"ef-6e66e2da"
set-cookie: connect.sid=s%3ApwL-xMS2tCh3qgqp_wyIqukbUKFeJv6S.2EB4449yTlxRWZrRyBXRc9J6Pv%2BNz4M7j35VLIlxE6M; Path=/; Expires=Wed, 17 Jun 2015 15:11:28 GMT; HttpOnly
Date: Wed, 17 Jun 2015 14:41:28 GMT
Connection: keep-alive

response json data

{
  "data": {
    "message": "Cast to ObjectId failed for value \"557a3e326221681d474cf078sdsds\" at path \"_id\"",
    "name": "CastError",
    "kind": "ObjectId",
    "value": "557a3e326221681d474cf078sdsds",
    "path": "_id"
  },
  "status": {
    "code": 0,
    "msg": "request success!"
  }
}

way 4:快捷错误处理

this.api_error(err);

the response header is :

HTTP/1.1 200 Ok
X-Powered-By: Express
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST
Access-Control-Allow-Headers: X-Requested-With,content-type, Authorization
Content-Type: application/json; charset=utf-8
Content-Length: 239
ETag: W/"ef-6e66e2da"
set-cookie: connect.sid=s%3ApwL-xMS2tCh3qgqp_wyIqukbUKFeJv6S.2EB4449yTlxRWZrRyBXRc9J6Pv%2BNz4M7j35VLIlxE6M; Path=/; Expires=Wed, 17 Jun 2015 15:11:28 GMT; HttpOnly
Date: Wed, 17 Jun 2015 14:41:28 GMT
Connection: keep-alive

response json data

{
  "data": {
    "message": "Cast to ObjectId failed for value \"557a3e326221681d474cf078sdsds\" at path \"_id\"",
    "name": "CastError",
    "kind": "ObjectId",
    "value": "557a3e326221681d474cf078sdsds",
    "path": "_id"
  },
  "status": {
    "code": -1,
    "msg": "api error"
  }
}

第一个usage里的var res.api = require('res.api');真的不会报错么

@hwoarangzk 会的,变量名res_api,才可以

楼主,模块名里有点号真的好么 ,感觉怪怪的。

回到顶部