首页 > 技术文章 > 如何设计API 摘要 《C++API设计》

tianc 2019-06-26 14:57 原文

许多软件工程师更喜欢把API 缩写为 Abstract Programming Interfaces 而非Application Programming Interfaces.

API 在c++中包含多个头文件及相关辅助文档

接口是开发者所写的最重要的代码,比起相关的实现代码出现问题,修复接口出现的问题的代价更大。

API是为编程人员所开发的用户接口,你的API可以被你没有想过的方式调用

修改API时必须保证向后兼容

API的生命周期比较长,为了创建好的API前期需要比较大的成本。因此规划、设计、版本、审查比不可少,后期大幅降低长期成本,对实现的更新改进不会影响客户

编写API时,良好的文档必不可少,尤其在不提供源代码的情况下。

自动化测试也非常重要,其他成千上万的开发人员依赖你代码的正确性,当对API进行修改时,一套完整的回归测试更有信心保证客户的程序不会奔溃。

API的好处

1.隐藏实现:通过隐藏内部实现细节,开发人员可以未来自由修改代码实现,不给用户造成重大影响

2.延长寿命:随着时间的延长,那些公开了实现内部细节的代码会变得错综复杂,系统的其他部分要依赖于另外的实现细节,系统会变得脆弱、僵化、顽固且粘渧性高,因此事先设计好的API,能后期保证一致性,软件寿命延长

3.促进模块化:API通常完成具体的任务和用例。API定义了一组模块化的功能集,大量API开发的应用降低了耦合,促进了模块化。

4.减少代码重复:通过将所有接口的逻辑置于一个接口之后,就将程序的某种行为统一处理,有助于消除代码复制。

5.消除硬编码假设:很多程序包含硬编码的值,并且不断复制,

6.易于改变实现:

7.易于优化:隐藏了实现细节不用,在优化代码时不用考虑客户端的调用

 

便捷API:简化API是一项困难的事情,减少API函数与API易于各种客户使用之间存在天然的矛盾

渐进式公开,API通过易用接口呈现基本功能,同时将高级的功能隐藏到另一个独立的层次中。

 

易用性:优秀的API设计应该使简单的任务更简单,使人一目了然。好的API可以让客户通过方法的签名知晓其使用方法,而不需要文档。遵循最小惊奇(leaset surprise)

  1.可发现性:可发现的API要求用户能够通过API自身明白如何使用它们,不需要任何解释和文档。

  2.不易误用:优秀的API不近易于使用,还要不易误用,这个是最重要的通用接口设计原则。

  3.一致性:优秀的API应该采用一致的设计方法,以便于用户记住其风格,进而更容易被用户采用。比如命名约定,参数顺序,标准的设计模式,内部模型语义,异常使用,和错误处理。

  4.正交:在API设计中,正交性以外这没有方法的副作用,调用设置的特定熟悉的方法属性的方法应该仅改变这个属性,而不改变其他公开访问的属性。

 

松耦合:

 

推荐阅读