如何响应 REST API 版本不匹配的警告？

Question

我有一个 Java 项目，它使用 Jersey + Grizzly HTTP Server 作为 REST 服务器。我使用的版本策略是在响应中放入标头“server-api-version”，并要求客户端在请求中放入标头“accept-api-version”。

基于这个实现，我想提供两个级别的版本检查：

1. 如果请求“accept-api-version”的主要版本低于服务器 API 版本的主要版本，则拒绝请求。
2. 如果请求“accept-api-version”的次要版本低于服务器 API 版本的次要版本，则接受请求，但警告客户端“我们将停止支持您在 X 个月内使用的 REST API 版本”。

我通过实现 javax.ws.rs.container.ContainerRequestFilter 实现了版本检查 1。但是，如何实现版本检查 2 以正常响应并带有易于被客户端注意到的额外警告？

Answer 1

对于检查 2，这取决于您的客户端的使用方式或位置。这也取决于客户端代码是否在您的控制之下

如果你的客户是

• 一个 java 库，然后添加已弃用的警告日志。
• 运行的 js 库是浏览器，然后控制台警告/错误可能会有所帮助，但大多数情况下会被忽视。
• 任何其他语言 - 使用各自的警告或弃用系统。
• 如果它是带有 UI 的企业应用程序，那么在 UI 上显示错误消息也可以引起正确的注意。对于非企业客户而言，UI 上的应用程序错误无济于事，因为普通用户大部分时间都无能为力。

另一种艰难的方式（这在面向客户的案例中可能无法接受）

如果客户端源在您的控制范围内，那么您可以在实际从服务器中删除之前中断对旧版本 api 的调用。让我解释一下我的意思。

现在你的客户端有一个调用函数getData(params: ParamType)，你的客户端也有一个平面设置函数useDeprecated(value: Boolean)

您在客户端中的getData(params: ParamType) 检查客户端是否可以调用已弃用的 API，如果不允许客户端，则抛出错误。

interface Client {

  //Clients extend this interface

  void useDeprecated(boolean deprecated);

  default boolean isDeprecated(int serverVersion, int clientVersion) {
    // you can string for representing versions as well.
    // complicated logic of deprecation here
    return result;
  }

  boolean isAllowedToUseDeprecated();

  default Object getData() {
    if(isDeprecated(serverVersion, clientVersion)) {
      if(isAllowedToUseDeprecated()) {
        return getDataFromServer();
      } else {
        throw new DeprecatedException(expectedVersion, actualVersion, message);
      }
    } else {
      return getDataFromServer();
    }

  }

  Object getDataFromServer(); //Clients implement this
}

假设您当前的版本是 2.1.1（int 中的 211），并且您想弃用以前的版本 2.0.0 (200)。然后使用 2.0.0 的客户端将开始收到DeprecatedException

这有什么帮助？

当 API 被弃用时，客户端将开始收到 DeprecatedException 并且他们的调用将失败，但他们可以应用 useDeprecated(value: Boolean) 来设置标志并继续使用弃用的 API。这让客户注意到了弃用，也为他们提供了短期的紧急缓解。

这种硬方法最适合内部团队，并且只有在您可以控制客户来源的情况下。

确保通过警告和控制台消息以及邮件等方式提前传达弃用。