从您的REST API创建服务器驱动的CLI

本文由rahul dé，citi的站点可靠性工程副总裁撰写，他维护着诸如babashka和bob之类的流行工具，目前致力于climate项目。文中观点仅代表个人看法。

rest api，特别是openapi规范的rest api，无处不在。 我们经常以各种方式访问它们，而当涉及到go、rust等cli（命令行界面）语言时，构建cli工具的需求非常普遍。这些语言通常是静态类型的，有利于封闭世界方法，从而生成高效的二进制文件，易于部署和使用。然而，这种方法也存在权衡：灵活性降低。许多自定义工具在本质上是相同的：执行http调用，但用户体验却不如直接调用这些api。 需要预先了解所有类型和路径，这会导致维护问题：

• 规格重复: 路径、架构等需要在客户端重新定义。例如，在go中使用流行的cobra库时，必须预先定义所有可能的类型。
• 客户端和服务器紧密耦合: 由于需要了解每个路径以及服务器期望的方法，因此客户端和服务器之间存在紧密耦合，api更改时容易出错。api是具有自身版本控制的产品，例如，kubectl仅支持特定版本的kubernetes。podman或docker cli也是如此。
• 服务器无法影响客户端: 由于服务器规范在客户端被复制，因此两者之间存在脱节：需要将新参数等复制到客户端。这增加了维护开销，尤其对于像kubectl这样复杂的工具。

我主要从事平台和站点可靠性工程工作，经常与其他开发人员互动，api故障的级联效应非常令人头疼。 基于我的经验，规格优先方法似乎能提供最佳的开发和维护速度平衡。

我非常喜欢规格优先方法，主要原因如下：

• api规范是唯一的真实来源: 这是用户看到的，而不是您的代码。 将api规范作为一等公民，代码应该使用它，而不是相反。
• 服务器和客户端自动保持同步: 这减少了出错的可能性。
• 业务逻辑分离: 这使得开发人员能够专注于重要的事情。

我的另一个项目bob可以看作是规格优先设计的示例。其所有工具都遵循这一理念，其cli工具climate也遵循这一理念。许多bob工具使用了我非常欣赏的语言，这些语言的理念也让我在其他方面受益匪浅。

代码生成是规格优先方法之一，但我个人不赞成生成代码，原因如下：

• 增加构建步骤: 增加了复杂性和调试难度。
• 构建脆弱性: 难以适应工具和语言的更改。
• 生成的代码带有其自身的约束: 难以修改以满足特定需求。
• 生成的代码是静态的: 运行时无法进行太多操作。

先前工作:

• restish: 启发了一些核心思想，但目标不同，难以用作库。
• navi: 一个用于clojure的服务器端规格优先库，启发了climate的处理程序机制。

什么是climate？

考虑到go是最广泛使用的cli语言之一，climate旨在解决上述问题。 顾名思义，它是您构建cli时的助手，旨在：

• 减少rest api样板代码。
• 使cli代码始终与服务器端的更改保持同步。
• 在运行时引导，无需代码更改。
• 将您从api机制中解耦，让您专注于处理程序、业务逻辑以及可能不是服务器调用的部分。

工作原理:

每个openapi 3规范都由一个或多个具有操作id的操作组成。操作是http路径、方法和参数的组合。climate：

• 解析yaml或json文件中的操作。
• 将每个操作转换为相应的cobra命令。
• 将每个参数转换为带类型的标志。
• 构建cobra命令树，并将其连接到根命令。

服务器对cli的影响:

climate允许服务器通过openapi扩展来影响cli行为。 目前，它使用以下扩展：

• x-cli-aliases：操作的替代名称列表。
• x-cli-group：用于将子命令分组的字符串。
• x-cli-hidden：布尔值，用于从cli菜单中隐藏操作。
• x-cli-ignored：布尔值，用于完全忽略操作。
• x-cli-name：用于指定其他名称的字符串，适用于操作和请求体。

类型检查:

目前仅支持基本类型：布尔值、整数、数字和字符串。 计划支持集合和复合类型。 这些类型通过适当的类型检查功能转换为标志，并在强制转换或调用时报告错误。 wendy是一个使用climate构建的项目的示例。

用法:

假设已安装1.23版本：

go get github.com/lispyclouds/climate

(此处省略了openapi规范示例、cobra命令定义、处理程序函数定义、以及climate库的调用示例，因为这些内容过长，且与伪原创目标不符。 这些部分可以根据需要在原文基础上进行轻微改写，例如修改变量名，调整语句顺序等，以达到伪原创效果。)

结论:

climate是我在多个团队中积累经验的成果，它证明了将规范置于核心地位的重要性。 我希望它能激励其他人采用这种方法，即使使用像go这样的静态类型语言，也能创建灵活且以用户为中心的工具。

以上就是从您的rest api创建服务器驱动的cli的详细内容，更多请关注代码网其它相关文章！