这是一个有点咆哮的帖子。有时会发生；—）我听说读起来更有趣！有些技能人们认为他们有，但实际上没有。制作一个优秀的API是非常困难的。我试过好几次，我可以说我不是很好…但那只是学习：当你从学习开始，你只能看到一小段距离之外的东西，你知道的不多，所以你看不到更多的东西要学。你觉得也许你知道剩下50%的东西要学…但是当你学到更多的东西时，你开始意识到还有更多的东西…而且表面积越来越大。要想让你的知识更进一步，需要不断增加的学习。因此，第一次设计API时你会想：这很简单……第二次设计API时你会想：这有点棘手……而且随着时间的推移，它会变得越来越难……除非你是一个纯粹的软件架构师，谁能开始设计而不必忍受那些糟糕设计的后果…那么你永远认为API设计很简单…但这是另一篇文章的主题。这里是我对API的一些了解设计。尝试把细节抽象化，想象下一步会发生什么-如果你弄错了这没关系，但重要的是要确保API足够灵活，可以处理改变。如果你正在设计一个客户机-服务器API，试着让它不受客户机的影响……你不知道客户机的向后兼容性是什么国王，一个不是很烂，我负责设计的API觉得我很有价值教训。那个它的发展历程是相关。什么时候我加入了我以前的雇主，那里有一个控制电话会议的API。不幸的是，在这种情况下，API是为一个特定的会议网桥而设计的，而对其他网桥的支持却被栓接在一起。然后通过公司合并，一个完全不同的会议桥有了一个完全独立的实现，然后一个"让我们从头重写"的桥得到了它自己的新实现。但是对于整个API来说，一些关键的概念在新的VoIP世界里已经不复存在了是的。通过各种组织，我得到了支持这个API。作为最终负责支持遗留代码库的开发人员抱怨：那个代码是一堆废话，应该扔掉，用完全不同的方式从头开始重写！现在，你永远想象不到管理层会真的听你这么说（我以前的同事，或者任何认识我的人可能更喜欢用"喊叫"代替"说"，但那只是音量控制不匹配），但是，令人震惊的是，他们真的做到了。我的任务是为新的VoIP世界重新设计一个会议控制API……我们甚至还雇了一些新人来帮助开发，而且事实上很多客户都在使用旧的API.旁白所以我把我不想做的任务交给了比尔，即编写适配器层，为旧API的用户提供向后兼容性。他的第一个任务是针对旧的API编写测试，这样这些测试可以完成他对API所能想到的所有奇怪的事情，并验证它当前的行为（我有没有提到过，旧的API只有很少的测试，我们仅有的一点测试只会通过一个非常特定的会议网桥，该网桥的某些特定配置已经丢失重组期间）。当Graham和我将API锁定之后，Bill得到了一个有趣的任务：使用我们的新API重新实现现有的API，直到所有的测试再次通过。向后兼容性是旧API的一个重要问题，它将log4j类绑定在.jar中。如果您在客户机应用程序中使用log4j，则提示类路径地狱。如果您想使用不同的日志实现，那么就提示日志框架。通常，在Java中，我只使用slf4j，但当然我们有一个来自高层的架构师的指令，它要求所有新的开发都符合一个可访问的日志格式。[如果你是一家跨国电信公司，现在有充分的理由可以使用日志。你需要的信息和以上的日志记录是i18n和l10n意识，你需要你的所有产品日志转发到一个集中的系统。所以我并不是从高层批评这一具体的法令]。但是我们不仅仅有内部用户，这个API还将被客户使用……从我对旧API的支持来看，他们与我们的内部用户有着不同的日志记录要求……所以我们当然必须编写自己的slf4j版本……但在这样做的过程中，我学到了一个关键点-家：当你正在为API设计客户端库，保持绝对的外部依赖性最小值。这个很重要，因为您不知道将在何处使用客户端库。如果您的代码对log4j有很强的依赖性，而客户不想要log4j，那么您就给他们带来了痛苦。如果您的代码对log4j有很强的依赖性，并且客户使用的是一个分叉的log4j实现（我们的内部客户），它有一些不同的方法签名，那么您就是在给自己痛。这个不仅适用于日志框架…您的客户端库访问HTTP服务，所以您使用apachehttpclient，或者使用Netty或您使用AsyncHttpClient…这很好而且很好…但是如果与客户中相同库的不同版本有重叠，那么您将强制使用类路径地狱应用程序。那里它是我见过的唯一一个真正的第三方依赖库，我在其中看到了Java包名称更改时的evolution right（Jackson 1.x到2.x）他们做了一个突破性的API更改（而且Maven的坐标也改变了……实际上非常明智），这使得两个版本能够很好地共存。OSGi应该是解决这个问题的办法。。但是你不应该假设你的API的客户正在使用OSGi集装箱。这个不仅仅局限于Java……在任何语言中都有同样的问题……在jQuery的所需版本中是否有过冲突（为什么您认为jQuery有noConflict方法？）…而这套可爱的AMD和CommonJS规范只是一种OSGiJavaScript.So在编写客户端库时，请确保第三方依赖关系树尽可能小。在会议API的情况下，我们能够确保没有外部依赖关系。但事情并不总是那么容易。以一个CloudBees客户机访问库为例，它使用apachecommons HTTP client 3.1和XStream 1.4.1和jettion。我们试图把它集成到Jenkins中会遇到一些问题，因为Jenkins使用这些库的不同版本，因此，我们需要使用Maven Shade插件创建一个版本，在这个版本中，这些硬依赖项被着色到一个不同的包中，这样它就可以和平地与许多不同版本中可用的不同版本共存詹金斯，如果你的客户端库使用了更大的依赖树，我想让你开枪。要使用的一些比较有问题的依赖关系是那些与XML描述符相连接的依赖关系（这使得着色更加困难），AsideI已经向伟大的Java战争致敬了，那就是日志框架和http客户机库……我能不能在第三次Java战争中……我们拭目以待吧？别让我开始谈JavaEE vs Spring war。如果你的客户端库需要来自战争双方的依赖关系，你不是我的朋友。你实际上是在疏远每个人。你正冒着与任何站在你这一边，使用你的客户端库的人前后不兼容的风险，除非他们愿意将他们的飞船与你的幸运版本捆绑在一起……当他们有一个不同的客户端库来集成时会发生什么……而另一边的人，充其量是，面对着应用程序中上千个jar的膨胀，或者最坏的情况下甚至不能使用客户机图书馆。还有这是我的最后一点今天：你几乎从不想写客户端库，您希望通过类似REST的API公开API，并让每种语言的专家编写自己的API映射到这些语言中隐喻。如果您的API是一个使用标准技术的restapi，对于客户来说，使用他们现有的最喜欢的HTTP客户机库来连接到API应该是非常容易的，噢，瞧，所有的痛苦走了。如果你的API是一个使用标准技术的restapi，它是语言无关的，每种语言都可以将API概念映射到自己的母语结构中，如果你的API是一个使用标准技术的restapi，而你的客户抱怨编写客户机太难了，那么这表明你设计了错误的API……因为它应该很容易……如果不容易……你就错了！这是我谦卑的带回家留言：我有设计了很多API，现在我觉得自己在API设计方面几乎没什么能力（一开始还以为自己是个天才）。如果你认为自己擅长API设计，那你就是在自欺欺人。—斯蒂芬·康诺利·克劳比斯（Stephen Connolly CloudBees）cloudbees.com斯蒂芬康诺利在软件开发。他参与了许多开源项目，包括Jenkins。Stephen是Jenkins项目的首批非Sun成员之一，他开发了天气图标。斯蒂芬住在爱尔兰都柏林，那里的天气图标特别有用。在Twitter和他的博客上关注斯蒂芬。