好的API设计

[非原创，原文链接]

API设计书籍下载：

　　1、keynote.pdf  

　　2、api-design.pdf

最近在重构公司的一个交互中间件，在重新设计API及总体架构的时候思考了许多， 不禁萌发了一个疑问，什么样的API才算是一个设计良好的API呢？

参考了许多的资料，做一下总结。主要来自这个keynote

什么是API

我们只要是在进行编程我们就需要不停的设计API，

API简单来讲可以是一个调用的函数，一个接口。抽象来说：接口是一个内聚系统暴漏给外部的一切信息。 包含但不限于：

• 调用方式：比如通过lib库或者http接口等
• 调用约定：比如lib的函数签名或者HTTP的参数，http method或者头信息，长短链接等等。
• 依赖关系：比如接口的调用需要涉及到第三方或者其他的准备工作等等。

设计良好API的特点

这里探讨的API均为系统边界的API设计，而对于内部API来说不在探讨范围之内。

变动困难

API就像一个人一样，我们和一个API打交道的时候需要了解这个人的特性偏好等， 有的人很好相处，而有的人让人很头疼，尤其是你不得不和他打交道的时候。

和人一样，如果你不得不和他打交道，要改变他的秉性是很痛苦的，人的“本性难移”, API也一样，一旦发布了，要改变的成本就很大很大。

好的API应该具有：

1. 易于学习
2. 即使没有文档也易于使用
3. 不易误用：这一点很重要，要减少使用者的心智负担
4. 使用API的代码易于维护。这个有点不一样，不是API本身易于维护，而是API的友好度。 比如接口功能单一，使用简单，使用者的代码也会相应的更易于维护
5. 易于满足需求：API的完备性和正交性。能够容易的满足需求，完备性保证功能完整， 正交性保证接口的简洁性，不需要为所有的需求提供接口，而是由用户去组合。
6. 易于扩展

怎么样设计良好的API

基本原则：

1. 专一：一个API的功能应该是单一的，需要能够很容易的解释和理解，也就会更好用。
2. 尽可能的小：小有很多的优势，易于理解和维护。
3. 尽量少的外部依赖：减少使用者的成本
4. 设计不被实现影响:不要暴漏实现细节给用户
5. 竟可能少的暴露，不止是内部细节，对于不必要的接口尽量不要发布，比如使用不多的功能， 可以暂时不暴露接口。
6. 良好的命名:尽量做到自描述。
7. 完善的文档
8. 考虑性能

其他具体的方法还是参考后面参考资料的内容吧。

参考资料

• http://mattgemmell.com/api-design/
• http://lcsd05.cs.tamu.edu/slides/keynote.pdf 
• http://ishare.iask.sina.com.cn/f/61717785.html
• http://qt-project.org/wiki/API-Design-Principles
• http://www4.in.tum.de/~blanchet/api-design.pdf