接口规范想哪说哪

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

这样在团队交付标准规范化后,个人的交付件就是一个标准集,团队的交付件就是一个整体。我们希望每个人都不是散兵游勇,而是集团化作战。此种小细节日后想到别的再来聊聊。

最后编辑于
©著作权归作者所有,转载或内容合作请联系作者
  • 序言:七十年代末,一起剥皮案震惊了整个滨河市,随后出现的几起案子,更是在滨河造成了极大的恐慌,老刑警刘岩,带你破解...
    沈念sama阅读 201,552评论 5 474
  • 序言:滨河连续发生了三起死亡事件,死亡现场离奇诡异,居然都是意外死亡,警方通过查阅死者的电脑和手机,发现死者居然都...
    沈念sama阅读 84,666评论 2 377
  • 文/潘晓璐 我一进店门,熙熙楼的掌柜王于贵愁眉苦脸地迎上来,“玉大人,你说我怎么就摊上这事。” “怎么了?”我有些...
    开封第一讲书人阅读 148,519评论 0 334
  • 文/不坏的土叔 我叫张陵,是天一观的道长。 经常有香客问我,道长,这世上最难降的妖魔是什么? 我笑而不...
    开封第一讲书人阅读 54,180评论 1 272
  • 正文 为了忘掉前任,我火速办了婚礼,结果婚礼上,老公的妹妹穿的比我还像新娘。我一直安慰自己,他们只是感情好,可当我...
    茶点故事阅读 63,205评论 5 363
  • 文/花漫 我一把揭开白布。 她就那样静静地躺着,像睡着了一般。 火红的嫁衣衬着肌肤如雪。 梳的纹丝不乱的头发上,一...
    开封第一讲书人阅读 48,344评论 1 281
  • 那天,我揣着相机与录音,去河边找鬼。 笑死,一个胖子当着我的面吹牛,可吹牛的内容都是我干的。 我是一名探鬼主播,决...
    沈念sama阅读 37,781评论 3 393
  • 文/苍兰香墨 我猛地睁开眼,长吁一口气:“原来是场噩梦啊……” “哼!你这毒妇竟也来了?” 一声冷哼从身侧响起,我...
    开封第一讲书人阅读 36,449评论 0 256
  • 序言:老挝万荣一对情侣失踪,失踪者是张志新(化名)和其女友刘颖,没想到半个月后,有当地人在树林里发现了一具尸体,经...
    沈念sama阅读 40,635评论 1 295
  • 正文 独居荒郊野岭守林人离奇死亡,尸身上长有42处带血的脓包…… 初始之章·张勋 以下内容为张勋视角 年9月15日...
    茶点故事阅读 35,467评论 2 317
  • 正文 我和宋清朗相恋三年,在试婚纱的时候发现自己被绿了。 大学时的朋友给我发了我未婚夫和他白月光在一起吃饭的照片。...
    茶点故事阅读 37,515评论 1 329
  • 序言:一个原本活蹦乱跳的男人离奇死亡,死状恐怖,灵堂内的尸体忽然破棺而出,到底是诈尸还是另有隐情,我是刑警宁泽,带...
    沈念sama阅读 33,217评论 3 318
  • 正文 年R本政府宣布,位于F岛的核电站,受9级特大地震影响,放射性物质发生泄漏。R本人自食恶果不足惜,却给世界环境...
    茶点故事阅读 38,775评论 3 303
  • 文/蒙蒙 一、第九天 我趴在偏房一处隐蔽的房顶上张望。 院中可真热闹,春花似锦、人声如沸。这庄子的主人今日做“春日...
    开封第一讲书人阅读 29,851评论 0 19
  • 文/苍兰香墨 我抬头看了看天上的太阳。三九已至,却和暖如春,着一层夹袄步出监牢的瞬间,已是汗流浃背。 一阵脚步声响...
    开封第一讲书人阅读 31,084评论 1 258
  • 我被黑心中介骗来泰国打工, 没想到刚下飞机就差点儿被人妖公主榨干…… 1. 我叫王不留,地道东北人。 一个月前我还...
    沈念sama阅读 42,637评论 2 348
  • 正文 我出身青楼,却偏偏与公主长得像,于是被迫代替她去往敌国和亲。 传闻我的和亲对象是个残疾皇子,可洞房花烛夜当晚...
    茶点故事阅读 42,204评论 2 341

推荐阅读更多精彩内容

  • Spring Cloud为开发人员提供了快速构建分布式系统中一些常见模式的工具(例如配置管理,服务发现,断路器,智...
    卡卡罗2017阅读 134,569评论 18 139
  • Android 自定义View的各种姿势1 Activity的显示之ViewRootImpl详解 Activity...
    passiontim阅读 171,321评论 25 707
  • Spring Boot 参考指南 介绍 转载自:https://www.gitbook.com/book/qbgb...
    毛宇鹏阅读 46,714评论 6 342
  • 1.告别 —— 柳生意子 姐姐,你在天上吗?你听得到鹭鸶大人的声音吗? 鹭鸶大人,现在叫千枫斋大人,总是出现在滨松...
    松平千枫斋阅读 524评论 0 0
  • 两情相悦,朝朝暮暮
    眼神心灵阅读 163评论 0 0