Question

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

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

如果来自请求'accept-api-version'的主要版本低于服务器API版本的主要版本，则拒绝该请求。
接受请求但警告客户“如果来自请求'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)，您的客户端也有一个平面的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（在int中为211），并且您想要弃用以前的版本2.0.0（200）。然后使用2.0.0的客户端将开始获取DeprecatedException

这对此有何帮助？

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

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

确保通过警告和控制台消息以及邮寄等提前通知弃用。

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

1 个答案: