掌握聚合最新动态了解行业最新趋势
API接口,开发服务,免费咨询服务

如何设计出好用的API

 你设计的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

sdk.jpg

原文来自:SDK.cn

声明:所有来源为“聚合数据”的内容信息,未经本网许可,不得转载!如对内容有异议或投诉,请与我们联系。邮箱:marketing@think-land.com

0512-88869195
数 据 驱 动 未 来
Data Drives The Future