浅谈如何设计API（一）

1.为什么要设计API

什么是API呢？API的全称是：应用程序编程接口（Application Programming Interface），既然是接口，必然要涉及到至少两个方面：使用方、提供方。

有人的地方就有沟通，有程序的地方就有互相调用。如果说语言是人与人之间沟通的桥梁，那么API则是程序间调用的“桥梁”。

规模越大的程序中，API数量就会越多，API的质量高低决定了程序的可读性、易用性。设计一套（或多套）优秀的API能为整体带来良好的代码阅读体验以及高效的开发效率，同时这也应该是一个优秀程序员的必备条件。

2.如何评价API的好坏

我们来简单的看下如何评价一个API的好与不好。

• 2.1 名称及参数

方法名称是否可以自描述，即看到方法的名字就能知道方法的作用、看到参数名就知道需要传递什么样的数据（比如getUserById(String userId)）。

• 2.2 协议及行为

API会涉及到协议吗？答案是肯定的。一个方法的输入、输出就是协议，什么样的输入是合法的、什么样的输入是非法的，针对合法的输入在处理后返回什么样的结果、针对非法的输入返回什么样的提示以便调用方能快速知道问题的症结所在。

同时协议也要保证在不同版本间的兼容，新版本要兼容老版本，保证之前的调用方不会因为API的内部修改而不能得到正确的结果。

所谓行为就是API内部实现逻辑，有些时候，虽然我们提供给用户的是API，但是内部逻辑也在用户的可见范围内，这时候用户会查看内部实现并根据API内部实现编写自己的代码，因此内部行为的稳定同样很重要。

• 2.3 可理解及一致性

API一定要便于使用者理解，这样才是广泛传播的基础。如果有些API需要用户掌握特定的概念、定义，那么就要保持这个API的一致性，不能轻易的改变API，否则会给使用者带来很大的麻烦。

【推荐】
浅谈如何设计API（一）
浅谈如何设计API（二）