versioning - Thrift 文件 (api) 版本控制的最佳实践是什么？

Question

我有一个用 thrift 编写的 API。例子:

service Api {
  void invoke()
}

它做了一些事情。我想改变行为以做其他事情，但仍然为期望旧行为的客户保留旧行为。

处理新 API 版本的最佳实践是什么？

Answer 1

软版本控制

Thrift 支持软版本控制，因此执行如下所示的服务版本 2 是完全有效的:

service Api {
   void invoke(1: string optional_arg1, 2: i32 optional_arg2) throws (1: MyError e)
   i32 number_of_invokes()
}

由于新添加的参数在技术上是可选的，任意客户端请求可能包含也可能不包含它们，或者可能只包含它们的一部分(例如指定 arg1 但不指定 arg2 )。异常有点不同，旧客户端会引发某种通用的意外异常或类似的异常。

甚至可以完全删除过时的函数，在这种情况下，旧客户端在尝试调用(现在不存在的)已删除函数时会遇到异常。

对于将成员字段添加到结构、异常等，上述所有内容同样适用。建议不要从 IDL 文件中删除声明，而是建议到 注释掉 旧删除的成员字段和函数，以防止人们在更高版本中重新使用旧字段 ID、旧函数名称或旧枚举值。

struct foobar {
  // API 1.0 fields
  1: i32 foo
  //2: i32 bar   - obsolete with API 2.0

  // API 2.0 fields
  3: i32 baz
}

required是永远

您需要小心使用关键字 required .一旦你发布了一个包含 required 的结构体的 API成员，您将需要携带这个直到整个结构被拆除。添加新的 required 也是如此字段稍后。否则你可能会破坏更改，因为混合新旧客户端和服务器迟早会产生一种情况，即一端绝对期望某个 required member 字段，但对端无法交付，只是因为它对此一无所知。

这不是正常或 optional的问题字段，因为 Thrift 旨在跳过未知字段(类型 ID 包含在连线数据中)，并且仅忽略丢失的字段。相比之下，对 required 应用了额外的检查。字段以确保它们存在于线数据中。

端点

虽然软版本控制是一个很好的工具，但它的代价是由于需要兼容而增加了负担。此外，在某些情况下，您的 API 会进行重大更改，故意不向后兼容。在这种情况下，建议在不同的端点设置新服务。

或者， multiplex protocol Thrift 0.9.2 引入的可用于在同一端点(即套接字、http URI 等)上提供多个服务和/或服务版本