从您的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的详细内容，更多请关注骃骐网【www.myinqi.com】。