我有一个 Java 项目,它使用 Jersey + Grizzly HTTP Server 作为 REST 服务器。我使用的版本策略是在响应中添加“server-api-version” header ,并要求客户端在请求中添加“accept-api-version” header 。
基于这个实现,我想提供两个级别的版本检查:
- 如果请求“accept-api-version”的主要版本低于服务器 API 版本的主要版本,则拒绝该请求。
- 接受请求,但警告客户端“如果请求“accept-api-version”的次要版本小于服务器 API 版本的次要版本,“我们将在 X 个月内停止支持您使用的 REST API 版本”。
我通过实现 javax.ws.rs.container.ContainerRequestFilter 实现了版本检查 1。但是如何实现版本检查2正常响应并附加一个容易被客户端注意到的警告呢?
最佳答案
对于检查 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。这让客户注意到弃用,也为他们提供了短期紧急缓解措施。
只有当客户来源在您的控制之下时,这种困难的方法才最适合内部团队。
确保通过警告、控制台消息以及邮件等提前传达弃用信息。
关于java - 如何响应 REST API 版本不匹配的警告?,我们在Stack Overflow上找到一个类似的问题: https://stackoverflow.com/questions/39008289/