接口规范想哪说哪

java服务型RPC框架所选用的远程调用方式有两种风格:用jar包和纯REST方式。

jar包方式的好处是用了对方提供的二方包,API都打在里面了,使用时直接能弹出提示;问题也很明显,随着引用的jar包越来越多,排包工作占了一半时间。

REST方式则直接以HTTP协议作为载体传递数据,彻底解耦了与调用方的关系;但这时不能像jar包那样方便的从IDE弹出使用提示了,要先看对方给的文档,但程序员写的文档大家都懂的,最后要费大量口舌联调沟通。这方面微信的开放平台做的文档还是不错的。

技术负责人应尽量考虑使用的开发者的应用细节,尽量减少对开发者的干扰。而为了大型团队沟通效率的提高,又需要制定开发规范来约束开发者的自由发挥空间。

如在定义统一的WEB API返回结果上,最简单直接的就是没有约束,使用各种开源框架的标准回复,由于基础框架就是对基本功能的封装,都是随意开发怎么写。

java servlet上就是HttpResponse。

如果使用一些json序列化形式的返回的话,可能json形式的就是:

{  "weather": normal,  "area" : hangzhou,}

这种返回很简单,但也很随意,大规模工程上希望所有人遵守同样的规范做事,例如这种返回如果出错了该返回什么呢?

  1. 又要开发自己随便定个status: error?

  2. 如果结果是error了,要不要加个返回码给前端呢? 例如 errorcode: 1

  3. 那么这个1代表什么意思呢? 是不是大家可以默认errorcode为0就是正常呢?

  4. 再下一步,如果有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

版权声明

本文来自互联网用户投稿,文章观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如若转载,请注明出处。如若内容有涉嫌抄袭侵权/违法违规/事实不符,请点击 举报 进行投诉反馈!

相关文章

立即
投稿

微信公众账号

微信扫一扫加关注

返回
顶部