为统一开发的接口格式, 提高开发效率. 现对开发接口的格式作统一要求. 大家有更好的建议, 欢迎提出.
数据格式: JSON
返回基础字段: status, info, data
status:
int类型, 必选. 返回状态, 只有两种可能, 0或1, 0状态说明此返回值需要Toastr提醒用户, 如: 用户名或密码不正确. 数据为空时此项值并不是0, 而是1. 如当一个新闻列表没有任何新闻, 这时status的值依然是1. 前端在数据列表时需要先判断status值为1, 再判断data值为"", 才跳转内容为空的页面. 为1的其它情况, 如登录成功, 注册成功. 一般为1时并不需要Toastr用户.
info:
string类型, 必选. 返回值的说明信息. 一般在status值为0时, 此值起作用. 因为此信息需要展示给用户, 所以此信息需要说明情况, 语言上要比较人性化. 如在登录失败时可以返回: "您输入用户名或密码有误, 请再试一次", 要比"用户或密码错误"这样的提示更友好. 在status状态为1时, 这时候页面展示的内容一般为data字段里的内容, 或着页面需要进行跳转. 所以这时的info信息主要是给前端开发人员看的, 或是调试用的, 并不重要.
data:
json array类型, 可选 此值作用时间和info正好相反. 当status值为1时起作用, 当status值为0时此值为空的json数组(请注意字段类为array json类型, 但并不是null或""). 此值并不是必选项, 有些接口即使status值为1时, 此值也可以为空json数组, 如短信验证码验证成功的接口返回
{
"status": 1,
"info": "验证正确",
"data": [] // 此值为[], 空的json数组, 不得为null
}
关于data项除了上面说的为空的情况, 主要还有另外几种情况
1. 一维数组, 如用户登录成功后的返回
{
"status": 1,
"info": "登录成功",
"data": {
"user_id": "98",
"user_name": "",
"mobile": "18953935328"
}
}
2. 二维数组多条记录, 如获取轮播图接口
{
"status": 1,
"info": "轮播图",
"data": [
{
"ad_id": "1",
"title": "手机首页",
"link_url": "",
"content": "/Uploads/Picture/Ad/2017-06-26/5950cf0a93c2f.jpg"
},
{
"ad_id": "2",
"title": "手机首页2",
"link_url": "",
"content": "/Uploads/Picture/Ad/2017-06-26/c2f50c5993f0a.jpg"
}
]
}
3. 多维数组. 如获取产品的分类列表
{
"status": 1,
"info": "全部分类",
"data": [
{
"cat_id": "194", //分类id
"cat_name_mobile": "裙装", //分类名称
"image": "", //分类图片
"parent_id": "0", //上级id
"_child": [
{
"cat_id": "205",
"cat_name_mobile": "包裙",
"image": "",
"parent_id": "194"
},
{
"cat_id": "204",
"cat_name_mobile": "半身裙",
"image": "",
"parent_id": "194"
}
]
},
{
"cat_id": "156",
"cat_name_mobile": "上装",
"image": "",
"parent_id": "0",
"_child": [
{
"cat_id": "165",
"cat_name_mobile": "背心",
"image": "",
"parent_id": "156"
},
{
"cat_id": "164",
"cat_name_mobile": "马甲",
"image": "",
"parent_id": "156"
}
]
}
]
}
4. 混合的多维数据, 如商品详情接口
{
"status": 1,
"info": "商品详情",
"data": { //商品基本信息
"goods_info": {
"goods_id": "225",
"goods_name": "个性8字韩版TTT",
"shop_id": "1",
},
"goods_gallery": [ //商品轮播图
{
"img_id": "912",
"image_path": "/Uploads/Picture/Goods/2017-07-20/59706709bd6ad.jpg"
},
{
"img_id": "911",
"image_path": "/Uploads/Picture/Goods/2017-07-20/59706709bd6ad.jpg"
}
],
"goods_attr": [ //商品属性值
{
"attr_name": "风格", //名称
"attr_value": "复古" //值
},
{
"attr_name": "厚度",
"attr_value": "适中"
}
],
"goods_desc": [ //商品详情图
{
"img_id": "912",
"image_path": "/Uploads/Picture/Goods/2017-07-20/59706709bd6ad.jpg"
},
{
"img_id": "911",
"image_path": "/Uploads/Picture/Goods/2017-07-20/59706709bd6ad.jpg"
}
],
"shop_info": {
"shop_id": "1",
"shop_name": "六牛科技自营", //店铺名称
"shop_logo": "", //店铺logo
"shop_addr": "山东省·临沂市·临沂市河东区山东六牛网络科技有限公司",
},
"shop_comment": { //店铺评论
"ravorableRate": 67, //好评率
"commentCount": "3", //评价总数
"newComment": [
{
"user_id": "98",
"content": "ssdffsfds", //评价内容
}
]
}
}
}
以上4种情况对数据通讯来说基本都能满足, 在后端开发中请尽量向这4种方式靠近, 如果以上四种方式不能满足开发需求, 请通知开发组长, 确认后完善此文档. 三个字段名称status, info, data不得修改.
为通一数据口, 在返回数据时通一调用以下公用函数:
/**
* 返回JSON通一格式
* @param int $status 要返回的状态
* @param string $info 要返回的提示信息
* @param array $data 要返回数据数组
* @return array
*/
function V($status = -1, $info = '', $data = array()) {
if ($status == -1) {
exit('status参数值错误');
}
if ($data == '' || $data == null) {
$data = array();
}
if (!is_array($data)){
exit('data数据类型不正确');
}
return array('status' => $status, 'info' => $info, 'data' => $data);
}
调用代码示例
// 找回密码 --- 验证手机号码
function checkFindpwdMobile() {
$mobile = I('mobile', '');
$result = D('Home/User')->checkUserExist($mobile);
if ($result == false) { // 不存在
$this->ajaxReturn(V(0, '手机号码不存在'));
}
$this->ajaxReturn(V(1, '验证正确'));
}