13 | 接口规范，是协作的合约

范学雷



该思维导图由 AI 生成，仅供参考

一个软件项目，一般需要交付两类文档。一类文档是面向开发者的，另一类文档是面向最终用户的。这两类文档，由于面向用户的不同，无论是内容还是形式，都有巨大的差异。今天我们先来聊聊面向开发者的文档。下一讲中，我们再接着聊面向最终用户的文档。
区分外部接口和内部实现为了便于维护和协作，一个软件通常被划分为几个不同的部分。比如我们通常使用的 MVC 架构，把软件分为模型（Model）、视图（View）和控制器（Controller）三个部分。这样做，可以降低复杂度，让程序结构更加直观。同时，这种架构也很容易对程序进行修改和扩展，并且可以重复利用基础的功能。
不同功能的分离，让程序员之间产生了分工，专业人员可以更聚焦于个人的专长领域。这是一个多赢的局面，也能让软件的质量得到提升。
既然有分工，就要有协作。MVC 架构把软件拆分为三块，是分工；而 MVC 模块之间的调用关系，就是协作。
一个好的软件设计，要区分外部接口和内部实现。外部接口，就是协作的界面，要简单规矩；内部实现，可以是千变万化的复杂小世界。
这种区分无处不在，即使是最普通的 API。比如我们常用的 InputStream，一旦我们获得这个对象实例，就可以调用它的 read() 方法。 我们不用去关心，它的底层实现是一个文件，一段内存，还是一个远程连接。InputStream 的接口定义只有十个方法，短短的 500 多行代码。

公开

同步至部落

取消

完成

0/2000

荧光笔

直线

曲线

笔记

复制

AI

深入了解
翻译
英语
中文简体
中文繁体
法语
德语
日语
韩语
俄语
西班牙语
阿拉伯语
解释
总结

接口规范是软件开发中至关重要的合约文档，需要成文、清晰、稳定、变更谨慎。文章强调了合约的重要性，并介绍了使用Java Doc组织接口规范描述的方式。合约的制定和修改需要充分沟通和协商，参与者要讨论清楚分工协作方式。文章还提到了OpenJDK的接口制定和修订步骤，强调了合约是使用者和实现者之间的合约。最后，文章以一个前端UI组件库的“彩蛋”事件为例，呼吁读者共同讨论如何避免类似事件发生。整体而言，本文深入浅出地阐述了接口规范的重要性，以及如何制定和维护规范，对软件开发人员具有一定的指导意义。

仅可试看部分内容，如需阅读全部内容，请付费购买文章所属专栏
《代码精进之路》，新⼈⾸单¥59

立即购买

登录后留言

全部留言(11)

最新
精选

MOV AX,0
关于更新接口的问题，我所知的做法一般有两种： 1.对于外部部门调用的公开接口，如果有修改，需要提前知会各部门负责人。负责人委派一名同事进行对接，我们协调好接口规范整理出文档。在近期版本，上线这个新接口，但不马上废弃旧接口，只是标注@Deprecated。等待所有部门在后续版本替换完新接口后，检查接口调用情况，确认没有任何调用后进行移除； 2.如果是作为开放平台公开出去的接口，或在更改接口实现逻辑前需要额外流程（比如DB变更、数据源切换等），需要加入类似如下的逻辑： if (isNewProcess()) { return executeByNewProcess(); } return executeByOldProcess(); 目前公司是使用携程的Apollo配置中心实现公共配置，比如近期我们遇到一个查询会员账户总余额&积分统计的DB慢查询问题。我们将查询数据源改为从大数据获取，但是在大数据可能出错或挂掉的情况，就可能导致一系列问题。所以我在apollo配置了三个开关： a.所有数据从大数据获取(boolean) b.从大数据获取统计信息的商户ID(list) c.所有统计数据直接返回0的商户ID(list) 容错性非常重要，如果大数据方面数据不可靠/接口挂掉，切到直查DB后，针对会员数很多的大商户，还需要直接返回0禁止DB的慢查询拖垮库。同理，开放平台的接口，如果修改在线上的应用具有不确定性，一定要有后手，可以换回旧逻辑。测试环境通过，并不代表线上也通过！
作者回复: 非常棒的经验，多谢！
2019-02-01

18
周锐
提供/调用接口甩锅指南： 1、提供接口：a、打印传入参数；b、对参数做验证，不合规就回抛异常；c、返回之前打印返回结果。 2、调用接口：a、调用前打印调用参数；b、调用后打印返回结果。
作者回复: 检查参数还不够吗？
2019-02-01
2
6
小文
唉我做游戏开发的从没有写过这个东东
作者回复: 忧桑，没接触过游戏开发，一点也不懂。游戏不开发公共接口吗？
2019-02-18

3
Sisyphus235
接口规范是好事情，但是如果业务变动非常大且频繁，接口就需要不断修改，这样规范的接口反而带来很大开发消耗，或许接口规范也要根据实际情况灵活调整，必须写清楚的是传参，其他部分根据情况来使用。另外，使用类似于 Protocol Buffer 的工具不仅能让协作者清楚知道接口情况，且能 parse 和 unparse，避免很多接口错误。
作者回复: 频繁变动的接口是个灾难。接口设计一定要舍得花时间。
2019-05-22

1
秦凯
在接口申明中将“积雪”（节日）的样式作为配置参数，并且默认为不应用。只有当开发者主动配置时才会应用节日特效。并且将此特性记录到使用规范文档中供使用者参考，好让使用者可以清晰明了的使用API。
作者回复: 这是一个好办法！ "默认为不应用"是一个常用的解决兼容性问题的办法。
2019-02-14


逆风飞翔
请问一下专栏内容有印象笔记版本吗
作者回复: 我没用过印象笔记，应该没有这个版本。
2019-02-01


ifelse
接口规范是使用者和实现者之间的合约。--记下来
2022-07-19


进化菌
接口，就像是一份契约，定义要实现的确定属性和方法。
2021-11-22


第一装甲集群司令克莱斯特
上游不通知评估就改接口模型，下游调用方崩溃，想🤬。
2021-08-04


慎独明强
对外接口尽量不要改参数明，接口名，遇到其他组直接改接口入参而不是重载一个，导致我们调用他们异常
2020-06-24



收起评论