首页 诗词 字典 板报 句子 名言 友答 励志 学校 网站地图
当前位置: 首页 > 教程频道 > 软件管理 > 软件架构设计 >

api设计的那些事情

2013-11-02 
api设计的那些事儿做了一年多的系统架构,后台研发,api设计,从原来的电子商务网站有幸进入了现在的公司,从

api设计的那些事儿

    做了一年多的系统架构,后台研发,api设计,从原来的电子商务网站有幸进入了现在的公司,从事app的后台开发,很感谢公司和同事给予本人的信任和帮助,现在公司已经形成了手机网页端,android客户端,iphone客户端,其中的乐与苦,得与失,仰首问天有谁知?我觉得是时候来个总结,以美学和技术的角度记录下来。

    

api设计的体会

 

 (1)Restful设计原则

 

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

       但现在看,一般的操作只有两种:GET ,POST。

    这个设计原则最简单的应用就是根据object而不是页面来设计api。最开始的时候,app的一个页面需要什么数据,api就返回什么数据。结果随着app的UI不断改版,需要的数据不断变化,不停地修改api,最后当api的改动会影响以前的版本的时候,只能写一个新的api版本,最后弄得api中有很多_V2,V3这样的标志,恶梦!

    后来在网站的重构过程中,就根据object来设计api,但根据object来设计,又有一个问题,一个大object可能包含很多小object,是一个api返回全部小object,还是分为多个api返回?根据业务和技术,带宽等仔细考虑吧。

 

(2) api的命名

    其中一个原则,一看api名字就知道这个api是干啥。在创业团队中,一般就只有一两个人负责后台,当你要负责几十甚至上百个api,你就知道不能“望名知api”是个什么样的痛苦。

 

(3)授权机制

    曾经的设想:类似于微博的auth 2.0,但觉得太麻烦,没必要做得这么繁琐,就放弃了。

    后来参考了网站上的session,cookie机制,设计了一个简单可靠的机制:登录时使用用户名和密码获取一个token返回给客户端,以后每次调用api都传递这个token标识用户的身份。

    在传送用户名和密码的过程,必须要采用https加密保证数据的安全。

   

 

(4) api返回数据

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

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

    对于客户端,必须用个全局的函数来处理所有api的返回数据,需要有一个机制:对于某个客户端需要数据,如果api中缺失,客户端自动补上并给予默认值。这个机制在我们的实践中大大减少了app的闪退。

    同时,在数据库设计的时候,一个合理的设计必须是所有字段都有默认值,不应该允许null值。null在大量的语言和数据库中,会带来无穷的问题。对于这个数据库设计原则,我以前不太明白,现在经历了一年的api设计后,终于懂得。

    如果客户端是php,还有一个问题,php中数组和字典都是array,但在java 和object-c中是不一样,这个问题一定要注意。

 

(5)图片的处理

 

    在不同版本的app中,各种不同尺寸的手机中,同一张图片显示的尺寸可能是不一样,如果每次都需要用返回原图,然后在客户端处理,则极大浪费网络资源。而如果是后台处理好图片才返回,则又是一个挑战,怎么有效保存和裁剪多种图片尺寸呢

    例如,一开始头像只需要返回60*60的尺寸,后来在新的版本需要返回70*70, 又出了一个新版本,需要返回80*80, 每次增加一个新的尺寸,怎么在数据库上记录下来。这个问题在一开始做api的时候没考虑,后来不得不用了一个极端的方法,没增加新的图片尺寸,就在数据库中增加一个新的字段,保存并生成新的图片尺寸,结果最后数据库的头像字段有"avatar","avatar_60_60","avatar_70_70","avatar_80_80",这种极度恶虐的设计。

    最后,针对图片,我们才用了这样的策略:

(1)客户端本地缓存图片,只有没有合适的图片,才去服务器取。

(2)当客户端需要某种尺寸的图片,由客户端告诉服务端图片的尺寸,服务端动态生成并缓存起来。

 

     例如,客户端需要图片(http://www.baidu.com/img/bdlogo.gif)的80*80的尺寸,则在图片的路径加上宽和高的参数(类似于CDN的机制) http://www.baidu.com/img/bdlogo.gif?w=80&h=80, 则服务器就生成80*80的尺寸并返回。

 

    采用了这样的图片处理机制,数据库中只要有一个字段保存原图就行了,其它尺寸就由客户端告诉服务端动态生成。以后无论什么尺寸的图片,数据库中都不需要记录,数据库只有原图就行了。

 

(6)返回的提示信息

   最科学的情况,服务端只返回信息代码,具体的文字提示由客户端决定。

    如果文字信息是由服务端返回,则最起码要区分2种信息:提示用户的信息,提示客户端程序员的信息。这两者的区别:

1.提示用户的信息是要在让客户知道的,提示客户端程序员的信息不需要让客户知道的。

2. 提示用户的信息文字很友好,客户不需要专业基础一看就知道是什么,提示客户端程序员的信息则很专业,例如告诉客户端少传了哪个参数?哪个参数有问题等等。

 

(7)在线api文档和测试

 

    我们网站的api在线测试文档,既是一份在线api文档,也是一个在线测试工具,极大方便沟通和测试。每次客户端程序员觉得某个api有什么问题,我们就是这个在线工具上讨论沟通的。客户端程序员最喜欢这个玩意了^-^。

    上个图解一下馋(这个图是旧版的api,已经弃用了):

api设计的那些事情


负责做这个功能的同事专门写了篇博客详细介绍了这个在线api测试文档,还带有demo:

 

 http://amuropikin.iteye.com/blog/1701537

 

 

[文章作者]曾健生

[作者邮箱]h6k65@126.com

[作者QQ]190678908

[新浪微博] @newjueqi

[博客] http://blog.csdn.net/newjueqi

http://blog.sina.com.cn/h6k65

 

热点排行