实现集成中 API 先行的七步指南

本文要点

过去十年间，企业使用 API 得到了突飞猛进的增长。不管是基于 RESTful 还是其他方式，API 已成为企业数字化的网关。因此，在向企业的利益相关者提供更好的数字化体验方面，可良好管理和维护的 API 是至关重要的。

API 需要理解为与商业契约类似。和商业契约一样，API 的设计和实现对企业数字化业务战略的成败至关重要。

大多数数字化转型项目中，集成先行和 API 先行是广为使用的两种策略。两者中，API 先行的方法更为高效，也永远不会过时。

企业中的 API 可分为三类，边缘（edge）API、工具类（utility）API 和领域（domain）API。边缘 API 担当企业系统的网关，领域 API 向集成层开放企业内部系统。工具类 API 中包含集成逻辑，实现边际 API 和内部系统的相互黏合。

在 API 先行的方式下，执行计划可划分为七个步骤。首先确定项目的目标，然后去了解企业的生态。进而确定当前系统可能的集成点、所需的集成功能和用例。对于所确定的每个用例，从边缘 API 着手去设计 API，最终实现集成。

想象一下，我们从早晨起床到晚上入睡，每天会与多少种数字化服务产生交互？所有的数字化媒体，包括移动端应用、网站、社交媒体应用、银行日常应用和 ATM 等，都直接或间接地使用了 API。我们每天都要与 API 打交道。

据全球领先的 CDN 服务提供商Akamai统计，2019 年 83%的流量来自 API，而 HTML 的流量已经跌到了只有 17%。相比之下，在 Akamai 2014 年的流量统计中，来自 API 的只占 47%。

对于集成领域的专业人士来说，API 的存在是不容忽视的。我们必须拥抱 API，并使用 API 先行（API-first）的集成思维来开发我们的集成用例。本文将介绍如何使用一种七步执行计划，以 API 驱动的方式开展项目集成。

在详细介绍“API 先行集成”之前，先给出使用 API 的优点。

视 API 为契约

API 是应用编程接口（Application Programming Interface）的缩写。在 API 先行的集成策略中，我们需要将 API 视为与商业契约类似。一旦需要与其他各方开展重要的业务，我们需要首先签订契约，或是双方达成某种协议。契约确定之后，我们才能开展业务。在集成用例中同样如此，需要首先确定 API。基于此，设计 API 的目的，就是将一组预先定义的后端系统功能暴露给网站、移动应用和 IoT 设备等前端应用。

图 1：API 的作用

优点

任何一家企业要在数字化中生存，设计良好 API 是重要的促进因素。下面列出 API 的一些应用场景：

• 作为企业数字资产的网关；

• 支持企业快速构建新的数字化消费体验；

• 开拓新的收入渠道，扩展现有的收入渠道；

• 为企业适应未来的发展提供支持。

上述所有优点，都依赖于 API 的具体设计与实现，以及集成的用例。

下面解释如何在集成项目中实现 API 先行。

集成先行 v.s. API 先行

当前企业所采用的 API 开发方式，无论使用 RESTful 或是其它技术，基本上可分为两种，分别称为集成先行和 API 先行。

集成先行方法基于传统的自底向上的方法，即首先在后端服务上构建集成逻辑，然后以受控 API 方式向用户开放集成服务（也称为组合服务）。

API 先行方法中，首先做 API 的设计，进而去实现 API 和集成逻辑。鉴于项目是从 API 设计着手的，所以称为 API 设计先行，简称为 API 先行。在本文中，我们将互换使用“API 设计先行”和“API 先行”这两个术语，它们指代的是同一方法。

为进一步解释上述两种方法，下面给出一个略微抽象的集成项目例子。

项目需求：

使用移动和 Web 应用，通过在线门户展示企业当前业务，为客户提供数字化体验。项目涉及后端和前端开发团队。

使用集成先行方法

1. 基于项目需求，后端开发团队开发集成层，暴露现有系统；

2. 后端团队通过 REST API 开放后端服务；

3. 随后，前端团队开始使用 API 连接 Web 和移动应用；

4. 前端团队发现一些功能很难使用现有的 API 实现，向后端团队发起了变更请求（change request，CR）；

5. 后端团队根据 CR 需求变更后端，改进 API；

6. 上述过程持续迭代，直到后端和前端团队就 API 可适于完成所有功能达成共识。

集成先行的方法对项目时间表和成本会产生一些不利的影响。团队之间的沟通也较少，并且一些设计缺陷只有到项目的后期阶段才会被发现。

图 2 集成先行方法

使用 API 先行方法

1. 前端和后端团队共同设计 API。将前端团队拉入设计这一理念，使得 API 开发人员可更好地获得用户体验。进而缩短功能实现的开发周期，因为开发人员不必去解决设计上的理解偏差。

2. 构建一组称为“Mock 后端”的样例服务，用于处理大多数的静态响应。

3. 后端和前端团队齐头并进地实现系统。其中，前端团队在开发中使用的是 Mock 后端；

4. 在后端完成后，再连接 API，完成集成测试。

API 先行方法可大大降低项目的延迟和成本超支问题。这些问题主要源自于前端和后端团队之间的沟通不畅，从而导致 API 和后端系统变更。

设计 API 之后，为便于前端团队进行 API 调用和测试，需要留一定的时间去启动和运行后端系统。为了解决此问题，前端团队可以设置为调用 Mock 后端的 Dummy 服务，去模仿所设计的 API，并返回 Dummy 数据。详细做法，参见资料“API mock指南”。

需求在某些情况下可能是模棱两可的，开发团队也可能并不确定如何正确地做出 API 预先设计。此时，需要针对一个缩小的范围去设计并实施 API。进而使用多个 Sprint 做多次迭代的方式，直到实现所需的范围。这样可以在早期阶段就发现设计上的缺陷，最大程度地降低对项目时间表的影响。

图 3 API 先行方法

API façade

在软件工程中，façade 设计模式用于隐藏系统的复杂性，为用户提供更友好的接口。API façade 背后的理念同样如此，它向应用编程人员提供复杂后端系统的简化 API。前文所说的 API 先行方法，需设计的正是置于 API façade 之前的边缘 API。

下图展示了 API façade 是如何将企业系统中的各个部分黏合在一起。

图 4 企业部署概览

从图中看，我们针对组织和用户（包括移动端、Web 以及 API 的直接用户）具有不同的后端系统。需要组合使用边缘 API 和 API façade 连接双方实体。

• API façade 中包括简化的 RESTful API，用于开放后端系统的功能；

• 边缘 API 组成 API 网关，提供 API 的全生命周期管理功能，包括限速、认证、授权等。

对 API façade 做进一步分析，可以看到它是由工具 API 和领域 API 组成的。

图 5 API façade 的图示

工具（Utility）API

如果后台的逻辑复杂，或是使用了特定的通信协议，那么需要设计工具 API，将后台开放给企业集成逻辑。后端服务的开放，并非必须通过工具 API 才能实现。对于Salesforce这样的 RESTful SaaS 应用，在没有复杂交互的情况下，可以直接连接到应用。否则，需要在后端服务的前面设计一个简化的工具 API。

领域（Domain）API

一旦后端开放，无论是直接开放的，或是通过工具 API，就可以使用包含消息调解逻辑或业务逻辑的领域 API。消息调解包含了消息传输、路由、服务链等。

识别数字资产

设计 API 先行集成解决方案的另一个方面，是掌握现有的数字资产情况。事实上，这是集成项目的初始任务之一。数字资产具有多种类型，不同的类型具有不同的集成方法。

• 完成企业关键业务能力的应用孤岛

应用孤岛（silo）主要是设计用于特定部门或单位的一些系统。它们从来没有考虑在全企业范围内应用并开放给对外部的世界。大多数此类系统是与特定部门的操作过程和实践紧密耦合的。在通过调解层开放此类型系统时，需要特别慎重。

• 企业 SaaS 应用

SaaS 已经开发成可被组织使用的服务，无需额外付出过多工作。它们通常以 RESTful API 形式开放。

• 企业数据所使用的各种存储机制，包括 RDBMS、文件、电子表格、CSV 文件等

组织使用不同的格式存储静态数据（data-at-rest）。我们需要了解数据存储的基本机制、格式，以及需要通过集成层在实体间传输的敏感数据。

• 执行企业内部过程流的应用

需要识别现有系统中所有的工作流。每个工作流会有不同的批准过程，或是不同的人工介入方式。

• 基于专有协议和数据格式的系统

一些现有系统，例如原有的数据库管理系统、CRM 等，会使用专用的数据格式。

关键的集成功能

项目集成成功的关键，在于理解现有系统的功能和新的需求。例如，是使用现成的集成产品，还是针对功能做内部开发，关键决定因素是对所需功能的理解。

下面列出我们在大多数集成项目中看到的一些关键集成功能：

• API 和服务托管：一种开发和部署服务的方式，可使用 REST 或 SOAP 服务。

• 服务和 API 的编排：通过聚合多个服务，形成端到端服务的能力。

• 路由：基于请求的内容和头部信息，路由所传入请求的功能。

• 转换：将传入消息数据映射为传出消息。二者可以具有相同的数据格式，具有不同的架构，也可以是完全不同的格式。

• 协议交换，以及处理各种数据格式的能力：消息从一种格式转换为另一种格式。例如，JSON 工作负载通过 RESTful API 公开为 SOAP 服务。

• 并行处理：在一些场景中，聚合后端响应，并向客户给出响应。例如，向多个后端并行发送请求。

在对所确定功能集成做出设计时，如果缺乏适当的经验或知识，那么最好从集成供应商那里获得帮助。这些集成供应商通过全球多个业务领域的大量集成项目而获取了丰富的经验，能为整个集成项目提供帮助。包括从 API 的设计到实现，甚至是在系统启动并运行后对系统进行维护。

一旦为项目选定了最合适的集成供应商，需要查看集成商是否能提供所需的功能。例如，为降低 IT 架构的成本，可以通过混合集成解决方案逐步将现有 IT 架构迁移到云上。

执行计划

上面介绍了在开展企业数字化转型项目中需要注意的几个方面。下面将给出一个遵循 API 先行策略的七步执行计划，用于确定秩序以避免实施中发生混乱，成功交付企业集成项目。

1. 识别项目目标

与利益相关者一起收集需求，形成项目的目标。基于此，确定项目实施的范围。

2. 理解企业的生态。

a. 识别所有的应用孤岛；

b. 理解数据情况。

一旦识别了项目目标，就可以整体上把握现有的系统，识别其中的应用孤岛、各后端系统、数据处理需求等。参见前文“识别数字资产”一节。

3. 识别每个系统中的可能集成点

在确定项目的目标后，我们可能需要去实际接触企业中的部分现有系统，也可能需要考虑项目未来的扩展问题。综合所得到的信息，再去选择适合的集成商。因此，至关重要的是识别需进行交互的系统，系统需要开放的特定功能。

4. 识别所需的集成功能

在理解了企业的数字资产和整体目标后，可以考虑所需的集成功能，参见前文“关键集成功能”一节。

5. 设计边缘 API

边缘 API 是前端团队需要与之交互的。首先设计边缘 API，其中大多数用于访问特定的系统功能。避免将后端的复杂性泄漏给前端应用，使 API 设计对应用开发人员更简洁。

6. 设计工具 API 和领域 API

一旦设计好边缘 API，后端团队就可以匹配边缘 API 的需求，着手设计工具 API 和领域 AP。如果碰上一些未考虑到的问题，可以按需回滚，更新边缘 API。

7. 实现前端和集成逻辑

一旦完成边缘、领域和工具 API 的设计，这时前端和后端团队可以开始实现系统。

通过将业务需求分解为多组更为细化的问题，该步骤可实现为多个 Sprint，而不是力图使用一组边际 API 去一次性地实现所有的业务需求。

结论

本文介绍了在集成项目中的 API 先行方法，这种方式可降低项目成本，控制开发时间，增进团队间的合作，改进整体质量，并为未来的扩展提供空间。此外，本文通过将方法归纳为具体策略，给出了一种分七步走的执行计划。

据Gartner分析，在 2020 年集成工作将占数字化平台建设中 50%的时间和成本。因此，在数字化平台建设中遵循正确的开发最佳实践是至关重要的。

作者简介：

Asitha Nanayakkara 是一名软件工程师，具有计算机科学和工程学士学位。他目前任WSO2的技术负责人，为企业提供构建集成产品的专业知识。Asitha 在担任国际公司（包括一些财富 500 强公司）集成顾问方面具有丰富的经验，并乐于与他人分享。

原文链接：

A Seven-Step Guide to API-First Integration