根据CA公司在2018年末的市场研究报告显示，API化、微服务和容器是企业现代应用架构的三大发展方向。关于后两者，本座在之前的好几期文章中都已探讨过了。而“API化”看似一个及其技术的标准，如何能成为应用架构的发展趋势，当下国内商业银行大搞Open API的寓意何在，本座今天来跟大伙探讨下“API化”的课题。

近年来各行各业都在讲能力输出，赋能生态，早年我们可能理解这些能力是现场指导，人员外包的方式，现在更多的是通过系统对接，数据传输的方式将内部能力外化，助力生态伙伴。当然在这个过程中，能力输出方一定不希望将代码逻辑、底层数据和盘托出，其实用户也不关心这些，他们只关注需要输入的字段是不是能得到预期的结果，就像我们打开手机地图查定位时并不关注App背后有的是基站定位还是卫星定位，只要结果准确就行。

上面说的这些内容大致就是API的功能了，从商业角度保护服务提供方隐私且精准应对客户需求，从技术角度如何设计一款易懂好用的API呢？我们以获取微信群群主的功能为例（这其实是一个开放的接口，去年有关部门不是约谈了很多群主嘛0），请求的报文格式是getAdmins (string ) 。getAdmins是微信群组的一个Method类，接入方的需求很简单，最多再加上返回两个错误码“该群组不存在”以及“该群组已删除”。

在设计这样一个API时，需要考虑到以下三点：

命名：Method类应尽量简单易懂，getAdmins加群组ID，使用户一看便知道是获取群组所有管理员的指令，而不应该返回创建者或全体用户，而且类似的指令（getCreator和getUsers）以后会有对应的API，因此好的API需要设计人员在一开始就界定好完整的命名规则。

参数定义：作为一款面向市场的产品，开发人员不能苛求终端用户熟悉API的全套参数，因此很多情况下我们把最浅显的参数暴露给客户，而将复杂的参数内部消化了，客户只看得到输入的群组名称和返回的管理员列表，中间的参数转换，服务间的调用都在内部系统之间完成了。

响应对象：除了告知用户管理员ID之外，还需要响应哪些信息呢？这是程序员之间的默契大考验，作为调用方，我可能希望获得的ID字段入库回头找他们约谈，我想知道ID的字段类型应该设成啥？长度是多少？或者在录入失败的时候最好能详细提示我究竟是什么原因。因此一个好的响应会将各种报错展示得很清楚，分主返回码和次级返回码，当然如果能提供详细的接口文档自然是最好。

在设计API时应尽量考虑简单，有些初级程序员喜欢将所有Method都放到请求报文中，再拿上面的例子来说，一个请求的报文（JSON）最好是：

{"groupID": "123"}，而不是{"action": "getAdmin"; "groupID": "123"}，因为getAdmin会体现在调用方发起的指令里，而不是请求的正文里。

伴随着企业微服务的深入，架构上不允许在一个应用开发中包含所有业务逻辑，不然会带来服务的紧耦合，不光资源不能独立分配，集成测试，系统运维都会牵一发而动全身。

以上只是get调用的形式，至于其他（例如post，put等）调用方式还需要考虑数据量大小（是否需要做分页或分片传输），缓存策略与一致性校验等等的问题，这都需要企业级架构师进行全盘统筹。