XX公司APP接口设计规范v1

APP接口设计规范v1

张遂程 2018年02月06日16:15:03

前言

没有最优的方案,只有最适合的方案,本文指出对APP接口设计的一些规范与大家分享和共勉,涉及到APP接口设计规范v1.0,设计案例的分享,和一些PHP编码的要求,目的在于开发出性能优异,结构清晰,维护便捷,安全,和高拓展性的接口。如果有说得不正确的地方,也请大家指出。

经验学习

在项目中,要做到融会贯通,首先就应该做到多学习,学习大厂的经验和总结,如果能避免到别家遇到的坑,那么就最好了,如果避免不到,那么也能做到心中运筹帷幄。程序开发中有句很流行话就是,”不要重复造轮子”,要”时刻明确自己是搬砖民工,不是烧砖的窑”。

新浪微博 open api

获取用户详情接口设计 http://open.weibo.com/wiki/2/friendships/friends
{
    "users": [
        {
            "id": 1404376560,
            "screen_name": "zaku",
            "name": "zaku",
            "province": "11",
            "city": "5",
            "location": "北京 朝阳区",
            "description": "人生五十年,乃如梦如幻;有生斯有死,壮士复何憾。",
            "url": "http://blog.sina.com.cn/zaku",
            "profile_image_url": "http://tp1.sinaimg.cn/1404376560/50/0/1",
            "domain": "zaku",
            "gender": "m",
            "followers_count": 1204,
            "friends_count": 447,
            "statuses_count": 2908,
            "favourites_count": 0,
            "created_at": "Fri Aug 28 00:00:00 +0800 2009",
            "following": false,
            "allow_all_act_msg": false,
            "remark": "",
            "geo_enabled": true,
            "verified": false,
            "status": {
                "created_at": "Tue May 24 18:04:53 +0800 2011",
                "id": 11142488790,
                "text": "我的相机到了。",
                "source": "<a href="http://weibo.com" rel="nofollow">新浪微博</a>",
                "favorited": false,
                "truncated": false,
                "in_reply_to_status_id": "",
                "in_reply_to_user_id": "",
                "in_reply_to_screen_name": "",
                "geo": null,
                "mid": "5610221544300749636",
                "annotations": [],
                "reposts_count": 5,
                "comments_count": 8
            },
            "allow_all_comment": true,
            "avatar_large": "http://tp1.sinaimg.cn/1404376560/180/0/1",
            "verified_reason": "",
            "follow_me": false,
            "online_status": 0,
            "bi_followers_count": 215
        },
        ...
    ],
    "next_cursor": 5,
    "previous_cursor": 0,
    "total_number": 668
}
  • 面向对象设计:用户是一个完整的对象,其中每个用户包含一个最新微博的对象,微博对象也是一个相对完整的对象,按照新浪微博的APP接口设计,获取每一个用户列表,都能获取到列表用户的最新微博信息。
  • 错误信息的返回:主接口中没有直接对错误信息的定义,但凡是能够获取到信息,都认为是正确,而错误信息的定义则是用另一种数据格式来表示。
{
    "request" : "/statuses/home_timeline.json",
    "error_code" : "20502",
    "error" : "Need you follow uid."
}
  • 错误信息的说明:’request’表示当前请求的接口;’error_code’表示错误编号;’error’表示错误的提示文字

淘宝开放平台

查询买家信息 http://open.taobao.com/docs/api.htm?spm=a219a.7629065.0.0.5Zpljz&apiId=21348
  • 正常响应
{
    "user_buyer_get_response":{
        "user":{
            "nick":"hz0799",
            "sex":"m",
            "avatar":"http://assets.taobaocdn.com/app/sns/img/default/avatar-120.png",
            "open_uid":"324324324"
        }
    }
}
  • 异常响应
{
    "error_response":{
        "sub_msg":"非法参数",
        "code":50,
        "sub_code":"isv.invalid-parameter",
        "msg":"Remote service error"
    }
}
  • 错误响应也是通过错误code来识别的,每个code对应一个错误内容

其他开放API

除了上文说的响应方式外,还有一种API响应方式也是比较流行,代表者是百度,高德,支付宝等。
- 百度举例

{  
    address: "CN|北京|北京|None|CHINANET|1|None",    #详细地址信息  
    content:    #结构信息  
    {  
        address: "北京市",    #简要地址信息  
        address_detail:    #结构化地址信息  
        {  
            city: "北京市",    #城市  
            city_code: 131,    #百度城市代码  
            district: "",    #区县  
            province: "北京市",    #省份  
            street: "",    #街道  
            street_number: ""    #门牌号  
        },  
        point:    #当前城市中心点  
        {  
            x: "116.39564504",    #当前城市中心点经度
            y: "39.92998578"    #当前城市中心点纬度
        }  
    },  
    status: 0    #结果状态返回码  
}
  • 支付宝举例
{
    "alipay_trade_precreate_response": {
        "code": "10000",
        "msg": "Success",
        "out_trade_no": "6823789339978248",
        "qr_code": "https://qr.alipay.com/bavh4wjlxf12tper3a"
    },
    "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"
}
  • 这类API相对新兴设计,在API响应上,不区分正确响应和错误响应的结构,采用统一返回方式,其中返回的code 来区分正确还是错误,其中的message来分别给出正确和错误的响应消息。

我们自己的API响应规则

选型我们自己使用的API相应规则如下

正常响应示例

{
    "status": 1,//状态值是1
    "error_code": 0,//同时错误代码是0表示无错误
    "message": "获取成功",//提示操作成功信息
    "data": []//主体返回内容
}

错误响应示例


{
    "status": 0,
    "error": 20102,//2:业务级错误(1代码系统级错误)固定一个字符;01:指的是01这个业务比如保洁 固定两个字符;02具体错误信息固定两个字符,会整理成一个对照表格,前端需要翻译成友好的提示
    "message": "用户id不能为空",//给前端程序员的不友好提示,指明错误的原因
    "data": {}//data字段固定
}

小结

  • API设计中,要根据自己的业务类型和面向群体来综合考虑
  • 都对错误级别进行了划分,并用不同的错误code来表示
  • API面向对象设计并不是面向页面设计,这样的API就具有了多端不同展示的能力
  • 响应主体设计中,个人比较倾向统一的返回,也就是现在我们正在使用的三段式返回,不同的客户端不用去写过多的兼容代码和错误处理,错误处理全部由服务端来完成。
  • 错误处理,目前我们的错误处理机制都还比较简单,就APP而言,只有 ‘0’ ‘1’ ‘1001’,三种识别码和对应的中文提示内容。如果我们后续要支持多种语言的提示,就必须使用error_code,然后由客户端自行提示。

接口设计规范

与前端交互部分

这里概念的定义为与APP部分相互的部分,我们将从安全,版本兼容,命名规范,迭代,面向对象等多个方面说起

接口安全部分

在app的后端设计中,一个很重要的因素是考虑通讯的安全性。

避免信息的泄露,最简单的方案是所有涉及到安全性的api请求,都必须要使用https协议。

因此,我们需要考虑的要点有:

  1. 在app和后台,都不能保存任何用户密码的明文
  2. 在app和后台通讯的过程中,怎么保证用户信息的安全性
  3. 在app中,根据安全考虑,用户的操作分为两类:
      1. 用户登录
      1. 注册操作
        用户的其他操作
  4. 在第一点,用户登录注册操作中,是会出现用户密码,所以在这个过程中,必须要使用https通讯,保证通讯的安全。
  5. 在第二点,用户的其他操作,怎么保证这部分通讯的安全呢?
    在我们的设计中,是采用了公钥加私钥保证安全。用户的id是公钥,通过一定的算法对用户的id进行加密得到一个加密字符串是私钥。当用户登录或注册后,通过https把公钥加私钥返回给app客户端。
  6. 但这个方法有个缺点,当别人截获了这个url时可以重复使用,所以有个改进方法是在传递的参数中增加时间戳,当发现这个时间戳离现在的时间已经很久了,就判断这个url已经失效了。但用时间戳怎么保证app的时间和服务器的时间同步?
    可以在app每次启动和注册登录时和服务器同步时间,然后在app内建一个时钟,时间戳在这个app的内部时钟获取,防止用户修改了手机的时间。
  7. 当然,这些操作做完了,也不能保证100%的安全,只能为攻击增加成本。

效率

APP对服务器端要求是比较严格的,在移动端有限的带宽条件下或者弱网络下,要求接口响应速度要快,,抛开后端的开发框架效率来说,对数据要求也比较严格,如果能做到app需要什么数据就传什么数据,不可多传,过多的数据量影响处理速度,最重要的是影响传输效率那么自然效率是最高的,但是这之间也要有个取舍,效率和接口设计思想之间,后面我们会提到面向对象的设计思想。

面向对象的设计思想

Restful风格:RESTfu设计原则,它被RoyFelding提出(在他的”基于网络的软件架构”论文中第五章)。而REST的核心原则是将你的API拆分为逻辑上的资源。这些资源通过http被操作(GET,POST,PUT,DELETE)。但现在看,一般的操作只有两种:GET ,POST。

  • 这个设计原则最简单的应用就是面向对象设计而不是页面来设计api。最开始的时候,app的一个页面需要什么数据,api就返回什么数据。结果随着app的UI不断改版,需要的数据不断变化,不停地修改api,最后当api的改动会影响以前的版本的时候,只能写一个新的api版本,最后弄得api中有很多version/2,version/3这样的标志,恶梦!
    但根据object来设计,又有一个问题,一个大object可能包含很多小object,是一个api返回全部小object,还是分为多个api返回?根据业务和技术,带宽等仔细考虑吧。
  • 目前我们的接口设计是根据业务来定制接口和返回,假设页面上只显示五个字段,那么后端就需要针对这个页面进行设计。
  • 当然这这样的好处是显而易见的,在和客户端交互的过程中,传输的数据全是有用的数据,极大地节约了网络资源,而且只需请求一个接口,接口就返回了所有界面显示的数据,在弱网状态下,加快响应速度。
  • 新浪微博的做法:打开个人中心,会分多次进行请求,’users/counts’批量获取用户的粉丝数、关注数、微博数,’users/domain_show’个性域名相关,’users/show’获取主要信息,这是比较极端的做法,仅供参考。
  • 下面是一个简单的例子
    image
    返回的数据结构如下
{
    "brand_name": "奥迪",
    "car_model": "SUV",
    "emission_standard": "国五",
    "car_owner": {
        "name ": "张三 ",
        "driving_years": "5年",
        "id": "666"
    }
}

其中车主是一个对象,车子是一个对象,两者是既有关系又相对独立。
总结建议是,新设计的接口,需要考虑到多端不同展示,尽可能的偏向于面向对象,少量特殊处理可以面向页面。当然,后端代码上,都是以对象的形式存在,逻辑必须清楚。

API命名规则

其中一个原则,一看api名字就知道这个api是干啥。但是有个问题就是当你要负责几十甚至上百个api,你就知道不能”望名知api”是个什么样的痛苦。

就拿一个接口来举例吧

'/User/userRedDot/version/1'

这是我们在使用的一个接口,从接口名字来看,不难看出User这个是用户相关的一个功能,然后userRedDot小驼峰命名指的是用户小红点,然后接口的版本号是第一版。以上4部分构成了一个完整的接口命名。

传参规则

接口文档中是会注明不同的接口该使用不同的传参方式

header参数部分:请求头部一般放入鉴权的相关参数,比如用户的token和签名,设备id,APP的标识,userAgent自定义等。

除去鉴权的参数,其他就是接口的入参传递(文档会注明传递方式):
1. 一维参数 按照POST/GET按照普通的form-data和urlencode方式即可
2. 多维参数 按照POST方式,并把body放入json的形式传递。
3. 新增数据 POST
4. 获取数据和修改数据用GET

接口使用规则

系统级接口需要独立于业务之外使用,对于系统级接口,需遵循接口使用规则,对于非系统级接口,可由具体业务实现。但是安卓和ios需要统一。

打个比方,获取用户权限的接口,接口的使用规则由产品给出的,切换tab和从后台返回。

再比如,获取编辑用户爱好,婚姻情况,个性签名等筛选数据,按照接口使用规则,应该在进入用户中心点设置的时候请求,现在是在打开APP地方的进行请求,不符合接口使用规则。原因也在于以前没有给出接口使用规则。

特殊处理的接口需要在接口文档上注明使用规则,比如接口的先后顺序,接口的使用环境和频率。

对于接口返回,也需要安卓和ios进行同步处理,操作成功和 操作失败的信息提示,成功是都不处理还是都处理,失败的提示信息怎么处理,操作失败的时候提示信息需要明确。两个客户端不应该存在不同的处理方案。

兼容性原则

接口不可能永远不变,它会随着需求的变化而做出相应的变动,这种变动也可以理解为兼容或者不兼容。大部分情况下直接在这个接口上叠加版本号,并兼容旧版本。App的新版本开发传参时则将传入新版本的version。

接口的变化一般会有几种:
1. 数据的变化,比如增加了旧版本不支持的数据类型(兼容:新增版本号,接口增量更新)
2. 参数的变化,比如新增了参数(兼容:新增版本号,接口增量更新)
3. 接口的废弃,不再使用该接口了(不兼容:原接口指定版本废弃,后端逻辑处理;原接口所有版本废弃,如果是业务流程修改,则停用原接口,并新开接口)
4. 如果整个接口系统的根基都发生变动的话,比如微博API,从OAuth1.0升级到OAuth2.0,整个API都进行了升级,就无法兼容,只能进行版本强制升级了。
有时候,一个接口的变动还会影响到其他接口,但做的时候不一定能发现。

服务端异常处理

服务端的程序在运行的时候,可能因为一个数据的转化或空指针异常什么的,都不能让程序奔溃,需要捕获异常并对异常进行处理,并返回明确的数据状态信息,不管是成功的,还是失败的,都必须要有数据返回给APP客户端,否则,接口的协议失去了所有的意义

  1. app客户端的语言 java和object-c都是强类型语言,所以怎么处理空值显得特别重要,不合理的设计很容易造成app的闪退。

  2. 从后台的角度来说,api中返回的数据中,正确值和空值的类型必须一样,举例,用户名的字段是“realname”: “xxx”,如果用户名为空,则应该返回“realname”:”“。如果返回值是一个array,空数据则返回一个空array,如果返回值是一个对象,空数据则返回一个空对象,绝对禁止null值。

  3. 对于客户端,必须用个全局的函数来处理所有api的返回数据,需要有一个机制:对于某个客户端需要数据,如果api中缺失,客户端自动补上并给予默认值。

  4. 同时,在数据库设计的时候,一个合理的设计必须是所有字段都有默认值,不应该允许null值。null在大量的语言和数据库中,会带来无穷的问题。

  5. 如果服务端是php,还有一个问题,php中数组和字典都是array,但是可以用(object)[]返回对象,但在java和object-c中是不一样,这个问题一定要注意。

数据格式

补充说明下json的六种数据类型数据类型和约定

  1. Number:整数或浮点数
  2. String:字符串
  3. Boolean:true 或 false
  4. Array:数组包含在方括号[]中
  5. Object:对象包含在大括号{}中
  6. Null:空类型

前后端需要对数据类型进行约定:
- 时间日期型数据:直接返回格式化后的时间字符串或者直接返回时间戳
- 数字类型和文本类型:统一使用字符串格式
- 布尔值类型:统一使用字符串’0’和’1’来表示假和真
- 不返回Null类型数据

APP后端代码部分

  • 面向对象设计,必须具有高拓展性来应对各种需求的变更
  • 抽象的颗粒度的把握,颗粒度必须很细,但是又不能太细了,但是实体对象必须是独立的。
  • 代码层次结构必须清晰,明确每一层干什么事情,做到适当的解耦,不依赖用不到的方法和函数
  • 面向接口设计,多人分工合作中,提供的代码的最小单位是接口,使用者无需关注接口的内部实现,提供接口的人后期维护该接口。
  • 代码重合部分,不难发现,目前系统中有很多功能类似的代码,但是又发现这些代码都有用处,维护这些代码就非常痛苦,当要改一个基础的数据的时候,就会去改很多
  • SQL部分,优化SQL查询,提升查询效率,杜绝使用join和写复杂sql等不便于维护的代码,不用jion和复杂sql之后能对系统的扩展和二次开发有帮助,提高系统和数据库的并发[目前能知道的是新浪微博已经全面禁止使用join查询了]。

待商榷问题

  • Herder管理:对herder的规划和规范,包括设计和命名上,还有技术层面上的难题,尤其注意原生里面的内嵌H5页面
  • push到达率:目前的push能否满足现状的需求,如果不满足,那么需要怎么样才满足。是否需要引进新的第三方push
  • 客户端更新和热更新:能否后续的功能用react来编写,集成热更新的能力,原生更新的逻辑梳理,和是否合理,不合理该如何调整。
  • 权限和用户权限:梳理现在的APP权限和用户权限设计模式和交互模式,看是否合理,不合理的话,怎么调整。
  • 接口依赖关系:接口之间原则上的依赖关系不能超过两个,意思是一个接口需求的数据,最多只能从一个接口处获取,如果情况特殊另说。

关于六大设计模式的补充

详情见博客:http://blog.csdn.net/zhengzhb/article/details/7296944

以上内容部分引用他出博客

发布了1 篇原创文章 · 获赞 0 · 访问量 692
展开阅读全文

没有更多推荐了,返回首页

©️2019 CSDN 皮肤主题: 大白 设计师: CSDN官方博客

分享到微信朋友圈

×

扫一扫,手机浏览