原 文：How to design APIs that don’t suck
译 文：SDK.cn
作 者：鲁行云（编译）
你设计的API，很可能会被其他开发者所使用。因此不要让你的API用起来让人感到痛苦。如果你不想让其他开发者在背后骂你的话，那就把你的API设计好。
在这些年中，我积累了一些API设计的技巧。我把它们进行了总结。
详尽
这一条是最重要的技巧。假如你的API中一个名叫getUser的方法，它会引起一些副作用，如果你没有详细说明的话，它会引发很多问题。
在没有详尽说明的情况下，不要调整那些共享可变状态。如果我调用getUser，我只是期望它会返回一个用户，并不想引发其它作用。你也可以考虑使用不可变的数据结构。
在给方法/类/模块起名的时候，尽可能的在名字中详尽的表明其行为。不要以为用户会去在源代码中搜索它们的隐藏行为。
“API军团”的规模越小越好
没有人喜欢臃肿的程序。在完成一个项目的时候，所使用的API数量越小，开发者和用户的体验越好。
加入你想写一个新的API，先考虑一下，是否真的有人希望你写它？如果这个API所解决的并不是人们特别想马上解决的问题，那你就可以暂时拖延这个计划。
一些环境（例如安卓）会限制应用所使用的方法数量，这一点你应该牢记。
减少boilerplate
尽可能多的处理好部署细节，能够减少用户的负担。用户所做的事情越少，你用来修复bug的时间也就越少。
这里还有一个美学的问题。写太多的boilerplate会让完美的API也变成糟糕的API。我们都喜欢简洁的代码，当用户在使用你的API时，你应该帮他们保持代码的简洁性。
减少依赖
不要让你的代码有太多的依赖。因为依赖越多，出现问题的可能性就越高。
如果你真的想要使用其他模块的某个功能，你可以尝试将这个功能提取出来，只用这个你想要的功能，其他无关功能完全抛弃。
出错提示要让人看得懂
在给用户弹出错误提示的时候，只显示一个null是毫无意义的做法。
这种提示根本无法让用户知道哪里出了问题，也无法让他们找到解决办法。你完全可以给出让人能看得懂的错误提示，例如：
Error.USER_NOT_CREATED或是Error.USER_DELETED
在可能的时候，你也可以在错误提示中给出相应的解决办法。
做好说明文档
没错，写文档是件无聊的事情。但是和许多无聊的事情一样，它是必不可少的东西。好的文档能够让你省下很多时间。文档写的好，用户就可以自己找到问题的答案，他们不再需要来询问你。
好的文档应该包含以下内容：
- 整个模块的总览和其工作方式
- Javadocs, Heredocs, Rdocs等公共方法和协议
- 充当使用说明的样本代码
而且文档也需要定期升级。如果好多用户一直在就一个问题对你进行提问，你可以考虑将这个问题添加在未来的文档中。
写好测试
测试是API开发中必不可少的一环。在你对API做出改变的时候，测试能告诉你新的东西是否能正常运作。
对于那些想要更加深入了解你API的用户来说，他们也可以通过测试报告来了解代码的行文。文档无法覆盖API的所有东西，这是就需要使用测试报告来补充。
你可能会问：“既然都写了测试报告了，为何还要写说明文档？”打个比方吧，如果说文档是用户手册的话，那么测试报告就是x86操作码指令参考。
让API本身可测试
测试你自己写的代码是一回事，让你的API可以被其他用户测试，则是另一回事。对于那些特别重视测试的开发者来说，如果你的API很难进行测试，他们就会非常恼火。
给用户一定的选择
每一个用户使用API的方式都不一样。一些人偏好同步调用，另一些人则喜欢异步调用。
你要让用户有一定的选择权，让他们自己选择使用方法。API与用户程序整合的方式越多，他们使用的意愿就越高。
但是不要给用户太多的选择
但是也不要一次性给用户太多选择，否则他们在使用的时候就会遇到选择恐惧症。分析一下人们使用你API时最主要的使用方法，然后将其设为默认行为。
你需要有一定的态度，不要因为给了用户太多选择，而让你的API失去重心。
总结
API的设计有点像是艺术。希望我给出的这些技巧能帮你设计出更好的API.
