app接口代码规范

为统一开发的接口格式, 提高开发效率. 现对开发接口的格式作统一要求. 大家有更好的建议, 欢迎提出.

数据格式: 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, '验证正确'));
}