[转载]app后端API开发总结
app后端API开发总结
25 Jun 2015
一.API 设计规范
1.1 按需Restful设计原则
按业务选择Restful API还是 josn风格的，关于restful api可参考：
1.2 合理的api命名
- 正确精炼的名称，能够体现这个接口是干什么的
- 配合时态(现在，过去，将来)和动态(如setName)
- 不要用生僻单词，也不要用汉语拼音
- 注意缩写规范，不要自己发明缩写
- 保持接口名称的对称性， 如
/api/msg/open和/api/msg/close等
1.3 api的安全性
- 在登录注册等用户操作能使用
https尽量使用它 - API 接口操作时，采用公钥加私钥保证安全，公钥如(user_id), 私钥(user_id经过某种对称加密算法生成)如
sid.将公钥和私钥作为参数传递。生成的私钥字符串每次都不同，且设置过期时间(存储在redis中)，每次启动或注册登录时候生成并更新私钥。当过期后就提示重新登录，每次请求的时候服务器端校验sid是否解密成对应的user_id,sid在redis中用户关系映射是否正确。如果用户N天后未使用APP，则到了过期点就重新登录；否则就一直重新计算过期时间。(有待优化) - json web token (jwt) JWT方案，给客户端的是公钥，然后用公钥把数据加密发送给服务端，服务端在根据来源的信息，使用对应的私钥来解析数据。这样就能保证数据的安全性。
推荐阅读：
1.4 api返回数据
- 要定义一致的返回数据，如 成功：
{"data": "xxx", "code":0}，异常{"data":"", "code": 500, "msg": "程序异常"} - 注意
null的使用， 如果为空或无，最好用空字符串替代 - 数据库设计中所有字段都有默认值，且为空值或数字而非
null - 异常提示信息的设计，分为用户友好类msg, 和面向程序员的异常提示类msg.
二.API开发注意事项
2.1 emoji 表情的处理
emoji 表情是 4 个字节，而 MySQL 的 utf8 编码最多支持 3 个字节，所以插入会出错。为了解决这个问题，MySQL 开始支持 utf8mb4. 具体参考让 MySQL 支持 emoji 存储
推荐一个python第三方模块emoji: emoji terminal output for Python
其他资源：
2.2 图片处理
app后台图片处理的一个基本原则，数据库中只保存原图的路径。对于同一张图片来说，针对不同机型，不同app版本所需要的不同尺寸，使用动态生成的策略，大体思路如下：
- 在图片的url末尾加上参数，声明需要生成的图片的新的尺寸，例如：户端需要图片（http://www.baidu.com/img/bdlogo.gif）的80*80的尺寸，则在图片的路径加上宽和高的参数（类似于CDN的机制） http://www.baidu.com/img/bdlogo.gif？w=80&h=80
- 服务器接收到图片的请求，先在缓存中查找这个尺寸的图片是否已经生成，如果已经在缓存中有记录，则不用重新生成。
- 如果该尺寸的图片还没生成，则生成新的图片尺寸，并把新生成的图片路径放在缓存中.
在app整个系统架构中，图片应该有两层缓存：
（1）app本地的图片缓存，当app中没有该图片时，才去服务取
（2）服务器的图片缓存，记录图片不同尺寸的保存路径
图片操作是非常消耗CPU，内存，和大量的磁盘IO，这里推荐GraphicsMagick,在GraphicsMagick Programming Interfaces 查看支持编程语言的接口，对于python的支持在这里
2.3 考虑移动端的网络情况和耗电量
APP后端开发不同web后端开发的地方有很多，虽然并没有细分。比如网络流量，这里汇总注意事项。
- 图片缩略图压缩
- 精简请求参数和返回数据，只返回需要的数据，对于大量数据要采用压缩上传或响应给app
- 根据用户的网络情况来设定不同的请求情况，如只有在wifi的情况下才给用户传输封面图、缩略图之类等
2.4 跨平台性
所谓跨平台是指我们的接口要能够支持不同的终端，比如android、ios、windowsphone以及桌面软件、网站等， 采用通用的解决方案，比如通信协议就采用最常用的HTTP协议，如果是即时通信，可以采用开放的XMPP协议，做游戏的可以采用可靠的TCP协议，除非TCP不够用了，再采用定制的UDP协议。 数据交换采用xml或者json格式等等。 总之，要达到的目标就是让不同的端能够很方便的使用你的接口。
2.5 通用的数据交换格式
目前，对于接口和客户端的数据交换格式，基本上就是两种，xml和json，而现在使用json的应该占大多数。交换的数据包括两种，一种是客户端请求服务器端接口时传递的一些参数，一种是服务器端返回给客户端的数据。
2.5.1 request
对于客户端的请求参数，现在也越来越多的接口要求采用json的格式，而不是以往最常见的key_value对了。
比如，接口需要username和password两个参数 key_value pair的方式是：
username=xxxx&password=*****
然后通过GET或者POST方式传送。
而通过json方式交换数据的话，格式如下，直接POST到服务器端。
{
'username':'xxxx',
'password':'*****'
}
2.5.2 response
对于服务器端返回的json数据格式，需要注意两个问题： 一是汉字编码问题，因为json（javascript）内部支持Unicode编码，会将汉字等转换成unicode编码保存， 所以在返回结果中，对于中文，可以直接输出中文，也可以输出中文的unicode编码，json解析器都会很好的解析。 比如下面两种方式都是可以的。
{"code":"208","data":"\u53c2\u6570\u4e0d\u5b8c\u6574"}
{
"code": "208",
"data": "参数不完整"
}
二是字段的数据类型，特别是数字类型的，json中尽量转成数字格式， 比如{'userid':128}不要写成{'userid':'128'}
2.2 取舍之道
- 对于创业型公司能用第三方服务就使用第三方的服务。
- 能在服务器端实现的功能就不要放在客户端
- 服务器端接口也要做好相应的版本维护
- 在app启动时，调用一个初始化api获取必要的信息.例如，最新的app版本。当发现本地app的版本已经低于最新的app版本，可提示用户更新。当然了，这个提示版本更新的功能很多第三方sdk都提供。
