API 工具链研发的理论基础 - 导读

前言

三年前，我因为一个偶然间的选择，从市场上大热的数据平台工作岗位，一头扎进了工具链产品研发的领域，成为了一名光荣的「工具人」。

在这三年的时间里，我辗转负责了 SDK、资源编排、数仓、制品交付平台等多个形态各异，纷繁复杂的产品，这些产品有一个共同的特点，就是为工具类产品的研发提供支持。

最初的一年，我十分迷茫，虽然工作地十分努力，但是「工具人」仿佛是个魔咒，「低技术含量」，「前路受限」，这些刻板印象不仅仅是外界对我们的标签，甚至一度连我自己也是这样认为的。主流的评价体系与我们相去甚远，仿佛抬头就能够摸到这个领域的天花板。

这两年我几乎每天都会抽时间阅读相关领域文章和技术趋势，慢慢地，我的观点发生了转变。

一部分原因是因为国内外相关的组织和企业，如 CNCF、Hashicorp 等的飞速发展，使得整个大环境变好，越来越多的人意识到工具的重要性，认同工具在基础设施领域的关键地位与商业价值。

另一部分原因是随着认识的加深，我开始逐渐意识到这个研发领域的复杂性，并且逐渐从最初的兴趣转向热爱，具备了一定的社会责任感，希望针对这个行业的评价体系更加多元化，并愿意贡献自己的一份力量。

摘要

这一系列文章，我将从一个虚构的主人公「小欧」出发，抛砖引玉，来谈一谈我眼中 API 工具链研发这个领域的模样。

API 工具链的主要职责，是使用户通过企业的开放平台 API，来管理和操作企业对外出售的产品实例。

比较典型的应用有三类：

• SDK / CLI（企业对外提供的开发者工具集）

• 第三方工具集成（如为 Terraform、Packer、Pulumi、Spinnaker 等开源工具贡献插件）

• 工具类 SaaS 应用（如云上编辑器、调试器、流程编排器等等）

API 工具链产品作为工具链研发体系中的一个断面，见微知著，可以从一个局部，间接地观察到这个体系从 0 到 1 的构建过程。

我们的主人公「小欧」，在文章中将面临重重困难，通过科学的方法和软件工程理论，逐一地去发现和攻克这些问题领域。同时也会面临一些挫折，通过反思与转变之后获得了最终的成功。

采用虚构主人公的原因有几点：

一是文中的一部分技术，例如基于 OPA 的准入控制、和基于 DSL 控制流图的制品生成，目前只是一个大胆的设想，并写了一些代码验证了可行性，但目前并没有机会真正落地实践。

二是我希望这一系列文章，能够从中立的角度，起到抛砖引玉的作用，引发一些在这个领域中基础理论的探讨，虚构主人公可以避免与现实相结合，引起不必要的猜想。我将在文中隐去具体的项目或组织名字，将提及的工具和技术统一放到每篇文章的参考文献中，欢迎大家自行探索。

当然作为一个虚构的故事，文章将采用一种对称的写作手法：

• 前半部分会专注于介绍 API 工具链产品研发面临的核心问题，以及相对应的技术解决方案。

• 后半部分则会介绍一些软件工程理论基础，它们将作为我们实践的指导原则，贯穿于技术研发路线之中，使我们在迷茫时，不至于丢失方向。

大纲

首先技术的角度来介绍 API 工具研发的一些问题领域，从简单到困难，依次包括：

• API 描述能力

- API 模型设计的流派

- 扫描器与代码生成器

• API 契约化

- 契约测试

- 准入控制与 OPA

• 制品建模

- 持续集成与交付

- DSL：SDK 与资源管理工具的建模

• 基础设施

- 数据管理与 GitOps

- 流程编排与事件总线

这四类问题就像立体结构的四个面，对于一个企业或组织来说，可能会同时观察到其中的一个或几个问题，而其他的问题则隐藏在冰山之下，在组织发展的不同阶段一一浮出水面。

这里我们将不再介绍与企业基础架构相关的内容，例如 API 鉴权、API 网关、交付流程等等，这些内容与企业具体的基础设施绑定，不属于本文提及的基础知识范畴。

在技术的探索之外，我们的主人公小欧还将对攻克问题的经历进行深刻的反思，和大家一起看到，这些经典的软件工程理论，如何对工具链产品的技术路线产生深刻的影响，它们包括：

• SOLID 原则

• 运动式的改造不可行

• 数据流向与土地所有权理论

• 团队实验

• 北极星指标

在实际的技术实践中，对于这些理论的思考应该是伴随着技术的演进而一同发生的，而在我们的故事里，将借小欧之口，在文章的下半篇里集中阐明，帮助大家更深刻地体会到这些理论基础的价值和意义。

致谢

在三年的“工具人”生涯中，对我影响最大的是一位前同事，他对于工具产品的热爱深深地感染了我，我读完了他推荐的所有资料与书籍。他对我数年如一日的鼓励，对于我这样比较内向，甚至有点轻微社恐的技术人来说，有着非常深远的正面影响。

我不清楚目前国内有多少人在从事相关方面的工作，但如果因缘巧合你看到了这篇文章，那么我的同行们，我希望你可以知道，你是不孤单的，你是最棒的！你从事的是一个伟大的，充满爱的事业，它将会成为一块行业基础设施领域的基石，在将来大放异彩！

赠人玫瑰，手有余香，如果这一系列文章，能够有幸地鼓舞到一些正在处于迷茫期的同行者，希望你在工作中，也能把这一份温暖继续传承下去。

出发

那么，让我们和小欧一起，开始这一次伟大的历险吧！