API的设计
前面的文章有我对公司的一些代码的吐槽,接着我就在想什么样的API才是好的API以及发布API的时候应该注意哪些重要的原则。关于API,维基百科的解释是这样的:
An application programming interface (API) is a specification intended to be used as an interface by software components to communicate with each other.
我们常说的API还包括Web Api。我理解的Api就是程序模块用来相互通信的。这里说的“程序模块”可大可小,小到程序中不同类之间的协作、大到两套不同编程语言的系统(web api)。
什么样的API是好的API?这个问题就像“你幸福吗?”一样难以回答,每个人都有自己的理解。stackoverflow上也有一个问题 http://stackoverflow.com/questions/469161/how-do-you-define-a-good-or-bad-api。
对api的评判标准分多个视角来考虑。作为api使用者,我希望:有一个好的文档、使用简单、不要随意发生变化。作为一个api的维护者,我希望:有好的文档、api是简洁的、api是易于修改的。
设计一个API应该遵循什么原则呢?我想看看前人是怎么做的,于是我找到了这个 http://lcsd05.cs.tamu.edu/slides/keynote.pdf 。是Google 一位工程师的分享。看完之后我认为应该将下面几点付诸实践。其中英文部分是原话,其他的是我自己的理解。
- API Should Do One Thing and Do it Well. 这跟写一个函数差不多,一个函数只做一个事情。
- API Should Be As Small As Possible But No Smaller. 也类似函数,一个函数应该足够简单,简单到不能在简单。
- Implementation Should Not Impact API. api的应该是与实现无关,api一旦发布就几乎不允许修改了。但是实现可能是会发生变化的。
- Minimize Accessibility of Everything. 不要暴露任何多余的东西,例如一个类,就应该尽量把所有的成员变成private。任何一个多余的地方都有可能被误用。
- Names Matter–API is a Little Language. 命名当然是很重的啦。
- Documentation Matters.
- Consider Performance Consequences of API Design Decisions. 性能很重要,特别是web api,可能会被调用很多次。