深入理解云计算OpenAPI体系

一  导读

提到API，从事技术的同学都十分熟悉，无论是在操作系统上开发软件，还是打造分布式网络服务，都离不开对各种API的调用。对应用程序开发人员来说，都会通过各种编程语言、系统调用和各种类库、编程框架构建系统，为了提升开发效率和统一性，就出现了各种各样的API标准，例如POSIX。这些标准的实现保障了应用程序可以不做过多修改就能运行在各种软硬件平台上，大大促进了整个IT生态的发展。

然而就云计算的API来看，当前并没有类似POSIX这样的API标准，基本上各大厂商各自为政。当然，有一些业界主流标准例如OAS获得多数云厂商的支持，但云厂商本身的API却往往由于历史原因、技术路线原因百花齐放，例如AWS的OpenAPI属于RPC风格，而Azure则是WebService风格，GCP则是基于gRPC为主流。技术方面的论述很多，本文更想从客户体验、研发效能的角度来阐述OpenAPI对云计算整体竞争力的重要性。

二  云计算OpenAPI的特点

如果将阿里云飞天操作系统与传统操作系统类比，那么它也是由内核层、接口层、操作界面、业务应用组成，计算、存储、网络等核心产品构成了内核，API层承担内核的管控和数据通信，各式各样的控制界面则相当于操作系统的Terminal/Windows/mac OS UI，基于云计算的各种行业应用则是跑在这个操作系统上的应用。

图1 飞天操作系统

阿里云不同于传统操作系统，OpenAPI自然也不同于其他业态的API体系，例如淘系、B2B的开放平台。业务开放平台输出的是以业务数据为主的服务，目的是为了整合商业生态，而阿里云开放平台输出的是云操作系统的管控能力、数据操作能力和其他企业级能力。前者重心是服务商业模型，而后者重心是服务技术底座。因此，云计算的OpenAPI体系要以服务技术开发者和企业场景为中心，保障技术体系的健全稳定，对外紧密对接行业技术体系（例如开源工具、三方厂商），对内促进众多云服务协同管理。

阿里云的OpenAPI有如下特点：

• 数量多：当前阿里云OpenAPI数量高达1万多个，每天调用量上百亿，分布在近300个产品上。

• 增速快：业务发展快，近年来每年数量的增速接近100%。

• API类型多：OpenAPI大体分为管控、数据两类，管控类又分为RPC/ROA两种形式，数据类又会分为数据流、文件等具体类型，还有很多业务需要有自己的格式。

• 产品协同要求高：单个OpenAPI是不能满足用户要求的，场景化的用户需求需要多个产品的多个OpenAPI组合才能服务，这对API编排、产品间API协同提出了更高的要求。例如在稳定性方面，一个产品的OpenAPI出问题有可能造成整个管控链路的雪崩。

• 企业能力需求强烈：OpenAPI主要是用来进行云资源管理或数据传输的，操作对象都是用户资产，除了常规的身份管理、权限管理外，对企业来说还要服务于运维、财务、法务、监管等部门，当涉及众多的云产品时对架构和底层设施的完备性、准确性、及时性要求很高。

• 与行业技术趋势结合紧密：云是全球化的，作为平台它要想服务好各种场景、人群就离不开与各种业界标准和技术体系相结合，云计算与开源行业高度结合证明了我们做的技术不能闭门造车。

• 稳定性风险加大：商业开放平台的OpenAPI如果不稳定影响的可能只是客户侧某个业务功能模块或流程，但是云OpenAPI出问题影响的可能是客户底层技术系统，爆炸半径会更大。

• 调用热点集中：调用量分布基本符合二八原则，20%的云产品承担了80%的调用量，核心产品的体验决定了用户对阿里云的体感，保障客户典型场景的运作至关重要。

上述特点决定了云上的OpenAPI相比于传统开放平台，要侧重技术能力的建设，同时又要兼顾客户企业级场景，才能做好体验工作。

图2 OpenAPI用户需求层次

三  管理自动化是企业客户的核心诉求

那么云计算客户在OpenAPI领域核心体验是什么？以阿里云上某实际案例来分析，具体要点包括：

• 客户希望全部的流程都是能够自动化的，从代码提交到服务器部署全部通过自动化工具进行。

• 许多客户希望使用混合云体系，云上云下两部分结合，业务系统与云平台紧密集成。

• 客户系统中大量使用多种开源软件，例如Git/Jfrog/Terraform等，希望能够整合形成完整的自动化流程。

总结起来客户的核心诉求是：客户业务系统要能够与云平台高度自动化地集成。不仅是客户，云厂商经常强调弹性、自愈等概念，其背后也是高度自动化的架构在支撑。

要做到高度自动化地集成，对OpenAPI体系是全方位的要求。对比一下POSIX，一套标准的、完备的、质量良好的API能够促进各操作系统之间的兼容性，确保上层应用的开发移植成本最低。而对于云计算，这样的规范应该在哪几个方面来满足客户的需求呢，实践中我们总结如下：

• 风格一致性：POSIX API的风格基本是一致的，例如文件处理API，其核心错误码都是一致的。一致的风格、术语、错误、操作模式，可以让应用程序开发者降低理解成本，提升效率。而如果不同产品API设计风格不一致，用户理解成本很高，使用不便，就会对云平台专业性产生质疑。例如，当前阿里云的OpenAPI就存在专业术语在不同产品中描述不一样，同样的资源信息各产品属性和数据不一致，分页API的形式不一致，甚至大小写命名也不一样的问题。

• 功能完整性：功能完整其实不难理解，但是如何定义功能完整性一直有争议，一个云产品是开放10个API就够了，还是开放100个才够？有点见仁见智，况且产品也是在一直演进的。POSIX文件处理涵盖了一套标准的文件处理API，包括create/close/dup/dup2/fcntl/flock/fsync/lseek/mkstemp/open/read/sync/write等 API，所有关于文件操作可能的API都存在了，这样用户才能精细控制文件。所以对于云上资源，由于客户需要对其进行全生命周期自动化管理，那么客户视角的所有管理动作都应该被开放。在实践中一般用实体关系模型去设计一组相互配合的API，不可随意零散处理。

• 服务有效性：实践中最大的问题是不同团队对于API SLA的标准不一样。例如在可用性上有些产品要求99.99%，有些产品觉得99%也能接受。极端的例子，如果某些OpenAPI只能允许一个并发，这样的OpenAPI对用户来说是没有服务质量可言的，自动化也会因为各种异常被终止。同时，如果必须某些限制，例如限流，ToB场景下是要告知客户的，否则客户端将不知道如何去优化自己的调用频率。

• 配套体系健全性：客户体验是客户从知晓到使用产品的心理感受的全过程。Linux/Mac上的开发体验很优秀是因为配套的工具链很成熟，具备完整的体系。云上客户基于OpenAPI开发时也应该能够获取专业的、详细的工具支持和技术支持，就像Visual Studio要有MSDN，Java开发要能够有IDE，任何语言都需要debug工具一样。像SDK、文档、调试工具是必备产品，同时诸如代码示例、API调用可视化等功能也是非常有价值的。

除此之外，云计算内部系统也需要通过API实现高度自动化。一些典型的场景例如专有云部署、新region扩建、单产品扩容，如果不能够自动化部署，对公司整体人效是不利的，更重要的是实施时间会拉长，客户体验也会变差。

要解决上述问题，主要难点在于如何统一标准、如何建立全面的配套平台体系、如何衡量服务质量、如何持续推动服务达标以及如何考察客户体验。

四  云计算需要面向资源编程

Linux/UNIX世界中，有个著名的说法： 万物皆可文件化。那么云上的万物能否资源化呢？

阿里云对外的OpenAPI都是基于HTTP协议，RESTful规范有提出基于资源设计的理念。 而实际工作中，能坚持这样的原则的API却不多。经常会碰到的疑问是“什么样的东西应该定义为资源？”“我的API没有资源化设计不也工作的挺好？”“我设计的时候有资源概念，但是客户没这需求啊？”。

然而，客户的困惑却是真实存在的：

• 想自建一个资源管理系统，阿里云上怎么能知道我拥有的所有资源列表？

• 那如果通过OpenAPI获取，怎么能知道这个API对应的是什么资源，资源能做什么操作，资源与资源之间有什么关系呢？

• 不同的产品在同一个资源类型情况下，怎么返回的属性不一样啊？

• 想查询不同产品若干资源的组合状态，目前一个个写代码太麻烦了，有什么好办法么？

• 自己去理那么多API对应的资源类型工作量太大了，能不能说说阿里云自己是怎么做的？

面对客户的需求，我们需要回答几个问题：

• 什么是资源？哪些资源应该被管理？无需管理的服务是否也要被定义为资源？

• 阿里云到底有哪些资源类型，统一的列表在哪里？能不能通过OpenAPI自动化获取？

• 这些资源类型的属性是怎样的？能做什么操作？对应的API是什么？资源有哪些状态？资源与资源之间的关系是什么？能不能保证资源都是一致的？

• 用什么方法能够面向资源编程减少开发成本？

对于云计算场景，如果没有资源模型，内部研发效率也会受到影响。原因是企业客户不同于个人客户，相对成熟的企业都对人、财、物、权、法的监管需求强烈，面对内部管理、盈利、监管约束等挑战，一套成熟的IT治理体系对资源概念的依赖是极高的，如阿里云的RAM/ActionTrail/Config/RD/ResourceManager等。没有资源模型，这些产品就要各自定义资源，分别找云产品沟通，实施落地进度和质量也不能保证一致。开源软件也一样，例如Terraform就是面向资源的。甚至很多平台服务如账单，也需要资源的概念才能更好地管理。

图3 资源生产者和消费者

如果能够统一资源模型，就相当于客户和阿里云在有一套面向对象的Java类或者数据库表，凡是依赖该资源模型的产品都将从中受益，理解更容易，沟通上保持一致性，研发上可以提供统一的技术方案提高效率。

所以，面向资源编程的API设计，对于客户和云平台自身都是非常重要的，如果前期不考虑，后期会付出更大的成本，必将影响阿里云整体服务质量。

五  云计算需要沉淀统一的OpenAPI/资源元数据

元数据是关于数据的数据，它描述的是数据组织、数据域及其关系的信息。元数据平台并不是新鲜事物，比如在大数据领域就有很多应用。由于阿里云有数百个产品，上万个OpenAPI，所以资源的数量也必定是庞大的，这时候就有必要有一个统一的平台来管理资源信息。而资源只是一种抽象，背后还需要依赖 OpenAPI的元数据，两者结合才能对外提供完整的服务。

那么统一OpenAPI/资源元数据能带来哪些价值呢：

1. 促进产品体验一致性：阿里云各个产品线独立发展，但是会面临此资源非彼资源的尴尬境地，每个产品都有自己的认识，非常不利于统一客户体验。
2. 提升沟通效率：统一的模型就像一个标准的数据库schema，能够让相关的业务方都能够在一个语境中沟通。
3. 提升研发效率：结构化的标准模型，能够让程序代替人来处理模式化的数据；以Terraform为例，有了资源元数据，可以直接编写自动化脚本生成terraform模块，将云产品的接入效率提升了50%左右，过程中就节省了Go语言研发资源和联调成本。

图4 基于API元数据无代码自动化生成

1. 提升业务质量持续保障：软件研发有个痛点是云产品初次发布后，如果随着业务迭代，如何保障过往的功能正确性。以阿里云的RAM产品为例，如果我们能够将资源元数据、API访问日志、RAM的Policy与云产品实际鉴权日志放在一起，通过对比元数据声明内容与实际发生的动作，就可以检查云产品的鉴权行为是否符合预期。相比于人治，基于数据和代码的自动化平台检查机制会更高效、更准确。
2. 更多的业务场景赋能：Azure有一个产品叫Resource Graph Explorer，它能够按照资源维度管理平台上所有的资源，跨地域也不是问题，有点类似于Windows的资源管理器。完善的元数据管理，将使得这类产品的研发变得可能。可能有人会有疑问：没有元数据就不能做吗？理论上可以，但是一定是事倍功半，因为它需要与各产品反复协调沟通，成本极高，而不是用一套平台来承载着标准化的生产流程，且不好复用，不可同日而语。

所以统一的阿里云OpenAPI/资源元数据管理，对内价值是许多围绕资源的业务开发都将变得更加轻松，甚至无代码化，提升业务效能，对外客户将能得到与内部一致的业务模型，提升用户体验，更加方便地集成。

六  OpenAPI体验是云客户的核心体验之一

云操作系统想服务好客户，经过优良设计的API是必需品，否则用户很难快速高效地基于API层来开发和部署应用服务，会对商业竞争力造成严重影响，一个各种理念能力都是顶级但却难以管理的操作系统谁愿意使用呢？

1. OpenAPI是云产品的服务契约。云平台不但要保障服务质量，而且一旦上线下线极难，产品很难冒风险去强行关闭某个API，不兼容变更也不行，等同于违约，有可能造成客户业务系统的崩溃，随后就是法律风险、舆情风险和客户流失。
2. OpenAPI的成熟度很重要。客户在使用云服务的时候货比三家，除了价格、稳定、功能等因素外，是否能够快速、方便地与客户业务系统集成是重要竞争因素，阿里云接触过许多大客户都在API成熟度上有明确要求。
3. 良好的开发体验和丰富的服务生态或将成为云厂商的核心竞争力。Windows靠视窗系统的体验代差霸占消费级操作系统市场，Linux/Unix在windows环伺下靠企业级开发能力占据企业级市场，macOS的良好开发体验又在windows一统天下的局面下杀出一条血路，都说明最终制胜必须围绕客户体验展开。当各厂商在核心服务能力上随着时间的推移逐渐同质化之后，差异化竞争力就在于价格、体验、服务了，而现在国外竞对在体验上的优势也是多年沉淀下来的护城河，不投入时间和资源来沉淀是不可能比肩的。
4. 客户视角在云计算场景下尤为重要。其逻辑不是我们有什么接口可以开放，而是客户需要我们开放什么接口。功能接口开放度不足可能会导致客户的生产流程中断，严重影响客户的信心。
5. 符合行业规范的API更容易兼容业界技术工具和合作伙伴，更容易为社区所接受。比如现在应该很难出现一个不支持POSIX标准的操作系统了，不兼容就意味着没有市场。草率设计的API会导致业务难以和外部生态协作，如果又必须合作会对内部研发资源造成压力，从而影响业务发展速度和商业竞争力。
6. OpenAPI不仅仅是API的问题，配套的服务体系必须完善。看看Linux系统上的开发，并不是有个系统调用函数就OK了，需要文档/代码示例/各种调试工具，由此还衍生许多IDE工具。在阿里云上这种全链路服务还比较薄弱，客户碰到问题要么反复提工单对公司服务资源造成很大压力，要么客户对服务不满意，用脚投票影响阿里云口碑，损害公司长期竞争力。

因此，OpenAPI不止是技术问题，也是产品问题，是产品体验的重要组成部分，需要慎重对待。

七  OpenAPI客户体验需要强大的体系支撑

那么OpenAPI的客户体验能不能被度量？阿里云开放平台刚开始发力OpenAPI时面临的最大问题是：客户和内部都有人吐槽阿里云API不好用，都是点状问题抛出和客户需求驱动，没有一个体系化的方法来衡量客户体验指标，且不能规模化解决问题。

阿里云的 OpenAPI数量1万多个，点状的、模糊的反馈对解决全局问题没有帮助，且用户其实是对具体产品有概念，但针对OpenAPI概念性却不强，调研主观偏差更大。

阿里云的OpenAPI体验是一个全链路问题，如下图：

图5 典型OpenAPI用户使用路径

长长的链路，任何一个环节没做好都有可能导致用户体验不好；而且反馈的信息也是五花八门，难以抽取有效信息。因此有几个核心问题需要依次解决：

1. 什么样的客户声音是清晰明确的？
2. 如何能够拿到这些客户声音，有哪些渠道？
3. 如何处理这些声音，如何清洗分类，如何定位根因，分析是哪个环节的问题？
4. 如何建立总体和细分量化指标，进而针对性治理，形成闭环？
5. 如何推动及运营？
6. 最终如何检验治理效果？

我们的做法是这样的：

1  Step1 量化

1. 要有具体用户问题： 能够反映客户具体问题的信息，过去主流是靠工单，但是工单反馈的用户只是冰山一角，更多的信息没有被看到。电话、钉群信息、网站反馈等内容也应该被纳入进来，这些信息加起来就是一个个具体的问题，很多问题汇集在一起就形成了很有价值的大数据集，可以给数据化治理奠定数据基础。
2. 获取数据：我们尝试联系工单系统、内部平台、钉群等渠道，需要拉通各个平台的数据。
3. 数据清洗：客户、工单数据是非结构化数据，需要自然语言处理方面的技术，阿里云开放平台与达摩院合作，通过对特定目标分类输入关键词、打标签等方式训练AI，由AI对大量的数据进行自动化抽取、归类、量化，对客户声音和根因进行较好的分类和量化。
4. 业务价值：通过根因分析得出客户主要问题分类后，针对性地优化升级产品，以问题的单位用户工单量为效果指标，来检验产品改进效果。有些问题是从趋势中发现的，需要升级产品，例如客户抱怨找不到SDK或API，我们就要优化API搜索。有些问题是已知内部问题，例如API可用性问题，就制定机制去督促业务改进。
5. 改进效果衡量：首先要有具体指标，目前主要还是工单降量。但是我们觉得还不够，因为工单只是冰山一角，数量不够多，也不够细节，流转周期也长。所以我们也尝试收口OpenAPI开发者门户，一方面标准化产品体验，另一方面直接触达终端客户拿到最详细的反馈。比如，客户的反馈能够详细到：当某个API的页码设定为0会导致功能异常、文档细节不对、必填非必填描述不对这样的精准问题。

通过上述动作，我们能够自动化分析出OpenAPI用户的主要痛点，并建立数字化趋势图去跟踪。

2  Step 2：治理

1. 有法可依：制定了《阿里云OpenAPI规范》，目前已经迭代到1.3版，涵盖设计风格、服务质量、资源规范、域名规范、文档规范等子项，在标准层面统一大家认知。
2. 执法必严：想要让规范落地只有文本不行，必须有配套的平台机制。
1. 收口阿里云所有API管理，从提升研发效率和全生命周期体系化管理的角度持续提升API管理平台的核心能力。
2. 将规范的审查规则沉淀到规则引擎中，用户在开发API的时候自动化扫描检查问题，不通过就打回。对于无法自动化约束的规范，建立审核流程和管理层审批流程，提高不合规问题的生产成本，不断提升自动化审核比例。
3. 针对API的质量进行数字化治理，通过质量分量化评估各个BU各个产品API质量，定期同步督促改进。
3. 违法必究：联合阿里云用户体验部门一起推动问题改进，并通过检查用户侧工单降量情况来验证效果。

上述能力，都沉淀在内部管理平台上，内部云产品可以一站式管理API及流程化参与API治理过程。

3  Step3 产品化

目标是收口外部用户的产品体验。以前OpenAPI的各项功能是分散割裂的，后续我们将所有与OpenAPI相关的功能集成正在一个产品中，即OpenAPI开发者门户 ，除了通过集中的产品建设提升用户体验外，还针对使用链路增加了troubleshooting、搜索、codesample等模块。

通过以上三步，我们整体OpenAPI体验治理大图如下：

图6 用户体验管理闭环示意图

通过这套体系运转中发现的问题，都会通过API管理平台和API开发者门户的功能上不断的完善，去逐步提升用户体验，从2020年的工单情况看，有比较明显的下降。

八  总结

阿里云是个庞大的分布式操作系统，OpenAPI相当于用户层操作内核层的重要通道，保障它的稳定、功能、性能、体验关系到客户的核心体验，关系到公司形象和生态拓展，也关系到内部产品质量和研发效率。接入层必须做深、做厚、做强才能让内外部客户被服务好。从团队两年的实践来看，数字化、体系化的做好基础建设才能做好OpenAPI体验。本文就云上OpenAPI的几个重要概念进行论述，希望能抛砖引玉，引起大家对OpenAPI体系价值的兴趣和关注。

参考文献：

1. https://apiacademy.co/2015/04/api-design-202-architectural-layers/
2. https://www.itread01.com/articles/1475911242.html
3. https://azure.microsoft.com/zh-cn/features/resource-graph/
4. https://maryamalshamsi98.wordpress.com/2014/05/21/linux-file-system-2/

---

存量应用快速迁移

本课程您将学习到如何快速将存量的应用迁移到云开发平台，通过几种常见的应用框架迁移的方法，让存量应用快速实现云原生架构的改造。1. Egg、Express、KOA等Node应用的迁移；2. SpringBoot、SpringMVC等Java应用迁移；3. PHP应用迁移；4. Python应用迁移；5. Midway一体化应用迁移。