Apivolve

Apivolve 是一个 API 进化工具。它帮助您保持 API 向后兼容且整洁，并生成多种语言的服务器/客户端代码。

为什么选择 Apivolve？以及 它是如何工作的？想要 编写生成器 吗？

它准备好使用了吗？

它还没有准备好使用，很抱歉。它甚至不足以用于实验性使用，很抱歉。任何帮助都欢迎！

它做什么？

进化

您不需要持续更改 API 定义文件，而是维护描述 API 变化的进化文件。

通过使用进化，Apivolve 不仅能够检查向后兼容性，而且还常常能够提供它。例如

• 将字段从数字更改为文本，并/或重命名它：Apivolve 将将具有旧字段的请求转换为新的一个，并且您的端点始终只看到最新版本。
• 将姓名字段合并为一个：Apivolve 将自动将具有旧字段的请求转换为具有单个姓名字段的新的一个，再次隐藏向后兼容性。
• 将可选字段更改为必需字段：Apivolve 将提醒您提供默认值或发布新的主要版本。

如果端点服务器使用最新的代码，则此方法效果最佳，但客户端可能使用各种过时版本。

代码生成（DRY）

您可以在一个地方定义您的 API，然后生成各种语言的服务器和客户端代码。

这与 XSD、Protobuf、JSON Schema 等模式类似...

但与它们不同，Apivolve 不仅生成最新版本的代码，还生成处理使用旧 API 的客户端所需的所有代码。

Apivolve 接受这样的观点：API 不仅仅是编码和解码，而应该清楚地记录它们需要/提供的内容。而最好的方法是包括约束在 API 中（而不是在应用程序逻辑中）。

有关创建代码生成器的更多信息，请参阅 apivolve_generator_api。

如何使用？

Apivolve 还未准备好使用，很抱歉。

设置 git 钩子

待办

显示进化

显示并检查目录 dir1 和 dir2 中的进化

apivolve -d=dir1 -d=dir2 check
apivolve -d=dir1 -d=dir2 list

您还可以使用APIVOLVE_EVOLUTION_PATH来设置目录。

生成代码

apivolve gen

创建一个进化

首先创建新文件

apivolve new

然后编辑新创建的文件。

待办

常见问题解答（FAQ）

版本号是如何确定的？

支持哪些语言？

Apivolve不受任何语言的限制，理论上可以生成任何语言的代码。然而，目前对任何语言的代码生成尚未完成。Rust可能会是第一个。

支持哪些协议？

您可以使用Apivolve与任何协议（如http、sockets、websockets、ZeroMQ、区块链等）一起使用。但您需要自己或使用其他工具来完成这部分工作。Apivolve只处理实际的消息，不处理它们的传输。

Apivolve使用哪种编码格式？

目前有两种编码

• Json用于可读的基于文本的API
• MessagePack用于紧凑的二进制API

理想情况下，每种语言都必须支持每种编码，因此编码的数量应该有限。

如果有第三种编码，它可能是一种二进制编码，它利用客户端和服务器都知道模式的事实，以实现更小的尺寸和/或更好的性能。

进化文件使用哪种语言？

它们使用Apivolve的一部分声明性语言，文件扩展名为.apiv。

Apivolve是否安全？

Apivolve被设计成能够安全地解码不受信任的消息。尽管如此，它尚未接受专业的安全分析。