驱动api_以API驱动的开发流程：选择一个出色的API规范可以帮你节省时间和省去麻烦...

转发，原文来自专栏《微服务应用开发和API管理》链接：out4b：以API驱动的开发流程：选择一个出色的API规范可以帮你节省时间和省去麻烦

在API开发的实践中有一项重要的过程就是规划API规范。API规范通常包含一组API（通常我们称之为服务）的定义，就像房子的蓝图一样。一份API规范中应该包含一个微服务应用提供了哪些API，这些API上承载的数据的定义。API规范可以帮助提前做好应用的结构设计，所以API规范的编写是开发前的关键步骤，它可以帮助你在编写代码之前降低设计缺陷或问题。

API驱动的开发流程

在以API驱动的开发过程中，开发者首先创建某一种机器和人都能识别，并且长期存在的API规范。遵循API规范，可以让你在开发API时提前捕获任何小故障或不一致之地方。虽然这个过程将使开发工作增加少量开销，但这项工作必不可少，因为它可以大大加速后面应用开发和测试维护的时间。预先规划好的API规范可以为你的开发节省数月甚至数年的时间，并且提高已开发好的API的复用性。否则，除了要在API设计上多花时间，有时候甚至必须从头构建一个新的API。

API驱动的开发流程鼓励将设计阶段与开发阶段分开，并迭代地进行处理。API的实现快速演进，但API规范保持稳定，可以确保API的使用者不会受到变化带来的影响。这也意味着使用标准化规范构建设计时，就可以通过模拟并获得用户反馈信息来测试该规范。

API规范有很多类型，对于REST API，较为流行的API规范有Swagger, RAML等。对于SOAP，通常使用基于W3C标准的，XML格式的WSDL规范。 对于REST和SOAP区别感兴趣的读者可以参考我的另一篇文章比较REST和SOAP之间的差别。

简洁的API规范

作为国内API管理领域的领导者，灵长科技开发的通用企业应用接口管理系统（CEAMS）为Node.js开发者提供了包括Web IDE在内的全套微服务应用开发以及API管理工具，以及相应的后台微服务框架：CDIF的支持。在CEAMS上，系统也为开发者提供了一份创新的内置API规范模型。这份API规范模型可以看作是一个JSON版本的WSDL规范，可以被用来描述在CEAMS系统上运行的云端微服务应用提供的JSON API接口，以及在这些API上传输的JSON数据的定义。

与基于REST的API规范例如Swagger等相比，CEAMS系统提供的API规范不需要用户费力思考自身应用对外提供的一组REST API应该各自放在哪个资源路径上；应该采用什么样的HTTP请求方法（get, post, put, delete）；使用什么传参方法（query string, form, json body）等等细枝末节的问题。只需要用户通过系统提供的方便易用的JSON Schema编辑器，编辑API上输入和返回的JSON数据的类型即可，相比之下更为简洁和强大。同时，系统采用JSON格式作为API规范，也避免了WSDL那样的基于XML的规范带来的复杂性。基于用户编辑完成的API规范，系统提供的API入口默认向每个应用唯一的URI地址，统一使用POST JSON body的方法提交API请求数据。

在CEAMS系统上，系统采用API驱动的开发流程，要求开发者从规划API开始，通过系统提供的JSON编辑器创建和编辑这份API规范：用户首先为自己的API起一个名字，同时为它自由地构造符合JSON Schema标准的，任意嵌套复杂度的API请求和返回的JSON数据结构定义。从这份API规范出发，系统将自动为开发者创建应用的框架JavaScript代码、API文档、API调用方的接入代码（目前支持Java）、以及在线的API测试工具等等。这些工具可以帮助开发者在很大程度上减少编写代码、文档和手动测试的精力，保持文档和代码永远一致，减轻对接和同步的工作量。同时，系统将根据开发者编写的API规范中提供的JSON schema数据定义，在运行时自动对输入的API请求数据做数据验证，并过滤掉不合法的请求，帮助提高微服务应用的数据安全性和稳定性。

采用JSON API的设计，Node.js开发者在CEAMS系统上将很容易地将API请求映射到后端各类npm工具库的输入中，比如各类数据库驱动，数据处理工具等等，并从中获得需要的数据，而无需去关心在设计REST API时需要考虑的路由、请求方法等细枝末节；但又不得不去实现的问题。

API设计背后的逻辑思路很简单：保持足够的灵活性和复用能力。这也就意味着当你构建API时要提前计划——不仅仅是规划项目路线图以缩短开发周期，而是为未来一两年可能存在的需求做出安排，好的API应该支持多种内容类型并保持灵活性开发者要保持一颗正确的心态——因为你将长期关注你所构建的API。选择一个出色的API规范可以节省时间以及省去开发过程中不必要的麻烦，同时，选择一个全面专业的开发平台，同样也会提升开发运维效率。