专栏首页DDDAPI如何设计

API如何设计

在之前《应对变化》[1]中提到模块之间合的策略:缩小依赖范围,API是两个模块间唯一的联结点

怎么才是一个好的API设计呢?最近项目中正好碰到一件关于一个API引起的相爱相恨的事件

数据来源于外部系统,外部系统通过回调把数据传输过来,内部系统通过系统A进行接受,接受完之后,转发给系统B

接受回调api大概是:

systemA.callback(long userId,Object data);

整体两个参数,一个userId表示这个数据是谁的、一个data表示数据本身

对于系统B来讲,他的业务要求,这数据必须要知道用户名字,必须在数据上打标签,所以跟系统A商量,要不你把username也随便转给我吧

系统A一想,那也是两秒的事,因为本身在接受数据时也得对userId校验,取个username也不麻烦,不废话了,你要就给你

因此系统B接受数据api设计成:

systemB.receive(long userId,String username,Object data);

一切都是行云流水,大家都很happy,如期发布上线

爱情总是在转角处遇到,上线完,QA同学一顿操作,却发现系统B没有如期显示出数据,系统B觉得是系统A没传来数据;咋办呢?心虚的系统A只能查查日志

log:systemB return error,username is empty

原来原来是因为这个用户的username是空,系统B拒绝接受了,怎么username会为空呢?username怎么能为空呢?

找到用户系统,用户系统解释了,一个用户在注册时并不一定有username,有username,email,usercode三个值中的任何一个值就可以了

这时该怎么办呢?相爱相杀时刻到了

系统B:要不你把这三个值都传给我?

系统A:我还得再改下代码,测试后发版本,要不你自己从用户系统取吧

系统B:传一个可以,怎么三个就不可以了,不都一样吗?

系统A:太麻烦了,你自己取了,想怎么控制就怎么控制

系统B:你是不爱我了

系统A:你怎么就不理解我呢


温习一下一个好的API设计要求:

缩小依赖范围,就是要精简API;API要稳定得站在需求角度,而不是how角度

1.API包含尽可能小的知识。因为任何一项知识的变化都会导致双方变化2.API也要高内聚,不应强迫API的客户依赖不需要的东西3.站在what角度;而不是how,怎么技术实现的角度

上面示例的问题就在系统B接受数据api:

systemB.receive(long userId,String username,Object data);

关照上面的要求:

问题一:API中包含的知识有重复:userid,username

问题二:客户端也就是systemA并不需要username,但被强迫要知晓并要按规则赋值

问题三:站在设术实现角度,api中增加参数username,而不是需求角度

总结

示例虽小,日常工作中常常碰到这类问题,如果这个例子上线成功,每个人都觉得这是一次成功的交付,但回头复盘,发现了很多理论缺乏,惯性思维使然造成的不合理,难维护,难扩展的设计

由此看出,日常的CRUD并不是没有技术含量,而是我们有没有深刻认知

References

[1] 《应对变化》: http://www.zhuxingsheng.com/blog/coping-with-change.html

本文分享自微信公众号 - 码农戏码(coder-game),作者:朱先生

原文出处及转载信息见文内详细说明,如有侵权,请联系 yunjia_community@tencent.com 删除。

原始发表时间:2021-07-19

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

我来说两句

0 条评论
登录 后参与评论

相关文章

  • 第三方API对接如何设计接口认证?

    在与第三方系统做接口对接时,往往需要考虑接口的安全性问题,本文主要分享几个常见的系统之间做接口对接时的认证方案。

    陶陶技术笔记
  • 四连问:API 接口应该如何设计?如何保证安全?如何签名?如何防重?

    说明:在实际的业务中,难免会跟第三方系统进行数据的交互与传递,那么如何保证数据在传输过程中的安全呢(防窃取)?除了https的协议之外,能不能加上通用的一套算法...

    芋道源码
  • 四连问:API 接口应该如何设计?如何保证安全?如何签名?如何防重?

    在实际的业务中,难免会跟第三方系统进行数据的交互与传递,那么如何保证数据在传输过程中的安全呢(防窃取)?除了https的协议之外,能不能加上通用的一套算法以及规...

    Java团长
  • 四连问:API 接口应该如何设计?如何保证安全?如何签名?如何防重?

    在实际的业务中,难免会跟第三方系统进行数据的交互与传递,那么如何保证数据在传输过程中的安全呢(防窃取)?除了https的协议之外,能不能加上通用的一套算法以及规...

    架构师修炼
  • 如何设计好的RESTful API

    现阶段的开发模式多以前后端分离形式存在,前后端开发人员需要通过大量 API 来进行数据交互,如果在交互过程中前后端人员经常遭遇如下问题:

    乱敲代码
  • 如何设计一个API签名

    大部分情况下,我们使用已有的API签名方案(如腾讯云API签名、阿里云APi签名、亚马逊API签名等等)即可,无需从零开始设计一个API签名方案...

    林喜东
  • 如何设计优秀的API(一)

    1. 不要暴露过度(Do not expose more than you want)

    用户5224393
  • 如何设计优秀的API(二)

    现在我们来谈谈Java的设计实践与设计模式,这两者有助于开发者和维护者的工作符合前几个章节所提到的准则,用户体验佳。可以先看看如何设计优秀的API(一)

    用户5224393
  • 如何设计优秀的API(三)

    此文章翻译来自国外的一本叫做《How to design API》的书籍,如果还没有没有看过前两张的朋友可以先看看前两章文章,如何设计优秀的API(一)、如何设...

    用户5224393
  • 如何设计出优秀的Restful API?

    现在微服务真是火的一塌糊涂!大街小巷,逢人必谈微服务,各路大神纷纷忙着把自家的单体服务拆解成多个Web微小服务!而作为微服务之间通信的桥梁,Web API的设计...

    互扯程序
  • 如何设计出优美的Web API?

    WEB API的应用场景非常丰富,例如:将已有系统的功能或数据开放给合作伙伴或生态圈;对外发布可嵌入到其他网页的微件;构建前后端分离的WEB应用;开发跨不同终端...

    IT老兵哥
  • 如何设计开发好一个 HTTP API?

    在过去的几年里,我使用着各式各样的HTTP API。这些API通常不是公开的,只是提供给合作伙伴公司。此外,我也看了很多开发者提供的API,自己也参与了几个AP...

    企鹅号小编
  • 如何设计API返回码(错误码)?

    客户端请求API,通常需要通过返回码来判断API返回的结果是否符合预期,以及该如何处理返回的内容等

    KenTalk
  • OAuth 2和JWT - 如何设计安全的API?

    恒宇少年
  • 如何写出好的 JavaScript —— 浅谈 API 设计

    很多同学觉得写 JavaScript 很简单,只要能写出功能来,效果能实现就好。还有一些培训机构,专门教人写各种“炫酷特效”,以此让许多人觉得这些培训很“牛逼”...

    前朝楚水
  • 如何设计一个牛逼的API接口

    在日常开发中,总会接触到各种接口。前后端数据传输接口,第三方业务平台接口。一个平台的前后端数据传输接口一般都会在内网环境下通信,而且会使用安全框架,所以安全性可...

    Java旅途
  • 我是如何根据豆瓣api来理解Restful API设计的

    1.什么是REST REST全称是Representational State Transfer,表述状态转移的意思。它是在Roy Fielding博士论文首次...

    方志朋
  • 如何掌握高级react设计模式: Context API【译】

    原文链接:How To Master Advanced React Design Patterns: Context API

    IMWeb前端团队
  • Discourse 如何设置 API 的 key

    在用户级别部分,你可以为这个 API Key 设置为全局访问还是只能是针对一个特定的用户使用这个 key。

    HoneyMoose

扫码关注云+社区

领取腾讯云代金券