<button id="dvsem"></button>

        RELATEED CONSULTING
        服务咨询
        选择下列产品马上在线沟通
        服务时间:24小时服务
        你可能遇到了下面的问题
        关闭右侧工具栏

        从客户端的角度设计后端的接口

        1
        前言
           

         

        兵马未动,粮草先行。在一款APP产品的各个版本迭代中,兵马的启动指的是真正开始敲代码的时候,粮草先行则是指前期的需求,交互,UI等评审准备阶段,还有本文要说的接口的设计与评审。

         

        虽然很多时候一个api接口的业务,数据逻辑是后端提供的,但真正使用这个接口的是客户端,一个前端功能的实现流程与逻辑,有时候只有客户端的RD才清楚,从某种意义来说,客户端算是接口的需求方。

         

        所以建议在前期接口设计和评审时,客户端的RD应该更多的思考和参与,什么时机调什么接口?每个接口需要哪些字段?数据含义怎么给?只有这些都考虑清楚,且达成一致并产出接口文档后,当项目真正启动时,根据接口协议进行开发,才能尽量避免各种不确定因素对项目整体进度的影响。

         

        本文介绍了接口设计中常见的规范,以及个人的一些思考与总结,水平有限,权当是抛砖引玉,如果有更好的设计,请在文章下方留言告诉我,谢谢。

         

         

        2

        接口设计规范

           

        一. 接口示例

         

        以下是一个用户信息接口的文档示例,包含接口描述,请求参数,响应参数,json示例等。

         

        接口描述:用户登陆成功后,或进入个人中心时会获取一次用户信息

         

        URI 方法
        /userinfo GET

         

        请求参数

         

        名称 必填 备注
        id 用户id

         

        响应参数

         

        名称 类型 备注
        id String 用户id
        name String 姓名,例:张三
        age String 年龄,例:20

         

        json示例

        {
        "code":200,
        "msg":"成功",
        "time":"1482213602000",
        "data": {
            "id":"1001",
            "name":"张三",
            "age":"20"
        }}
        2
        基本规范
           

        1.通用请求参数

         

        每个请求都要携带的参数,用于描述每个请求的基本信息,后端可以通过这些字段进行接口统计,或APP终端设备的统计,一般放到header或url参数中。

         

        字段名称 说明
        version 客户端版本version,例:1.0.0
        token 登陆成功后,server返回的登陆令牌token
        os 手机系统版本(Build.VERSION.RELEAS)例:4.4,4.5
        from 请求来源,例:android/ios/h5
        screen 手机尺寸,例:1080*1920
        model 机型信息(Build.MODEL),例:Redmi Note 3
        channel 渠道信息,例:com.wandoujia
        net APP当前网络状态,例:wifi,mobile;部分接口可以根据用户当前的网络状态,下发不同数据策略,如:wifi则返回高清图,mobile情况则返回缩略图
        appid APP唯一标识,有的公司一套server服务多款APP时,需要区分开每个APP来源

         

        2.请求Path,http://www.online.com/api/ [path]

         

        原则:在以下命名规范的基础上尽量保持良好的可读性,见名知意。另外这里需要额外提下restful规范,个人理解restful规范是通过path表示当前请求的资源,通过method表示当前请求的操作动作(post=增,delete=删,put=改,get=查),例:GET /userinfo/{id},通过这个path就可以清楚的知道当前请求的意图是根据id获取用户信息,而APP开发中很多时候一个页面是需要同时获取,如,用户,订单,营销各种信息,这时候就很难用一个path来表示当前请求的真正意图,restful规范就很难得到实现,有不同见解的欢迎交流。故本文介绍的接口设计方法,只区分get和post,通过path命名定义请求行为,

         

        操作行为 Method Path
        查找 GET getXxx
        增加 POST addXxx/submitXxx
        修改 POST modifyXxx
        删除 POST delXxx

         

        示例

         

        操作行为 Method Path
        获取用户信息 GET getUserInfo
        增加收货地址 POST addAddress
        修改密码 POST modifyPwd
        删除收货地址 POST delAddress
        登陆 GET login
        发送短信验证码 GET sendSms
        订单支付 POST orderPay

         

        3.响应数据

         

        字段名称 说明
        code 响应状态码,200:成功;非200:失败
        msg 请求失败时的message
        time 服务端时间戳,单位:毫秒。用于同步时间
        data 数据实体

         

        code=200时,msg=登陆成功/修改成功/提交成功;如果需要Toast,可以直接使用msg。


        code!=200时,msg=错误提示信息;比如login接口,"账号或密码错误","账号不存在"类似这些的业务提示文案放在msg字段,客户端直接Toast就可以了。不过需要提醒后端同学,错误提示不能自己觉的什么合适就提示什么,要按需求文档来提供,或和PM确认。

         


        大唐传易福州网站建设推荐阅读:

        管家婆一句赢