技术头条 - 一个快速在微博传播文章的方式     搜索本站
您现在的位置首页 --> 系统架构 --> 好的API设计

好的API设计

浏览:11262次  出处信息

   最近在重构公司的一个交互中间件,在重新设计API及总体架构的时候思考了许多,,那么什么样的API才算是一个设计良好的API呢?

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

什么是API

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

   API简单来讲可以是一个调用的函数,一个接口。抽象来说:接口是一个内聚系统暴漏给外部的一切信息。

   包含但不限于:

  • 调用方式:比如通过lib库或者http接口等

  • 调用约定:比如lib的函数签名或者HTTP的参数,http method或者头信息,长短链接等等。

  • 依赖关系:比如接口的调用需要涉及到第三方或者其他的准备工作等等。

  • 设计良好API的特点

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

       变动困难

       API就像一个人一样,我们和一个API打交道的时候需要了解这个人的特性偏好等,

       有的人很好相处,而有的人让人很头疼,尤其是你不得不和他打交道的时候。

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

       好的API应该具有:

  • 易于学习  

  • 即使没有文档也易于使用  

  • 不易误用:这一点很重要,要减少使用者的心智负担  

  • 使用API的代码易于维护。这个有点不一样,不是API本身易于维护,而是API的友好度。

       比如接口功能单一,使用简单,使用者的代码也会相应的更易于维护


  • 易于满足需求:API的完备性和正交性。能够容易的满足需求,完备性保证功能完整,

       正交性保证接口的简洁性,不需要为所有的需求提供接口,而是由用户去组合。


  • 易于扩展

  • 怎么样设计良好的API

       基本原则:

  • 专一:一个API的功能应该是单一的,需要能够很容易的解释和理解,也就会更好用。  

  • 尽可能的小:小有很多的优势,易于理解和维护。  

  • 尽量少的外部依赖:减少使用者的成本  

  • 设计不被实现影响:不要暴漏实现细节给用户  

  • 竟可能少的暴露,不止是内部细节,对于不必要的接口尽量不要发布,比如使用不多的功能,

       可以暂时不暴露接口。


  • 良好的命名:尽量做到自描述。  

  • 完善的文档  

  • 考虑性能

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

    参考资料

  • http://mattgemmell.com/api-design/

  • http://lcsd05.cs.tamu.edu/slides/keynote.pdf 虽然是Java相关,但是道理是相通的

  • http://ishare.iask.sina.com.cn/f/61717785.html 《API Design for C++》

  • http://qt-project.org/wiki/API-Design-Principles

  • http://www4.in.tum.de/~blanchet/api-design.pdf (前面的链接里提到的)  

建议继续学习:

  1. Google短网址的API    (阅读:5141)
  2. 移动互联网api设计实践    (阅读:3794)
  3. HTML5文件API之图片预览    (阅读:3680)
  4. 如何设计一个优秀的API    (阅读:3688)
  5. 评判浏览器API好坏的标准是什么    (阅读:2493)
  6. 以用户为中心的 API 异常设计    (阅读:2413)
  7. Google font api、web font与中文    (阅读:2399)
  8. API设计新思维:用流畅接口构造内部DSL    (阅读:2135)
  9. 学习设计API    (阅读:1488)
  10. 使用DNSPOD的API实现动态域名    (阅读:1734)
QQ技术交流群:445447336,欢迎加入!
扫一扫订阅我的微信号:IT技术博客大学习
© 2009 - 2024 by blogread.cn 微博:@IT技术博客大学习

京ICP备15002552号-1