黑马程序员技术交流社区

标题: 如何设优秀的 API [打印本页]

---

作者: cuisq    时间: 2016-6-9 08:58
标题: 如何设优秀的 API
设计可以降低系统各部分之间的相互依赖，提高组成单元的内聚性，降低组成单元间的耦合度，从而提高系统的维护性和稳定性。

Joshua Bloch是美国著名程序式设计师。他为Java平台设计并实现了许多的功能，是Google的首席Java架构师（Chief Java Architect）。他也是《Effective Java Programming Language Guide》一书的作者，就是人们常说的 Effective Java。本文翻译自Joshua Bloch所发表的一个PPT：How to Design a Good API and Why it Matters。

随着大数据、公共平台等互联网技术的日益成熟，API接口的重要性日益凸显，从公司的角度来看，API可以算作是公司一笔巨大的资产，公共API可以捕获用户、为公司做出许多贡献。对于个人来说，只要你编程，你就是一个API设计者，因为好的代码即是模块——每个模块便是一个API，而好的模块会被多次使用。此外，编写API还有利于开发者提高代码质量，提高自身的编码水平。

优秀API所具备的特征：

    简单易学；
    易于使用，即使没有文档；
    很难误用；
    易于阅读，代码易于维护；
    足够强大，可以满足需求；
    易于扩展；
    适合用户。

了解了一款优秀API所具备的特征后，一起再来看看如何设计优秀的API，有哪些流程和规则可循，开发者在设计时需要注意哪些事项。
API设计流程中的注意事项

征集需求

在开始之前，你可能会收到一些解决方案，它们不一定会比现有的方案好，而你的任务是以用例的形式提取真实需求，并制定真正合适的解决方案，这样构建出来的东西就会更加有价值。

从简短的说明开始

这时，编写简短的说明最为合适，编写时需要考虑的因素有：

    灵活性要远胜于完整性；
    跳出规则：听取意见并严阵以待；
    精炼短小才易修改；
     获得信任之后将其具体化，在此之中，编程很重要。

尽早编写API

    对每一个实现进行保存，以防丢失；
    在开始之前，列出一些合理的规定，保存所写说明，以防丢失；
    继续编写和充实API。

编写SPI尤为重要

    Service Provider Interface即服务提供商接口，插件服务支持多种实现，例如Java Cryptography Extension
    (JCE)；
    发布之前编写多个插件；
    “三次原则”（“The Rule of Threes”）：指的是当某个功能第三次出现时，才进行”抽象化”。

维护切实可行的期望

    大多数API设计都过于约束；
    对可能会犯的错误进行预计，要用发展的思维来编写API。

API设计原则

每个API接口应该只专注一件事，并做好：如果它很难命名，那么这或许是个不好的征兆，好的名称可以驱动开发、并且只需拆分与合并模块即可

    API应尽可能地轻小：满足需求、对有疑问的地方可以暂时不使用（函数、类、方法、参数等，你可以不添加，但千万不要删除）、概念性的东西比体积重要、寻找一个良好的动力体积比；
    实现不要影响API：关注实现细节（不要迷惑用户、不要随便改变实现方式）、意识到具体的实现细节（不要有越权的方法行为，例如不要制订哈希函数、所有的调优参数都是可疑的）；
    不要让实现细节“泄露”到API（例如on-disk和on-the-wire格式等异常情况）；
    最小化可访问：设计人员应尽量把类及成员设为私有，公共类不应该有公共字段（包括异常实例），最大限度地提高信息隐藏，允许模块可以被使用、理解、构建、测试和独立调试；
    命名问题：应该见名知意，避免含糊的缩写、对同一样东西的命名应该有个一致性的前缀（遍及整个平台API）、讲究对称、代码应该易读。如下所示：

---

欢迎光临 黑马程序员技术交流社区 (http://bbs.itheima.com/)

黑马程序员IT技术论坛 X3.2