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

Question

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

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

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 上显示错误消息也可以获得正确的关注。对于面向非企业客户的应用程序，用户界面上的错误无济于事，因为普通用户大多无法执行任何操作。

另一种困难的方式(这在面向客户的情况下可能 Not Acceptable )

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

现在您的客户端有一个调用函数 getData(params: ParamType)，您的客户端也有一个平面 setter 函数 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(整数为 211)，并且您想要弃用以前的版本 2.0.0(200)。然后使用 2.0.0 的客户端将开始收到 DeprecatedException

这有什么帮助？

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

只有当客户来源在您的控制之下时，这种困难的方法才最适合内部团队。

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