如何设计好软件的API

crazyhadoop

获奖名单已公布：http://bbs.chinaunix.net/thread-4171401-1-1.html

话题背景：


团队合作过程中免不了需要和别人合作，对于软件开发人员来说，API可能是最直接，最有效的沟通方式。但是，现实很骨感，你发现别人提供的API要么不能很好的满足你的需求，要么功能不能保持一致性。对每个人来说，API的一致性都是最大的问题。原因不只是处在开发人员的身上，他们其实也是想保持一致的。自己知道如何做某件事，可能就是无法和别人讲清楚。那么API设计到底有什么特殊的地方呢？API 也是软件和外界交互的门面，间接的表达了软件内部的设计。可能API不适当的一个表达，就反映了内部架构上的问题。

本期话题：

1. API设计的特殊之处在哪里？
2. 如何评价API设计的好坏？
3. 总结一下自己设计API的一些经验。

活动时间：

2015-1-27~2015-2-27

活动奖励：
程序员必读之软件架构

作者： (英)Simon Brown   
丛书名： 图灵程序设计丛书
出版社：人民邮电出版社
ISBN：9787115371072
上架时间：2014-11-5
出版日期：2015 年1月

zsszss0000

沙发啊，谷歌一个工程师制作了一个PPT，讲述如何设计API，感兴趣的大家可以搜索 《How to Design a Good API and Why it Matters》

forgaoqiang

这个靠谱 做接口还是挺有技术含量的

qingduo04

地板上了！！！

NumberOneFrog

菜鸟一只，不知道以后能不能接触到这些目前够不到的地方

crazyhadoop

回复 3# forgaoqiang


    相当有技术含量，尤其是新旧版本兼容，不小心就被人喷死了，关键是会造成重大事故

crazyhadoop

回复 5# NumberOneFrog


    写程序，就会写API，怎么会说是距离自己很远呢？

fire_cpp

实际上，API设计并不程序员的职责（至少大部分不是），而是主程序员、架构师的责任，API反映了架构和业务流程，所以，除了需要与其它程序员沟通之外，还需要和各业务部门沟通，除了确保按架构师的意图完成工作之外，还需要确保业务流程的正确、清晰地实现。

1. API设计的特殊之处在哪里？
体现架构与流程，确保至少较长时间内的稳定性。

2. 如何评价API设计的好坏？
是否体现架构意图，是否有良好的软件工程原则体现。

3. 总结一下自己设计API的一些经验。
良好的软件工程原则，良好的业务体现，良好的架构理解，良好的沟通。

cjdao

1. API设计的特殊之处在哪里？
    api设计最最特殊的地方也是最需要设计者考虑的地方，就是它的稳定性及易用性。
    所以设计者在更新api设计时总是以一种向下兼容的方式来做。
2. 如何评价API设计的好坏？
    1).不标新立异，这一点可以参考C++语言，它允许使用者重载操作符，但是如果你
        将operator+重载成operator*的语义，那么往往预示着你建造了一个滋生bug的温床
     2).把握好api的粒度，不要一味地讲究大而全，最好以8020原则正交的提供好一个最基本的
       操作集，剩下的功能留给使用者去实现，或者在更高的层次上去实现多一个层
     3).  简单易用，尽量减少使用者的学习成本      
3. 总结一下自己设计API的一些经验。
    1). 这是一个需要反复琢磨的迭代过程，你基本上无法一次性做好，你需要自己试着去写一些使用自己
         设计的api的代码，去感受它的实用性
    2).参考类似的api设计，发现自己考虑的欠缺，让其他同事试着来使用并评价你的api

shenlanyouyu

1.API设计的特殊之处在哪里？
      在工作中，一人完成整个项目的单打独斗的时代已经过去。在工作中很多时候我们都是承担的一部分模块功能的开发，最后将多个模块整合起来，模块间的通信是通过定义好的API来完成，不必要了解其他模块的内部实现细节，只需要阅读API使用说明，就可以使用其他模块提供的功能。
      毫无疑问的是，API是给用户使用的，无论用户是公司内部团队还是外部用户。要设计好的API，满足用户的需求是最重要的。因此需要站到用户的角度来思考，面向用例来设计API，才能保证API设计的合理性。
      API的特殊之处在于API是开发者所编写的最重要的代码。因为比起相关的实现代码出现问题，修复API的出现的问题代价要大得多。如果一个特定的应用程序代码出现了错误，只会影响到该应用程序本身，而如果API的代码中出现了错误，就会影响到所有使用该API的应用程序。

2. 如何评价API设计的好坏？
判断API设计好坏可以从以下几个方面出发：
(1) 一致性，一致性是API设计的重要的评价标准。一致性包括两个方面，API应该在版本间保持一致，其次是API对外提供的功能一致。
(2) 可理解性，API易于学习，用户能够理解API的用法。
(3) 可维护性，API支持后续的维护，添加新的需求。
(4) 功能的内聚性，一个API提供的功能应该只包括用例中说明的功能。

3. 总结一下自己设计API的一些经验。
     在工作中主要用C/C++编程语言，所以只能说说C/C++相关内容。设计API是给内部team使用，因此在设计之前会根据自己承担部分模块的功能，和上下层模块复杂人沟通，商定了好通信流程，维护一份API文档。如果在开发过程中需要修改，及时将信息反馈，并及时更新文档。API必须有使用说明和完善的文档记录。由于C++允许同名函数，因此在设计之初，对于函数参数一定要把握好。其次，对于同一个功能实现进行扩展，需要提出新的API时，保持API的一致性，可以参考Microsoft的做法提供新的API，例如CreateThread和CreateThreadEx；使用设计模式，提供API的灵活性。例如基于C语言的callback函数实现观察者模式，qsort函数也是一个使用callback实现的功能强大的排序函数。其次可以从开源项目宝库中学习经验，Glibc、Linux、Android等都是学习API设计的宝库，学习里面良好的设计。例如在C标准库里面getchar函数就是一个糟糕API设计例子。建立API的审查机制，团队对API设计进行Review，团队中每个人根据自己经验给出评价。