接口规范想哪说哪
java服务型RPC框架所选用的远程调用方式有两种风格:用jar包和纯REST方式。
jar包方式的好处是用了对方提供的二方包,API都打在里面了,使用时直接能弹出提示;问题也很明显,随着引用的jar包越来越多,排包工作占了一半时间。
REST方式则直接以HTTP协议作为载体传递数据,彻底解耦了与调用方的关系;但这时不能像jar包那样方便的从IDE弹出使用提示了,要先看对方给的文档,但程序员写的文档大家都懂的,最后要费大量口舌联调沟通。这方面微信的开放平台做的文档还是不错的。
技术负责人应尽量考虑使用的开发者的应用细节,尽量减少对开发者的干扰。而为了大型团队沟通效率的提高,又需要制定开发规范来约束开发者的自由发挥空间。
如在定义统一的WEB API返回结果上,最简单直接的就是没有约束,使用各种开源框架的标准回复,由于基础框架就是对基本功能的封装,都是随意开发怎么写。
java servlet上就是HttpResponse。
如果使用一些json序列化形式的返回的话,可能json形式的就是:
{ "weather": normal, "area" : hangzhou,}
这种返回很简单,但也很随意,大规模工程上希望所有人遵守同样的规范做事,例如这种返回如果出错了该返回什么呢?
又要开发自己随便定个status: error?
如果结果是error了,要不要加个返回码给前端呢? 例如 errorcode: 1
那么这个1代表什么意思呢? 是不是大家可以默认errorcode为0就是正常呢?
再下一步,如果有error了,前端一般都需要一条提示信息,例如XXXX错误,这个详细信息我们是不是又要定一个errormessage呢?
于是一个错误的返回可能就变成了这样:
{ "status": 1 "errorcode": 202 "errormessage" : 服务器繁忙}
既然这样,那么正确的返回就不能太随意了,也要跟着这个来,正常的返回可能就要变成这样了:
{ "status":0, "body":{ "weather": normal, "area" : hangzhou, }}
为了达到这样的效果,设计者就不能让开发简单的用个
String jsonInString = mapper.writeValueAsString(staff);
这种形式来玩了,我们需要通用解决方案。
开放式平台对外的接口设计是很重要的一块,要考虑到简单,扩展性,易读性。这里就先不讲怎样设计API接口了。先讲讲设定规范的思路,首先我们想让普通开发人员无感知,那么就应该在他返回了response后对他的结果做点什么,找切入点,无论返回了什么内容,都封装上一层类似于http header的东西,包括了本次请求的状态信息。
reponse class-> json -> [head]+json
这样在团队交付标准规范化后,个人的交付件就是一个标准集,团队的交付件就是一个整体。我们希望每个人都不是散兵游勇,而是集团化作战。此种小细节日后想到别的再来聊聊。
关键字:api
版权声明
本文来自互联网用户投稿,文章观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如若转载,请注明出处。如若内容有涉嫌抄袭侵权/违法违规/事实不符,请点击 举报 进行投诉反馈!