今天早上共有三个topic，第一，给大家分享阿里云内部是如何通过API first和模型驱动的方式保障API的质量。第二，给大家分享我们是如何通过各种各样的工具和服务来提升在阿里云上集成API的体验和效率。最后也会给大家分享如何用阿里云的SDK实现更安全稳定的做业务集成。
今天的内容主要分为四部分：
第一部分，先看一看什么是好的API, 怎样通过API first设计出好的API；第二部分，介绍一下阿里云内部是如何通过一系列的工具和体系实现API质量保障；第三部分，简单分享一下阿里云内部API的生命周期，一个API从设计到最终发布上线要经历哪些流程，内部有哪些工具、平台辅助。第四部分，做简单的总结和展望。
一、API First：好的API是设计出来的
大家对API,肯定都不会陌生，那什么是API呢？从字面上定义API application programming interface是一个编程的界面；API就是一个文档，我们去理解它的入参、出参、错误码，把这些东西都填好，后边的内容就可以拿到了。这些说法其实都对，但都不够全面。本质上，API是一个对消费方的协议和承诺，它抽象掉了背后所有实现的细节和复杂性，明确的告诉消费方这个API能做什么、不能做什么。在此定义下，什么是一个好的API/一个好的云的API。
我列出了最重要的三大支柱：安全、稳定和效率。先看安全，阿里云上的客户都是企业级客户。对于一个企业来说，最重要的就是要保障它的安全性，所以说API的安全，它是否做了身份认证、访问控制、操作审计（即行业中说的3A）、是否做了足够充分的租购隔离，对于企业来说这是生死一线的事情，是一个红线，必须做到。和安全同样重要的支柱是稳定，企业用API和云去做集成，一定要保证业务的连续性和可用性，这时一定要保证API的兼容性和可用性，碰到流量激增要有合理的流控，能让用户做适合业务的配置。
在这两个支柱之上，第三个非常重要的评判标准是效率，效率这方面我列了很多东西，但简单概括就是把API当成一个产品来设计。它的用户就是研发，我们研发用API和阿里云集成。所以说一个好的产品需要具备的特质API都要具备，它需要一个自服务的高质量的文档，需要一个基于模型的统一设计，需要一些高质量的应用SDK。
今年的云栖大会有非常多的主题，应有成百上千个。作为一个话题的出品人，同时要管理非常多的话题，非常辛苦。如果这时有一个任务管理APP/服务，能帮助话题出品人降低很多工作压力。今天我们就以此为例，写一个任务管理的服务，需要做一些基本操作，比如任务的资产改查，然后批量搜索和拉取任务，做一些任务状态的变更，添加PPT的附件等。
我们先要明确两个概念：一是API first，另一个是Code First。先从Code First说起，相信在座的有不少是研发，对于研发来说，Code First是一个本能，和条件反射一样。我给大家描述一个典型的Code First场景，大家可以对号入座，看看是否像是自己研发中的一个正常流程。我们接到了产品的需求，要写一个任务管理的APP, PRD写出后做研发，通常的研发会做一个表结构设计， 先创建一个任务的表，把主键和各个字段都定义好，然后创建目标，做完之后，我们开始写业务逻辑。
如果用的是java，我们会用熟悉的框架，比如spring book，再结合ORM的一些框架，从数据库里做数据读写，然后定义各种各样的类、mad，做一些业务逻辑的实现。把所有实现都做完并验证通过后，最后临门一脚的事只是做一个API的透出，让后端的服务能被外部的用户用到。甚至基于用的框架，有大量业界的插件可以帮助我们，通过写一行education、一个注解的方式，把API自动化生成。整个流程甚至不需要关注什么是API，一行API的schema都不用写，整个过程就完成了。
听起来非常流畅，也符合我们日常的研发设计，那大家会问这有什么问题吗？有，而且是非常大的问题。前面说到一个好的API要具备三块最重要的特质：安全、稳定、效率。我们来看一看，通过Code First方式设计出来的API有哪些问题。
首先看左上角，我相信大家做业务逻辑的开发的时候，很少有人会认真的关注鉴权，即便是做，也不会说做到一个非常细力度，比如资源级别的鉴权。如果我们把业务的逻辑都写完了，甚至API都已经通过便捷的方式暴露了，这时发现鉴权是缺失的，一方面会给业务带来巨大的安全风险；另一方面如果要补鉴权、做一些权限的改造可能会有大量的返工。
第二，这个任务需求是要做一个任务管理系统，我们要定一个list task， 大家做实现时，起初不会碰到大量的数据，所以大家可能不太会关注分页，写测试时也不会往里扔成百上千上万条的数据，一般第一版写的东西是把所有数据无脑往外扔的方式。随着业务上线，逐渐变得越来越成功，越来越多的用户使用，数据量越来越大。
我们内部有上万条/几十万条数据，如果每次list都是全量拉取，前端可能受不了，无法handle这么多数据。这时才想到去补分页。第三个问题，这也是软件工程业界的一个笑话——软件工程最大的两个难题，一是缓存的失效，二是命名。它比较真实的反映命名对于研发来说是一个非常痛苦的事情，需要花很多精力。但是相信大家在日常写代码中再关注命名的标准性、 各种参数方法命名的一致性，也不会全身心投入，保证每一个方法、参数命名都是一致的。
所以，通过Code First暴露的API体现的是code命名。如果维护的API数量较少，比如三、五个，完全可以通过检查一遍保证一致性。像阿里云这种有两万多个开放的API、几百个云产品、这么多的团队互相协作，很难保证全局性命名的一致性，看到的就是千奇百怪的命名方法。大家可能会问了，前面提了这么多问题，像写代码、研发一样，有bug是=自然的，修就完了，殊不知这才是一个噩梦的开始。
前面提到API的本质是对消费方的协议和承诺。刚才所有的场景缺少鉴权及补鉴权、补分页、改命名，本质上都是非兼容变更。大家可以想一下，原来没有鉴权的，加了鉴权，之前调用的人基本就不是kitchen去了；原来没做分页，加了分页，原调用方拿不到全量数据，可能都不感知；改命名更不用说了。如果以API是一个协议的方式/视角去看，这些操作都是在撕毁这个协议。虽然Code First非常爽，是一个研发的本能，但是一个好的API一定是设计出来的，一定要通过API first的方式才能从第一天/第零天就保证API是高质量的，不会到后面反悔，撕毁这个协议。
我再多补充一点，我们说的API first一定是一个模型驱动的API first。希望这张图能给大家形象的描述这件事情。如果只是单独的定义API,就像这个图一样， API是一大堆游离的分子，虽然API背后也是我们的计算存储网络、各种各样的云产品，但是从用户的角度来讲，从这些杂乱无章的API中很难看出背后的产品和结构以及这些API间的关联。
模型驱动就是要先把背后的资源定义出来，像中间的这个图一样，围绕资源再来定义标准化的API。对于一个资源来说，它的生命周期从创建到删除就是标准化的5个API：C、R、U、D、L。我们用统一的方式命名，C就是create，它不叫start、 不叫instances、不叫whatever,我们用一个标准化命名定义它。对于用户来说，它的好处就是大大降低了理解成本，能够一目了然的看出背后的模型结构、资源关系；还有一个好处是通过API会定义各种各样上层工具，像IaC工具，比如terraform、ROS, cloud control API等，这些工具底层都有一套清晰的资源模型定义。
二、CloudSpec：阿里云的统一API模型设计语言
第一部分简单给讲了好的API是什么样的，为什么需要用API的方式设计，第二部分给大家来看一下阿里云内部是怎么样通过体系化方式保障API的质量。先给大家看一个整个阿里云API模型驱动的体系的大图。阿里云API是围绕底层的一套模型为核心，提供从原子化到编排的上层分层工具。从API到多语言的SDK, 再到上面的IaC工具，都是这样一套体系。
第一部分花了大量的篇幅介绍为什么要API first, API first有那么多的好处，但果只是停留到口头是没法落地的，我们必须要提供一套和API first理念匹配的工具。为此我们在阿里云内部是设计了一套全新的、我们叫做CloudSpec IDL interface definition language的语言来帮助内部云产品用统一标准化的方式定义API和模型。左边是代码示例，这是我云栖大会前手写的一个示例，完全用CloudSpec标准语法，所以大家可以看到，主要有三个主要组成部分，第一部分是服务类型， 即service，我是一个任务服务，那资源任务这个资源，operation对应API ，比如CRUDL, 还有error，下一页可以看到错误也可以是标准类型。
第二部分是数据类型，比如最基本的string 、number, 还有的复合类型，比如array 、map等。第三部分是很重要的组成部分——注解annotation，后面一页会给大家详细讲解。这时可能大家又会疑惑怎么又搞一套语言？ API的定义在业界是几十年不新鲜的事，而且业界有它的实施标准OAS、Smart的那套，为什么我们还要另起炉灶再做一套？这有两个最重要的理由：
第一， API first和Code first怎么选，不只是要强行掰里面，还需让大家在编程的体验上能够和API first达到一样高效优质的体验。OAS最大的问题是它更偏重于机器消费的格式，对于我们编程、手动去写、去理解来说，非常不友好。我们内部也做过一些原型和调研，我们把同样的API用CloudSpec IDL语言重写，行数上能减少至少50%以上。
第二，我们需要形成一个模型驱动的心智，通过CloudSpec IDL语言，把资源的模型放到第一位，从编程的心智上保证模型的设计先行，因为如果不定义resource资源是无法编译的。
这块再给大家多看几个语言的一些示例，这里补充了创建任务和列举任务Operation的定义，包括前面说的注解和错误都给了一些例子。通过可复用的结构和注解最大程度保障了前面定义的安全、稳定、效率的各种各样的最佳实践可复用，且在语言内部内置。
举个例子，比如左下角的这个错误，Environment task error这个任务错误了，任何会涉及到产出错误任务的API Operation，都可复用这个结构，不会造成定义了10个API, 有十个不同的错误码，但其实是同一个真实的错误。右上角是at pagination的分页的annotation，这个语法结构里的一个注解。前面第一个例子里提到，分页往往是大家最后才会想到的事情，我们要做到的让大家在设计API的第一天就能直接通过很简单的语法把分页一次性做对，无需担心我到底是用next token还是page number的方式实现。到底这个玩意儿叫token还是string，还是叫whatever，从语法的结构、框架保证了我们的最佳实践可以落地。
不以规矩，无以方圆。前面提到我们通过CloudSpec IDL让大家能够高效定义模型，但是如果不匹配相应规范，那它其实是不完备的。所以我们在设计这一套CloudSpec IDL时的第一天，就内置了非常多的API的规范校验语法，能够让我们写API像写代码一样，随时随地的享受类似于link的前置校验和实时校验能力。
这里截取了一个真实例子。我们内部围绕着这一套IDL是提供了大量的编程工具。我们提供了一个CRI, 这里输入false back check, 把文件放入，这是我前面定义的文件，它会透出所有不满足定义规范的场景。这里我截取了两个典型的，对于创建任务的API来说，没做鉴权，违反了安全支柱，扫描出来了。对于list task,虽然定义了分页，但没有定义skip字段允许用户去跳过中间若干个item，违反了效率的规范，也被扫描出来。
再回到开头的第一张图，回顾一下好的API需要的规范。我们开头讲到API需要在稳定、安全、效率各个方面都做好，才是一个好的API。听到这里相信大家对这个理念多少是有一些认同的，为从根本上解决人为理解各种各样的规范，人为理解到底什么是安全，什么是稳定所带来的成本，我们内部把所有的API的最佳实践和规范都变成了文本上清晰的规范定义，并把大部分文本定义都通过程序化的方式实现到了CloudSpec IDL语言。
就是前面展示的那一页，我们可以通过一个简单的CLL命令把所有不合规的事情程序化的检验出来。一方面把API的校校验前置化，大大提升了效率。另一方面也可以让我们在第一天/第零天就能达成一个标准的API设计。简单的来说就是我们把API设计规范这一件本来是人治的事情，变成了一件法治的事情。至今，我们内部也沉淀了八百多个规范，并且还在不断迭代更新，希望更全面的保障API的质量，这些规范也形成了阿里云API质量的内核。
前面说了这么多，最终还是希望能够打造高质量的API, 提供高质量的API工具。阿里云API的工具体系说简单点就是围绕着两个核心去建设的——标准化、自动化。标准化就是我们前面说的CloudSpec IDL体系，通过一个标准化模型定义高质量的API，把各种各样的不规范的东西前置校验。当我们产出高质量、标准化定义的API和定义之后，希望能够从这个上面直接自动化生成各种各样的下游的工具链，比如常用的多语言SDK,如果用IAC，terraform provider很大一部分也是通过原数据自动化生成的，包括code control API都是根据底层的统一资源模型生成的。自动化生成一方面可以避免人肉编写带来的低效问题，另一方面也可以通过这样的方式保证不同的语言、不同的云产品、不同的API之间的一致性。最中间的是各种各样的CloudSpec IDL的语言内核，比如 SDK多语言代码生成器，这已经是开源，大家如果去有兴趣可以去搜，还有编排内核等一系列的工具和体系构成了我们内部的技术支撑和保障。
三、APILifecycle：阿里云的API生命周期
前面介绍了CloudSpec IDL怎么从模型的层面和语法层面保障API质量，第三部分我简单给大家串一下一个API在阿里云内部从设计到最后的上线的完整生命周期。
这张图基本简单的概括了一个API在阿里云内部从诞生到发布上线，到最终下线的过程。首先从左上角开始做为起点，我们要做API和模型化设计，这个过程中不断用前面说的link校验API是否符合定义，不符合的打回重新设计。
通过了规范校验之后，接下来一步也就是中间第三个，进入企业级能力的接入，就是一个好的API需要具备安全、稳定、效率的这三大支柱所需要具备的各种能力在这个环节都需要让API接入、验证，比如身份认证、访问控制、资源管理等一系列。接入之后，我们还会做一些校验。再接下来会进入大量的测试。比如最基本的是ApI的业务逻辑的测试，然后是企业级能力的测试，比如权限测试、租户隔离测试、资源的测试等等，只有符合了测试的API, 才能够进入下一环节——工具链的生成。
我们根据标准化定义的API原数据生成API文档，对于SDK 、terraform provider等，这个过程中我们还会做一些校验，如果有问题，还是打回到设计阶段，最终才到发布上线。发布上线前还会再做一次兼容性的检查，确保API层面没有非兼容性的变更。然后做灰度、上线，各个工具链的发布，比如SDK的同发terraform的版本的升级和发布等。这是我们内部API生命周期的主要流程。我们内部也通过一个统一的API管理平台把整个流程都串起来，并且基本上对内部的管控API做了收口。
这是我们阿里云开发者工具的大图，相信大家前两天在我们的展馆或听自动化场次也都看到过，正是有了内部API的质量保障体系，在此基础上，才生长出了丰富的API的供给链，今天这个专场，我们会聚焦在黄色区域，就是API和我API相关的开发者工具。
四、What Next：总结与展望
最后部分简单的总结和展望一下未来。
今天我们花了一些时间给大家介绍了什么是一个好的云的API， 为什么好的API一定要通过API first的方式设计出来；第二部分也给大家看了阿里云内部是怎么通过工具化和体系化的方式搭建CloudSpec IDL保障设计时API就是高质量的；第三部分给大家看了一下API在阿里云内部的完整生命周期。最后展望一下未来。
从2009年阿里云正式成立到两年后2011年第一款对外的OSSAPI发布到今天已有15年了。过去快速的发展，带来了非常多的创新。但同时也在API方面留下了一些历史的债务。我们现在不断的意识到了过去在API的方面走过的一些弯路，把这件事情重视起来，不断的在内部对存量API治理、对新增的API做质量安全、稳定、效率的强卡口。在2022年，我们推出了一款叫做cloud control API的产品。这款API完全以资源的方式定义，强化标准资源的一个重要性。
2023年我们内部做了全面的API质量保障体系的升级，就是我们前面讲的一系列体系，我们从规范、从定义API的语言模型，从API管理和发布平台全方位保障API质量。未来我们还希望在内部把CloudSpec IDL更多的打磨之后，希望能够开源，和社区共建，大家一起建设更好的API。重点问题还是要两头抓，虽然我们内部不断的在提升API的质量，通过各种各样的体系去保障、做提升。但同时我们对客还是需要提供各种各样丰富的工具、平台和服务，让大家更高效的集成阿里云API。接下来我的同事会给大家深入讲解如何通过API门户、新发布的AI助手和我们的ID插件来共同打造一个沉浸式的API集成体验，大家敬请期待。我的分享就到这里，谢谢大家。
