接口规范想哪说哪

2016-08-07 22:59:00

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

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