如何使用 spring 管理 REST API 版本控制？

Question

我一直在寻找如何使用 Spring 3.2.x 管理 REST API 版本，但我没有找到任何易于维护的东西。我将首先解释我遇到的问题，然后是解决方案……但我想知道我是否在这里重新发明了轮子。

我想根据 Accept 标头管理版本，例如，如果请求具有 Accept 标头 application/vnd.company.app-1.1+json，我希望 spring MVC 将其转发给处理此版本的方法。而且由于并非 API 中的所有方法都在同一个版本中更改，因此我不想转到每个控制器并更改版本之间未更改的处理程序的任何内容。我也不希望有逻辑来确定在控制器本身中使用哪个版本（使用服务定位器），因为 Spring 已经在发现要调用的方法。

因此采用了 1.0 到 1.8 版本的 API，其中处理程序在 1.0 版本中引入并在 v1.7 中进行了修改，我想通过以下方式处理这个问题。想象一下代码在控制器内部，并且有一些代码能够从标头中提取版本。 （以下在Spring中无效）

@RequestMapping(...)
@VersionRange(1.0,1.6)
@ResponseBody
public Object method1() {
   // so something
   return object;
}

@RequestMapping(...) //same Request mapping annotation
@VersionRange(1.7)
@ResponseBody
public Object method2() {
   // so something
   return object;
}

这在 spring 中是不可能的，因为这 2 个方法具有相同的 RequestMapping 注释并且 Spring 无法加载。这个想法是VersionRange 注释可以定义一个开放或封闭的版本范围。第一种方法从 1.0 到 1.6 版本有效，而第二种方法适用于 1.7 及以上版本（包括最新版本 1.8）。我知道如果有人决定通过 99.99 版，这种方法就会失效，但我可以接受。

现在，如果不认真修改 spring 的工作原理，上述内容是不可能的，我正在考虑修改处理程序与请求匹配的方式，特别是编写我自己的ProducesRequestCondition，并在其中包含版本范围.例如

代码：

@RequestMapping(..., produces = "application/vnd.company.app-[1.0-1.6]+json)
@ResponseBody
public Object method1() {
   // so something
   return object;
}

@RequestMapping(..., produces = "application/vnd.company.app-[1.7-]+json)
@ResponseBody
public Object method2() {
   // so something
   return object;
}

通过这种方式，我可以在注释的产生部分定义封闭或开放的版本范围。我现在正在研究这个解决方案，问题是我仍然需要替换一些我不喜欢的核心 Spring MVC 类（RequestMappingInfoHandlerMapping、RequestMappingHandlerMapping 和 RequestMappingInfo），因为这意味着无论何时都需要额外的工作我决定升级到更新版本的 spring。

如果有任何想法，我将不胜感激……尤其是任何以更简单、更易于维护的方式执行此操作的建议。

---

编辑

添加赏金。要获得赏金，请回答上面的问题，而不建议在控制器本身中使用此逻辑。 Spring 已经有很多逻辑可以选择调用哪个控制器方法，我想捎带它。

---

编辑 2

我在 github 上分享了原始 POC（有一些改进）：https://github.com/augusto/restVersioning

Answer 1

无论是否可以通过向后兼容的更改来避免版本控制（当您受某些公司准则的约束或您的 API 客户端以错误的方式实现并且即使不应该这样做也会中断）时，这可能并不总是可行）抽象的要求很有趣：

如何进行自定义请求映射，对请求中的标头值进行任意评估，而不在方法主体中进行评估？

正如this SO answer 中所述，您实际上可以拥有相同的@RequestMapping 并使用不同的注释来区分运行时发生的实际路由。为此，您必须：

1. 创建一个新注解VersionRange。
2. 实现RequestCondition<VersionRange>。由于您将拥有类似最佳匹配算法的东西，因此您必须检查使用其他 VersionRange 值注释的方法是否为当前请求提供了更好的匹配。
3. 根据注解和请求条件实现VersionRangeRequestMappingHandlerMapping（如post How to implement @RequestMapping custom properties 中所述）。
4. 配置 spring 以在使用默认 RequestMappingHandlerMapping 之前评估您的 VersionRangeRequestMappingHandlerMapping（例如，通过将其顺序设置为 0）。

这不需要对 Spring 组件进行任何 hacky 替换，而是使用 Spring 配置和扩展机制，因此即使您更新 Spring 版本（只要新版本支持这些机制），它也应该可以工作。

Answer 2

我刚刚创建了一个自定义解决方案。我在@Controller 类中结合使用@ApiVersion 注释和@RequestMapping 注释。

示例：

@Controller
@RequestMapping("x")
@ApiVersion(1)
class MyController {

    @RequestMapping("a")
    void a() {}         // maps to /v1/x/a

    @RequestMapping("b")
    @ApiVersion(2)
    void b() {}         // maps to /v2/x/b

    @RequestMapping("c")
    @ApiVersion({1,3})
    void c() {}         // maps to /v1/x/c
                        //  and to /v3/x/c

}

实施：

ApiVersion.java 注释：

@Target({ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface ApiVersion {
    int[] value();
}

ApiVersionRequestMappingHandlerMapping.java（这主要是从RequestMappingHandlerMapping复制和粘贴）：

public class ApiVersionRequestMappingHandlerMapping extends RequestMappingHandlerMapping {

    private final String prefix;

    public ApiVersionRequestMappingHandlerMapping(String prefix) {
        this.prefix = prefix;
    }

    @Override
    protected RequestMappingInfo getMappingForMethod(Method method, Class<?> handlerType) {
        RequestMappingInfo info = super.getMappingForMethod(method, handlerType);
        if(info == null) return null;

        ApiVersion methodAnnotation = AnnotationUtils.findAnnotation(method, ApiVersion.class);
        if(methodAnnotation != null) {
            RequestCondition<?> methodCondition = getCustomMethodCondition(method);
            // Concatenate our ApiVersion with the usual request mapping
            info = createApiVersionInfo(methodAnnotation, methodCondition).combine(info);
        } else {
            ApiVersion typeAnnotation = AnnotationUtils.findAnnotation(handlerType, ApiVersion.class);
            if(typeAnnotation != null) {
                RequestCondition<?> typeCondition = getCustomTypeCondition(handlerType);
                // Concatenate our ApiVersion with the usual request mapping
                info = createApiVersionInfo(typeAnnotation, typeCondition).combine(info);
            }
        }

        return info;
    }

    private RequestMappingInfo createApiVersionInfo(ApiVersion annotation, RequestCondition<?> customCondition) {
        int[] values = annotation.value();
        String[] patterns = new String[values.length];
        for(int i=0; i<values.length; i++) {
            // Build the URL prefix
            patterns[i] = prefix+values[i]; 
        }

        return new RequestMappingInfo(
                new PatternsRequestCondition(patterns, getUrlPathHelper(), getPathMatcher(), useSuffixPatternMatch(), useTrailingSlashMatch(), getFileExtensions()),
                new RequestMethodsRequestCondition(),
                new ParamsRequestCondition(),
                new HeadersRequestCondition(),
                new ConsumesRequestCondition(),
                new ProducesRequestCondition(),
                customCondition);
    }

}

注入WebMvcConfigurationSupport：

public class WebMvcConfig extends WebMvcConfigurationSupport {
    @Override
    public RequestMappingHandlerMapping requestMappingHandlerMapping() {
        return new ApiVersionRequestMappingHandlerMapping("v");
    }
}

Answer 3

我仍然建议使用 URL 进行版本控制，因为在 URL 中，@RequestMapping 支持模式和路径参数，可以使用 regexp 指定格式。

为了处理客户端升级（您在评论中提到），您可以使用“latest”之类的别名。或者有使用最新版本的未版本化 api（是的）。

同样使用路径参数，您可以实现任何复杂的版本处理逻辑，如果您已经想要范围，那么您很可能想要更快的东西。

这里有几个例子：

@RequestMapping({
    "/**/public_api/1.1/method",
    "/**/public_api/1.2/method",
})
public void method1(){
}

@RequestMapping({
    "/**/public_api/1.3/method"
    "/**/public_api/latest/method"
    "/**/public_api/method" 
})
public void method2(){
}

@RequestMapping({
    "/**/public_api/1.4/method"
    "/**/public_api/beta/method"
})
public void method2(){
}

//handles all 1.* requests
@RequestMapping({
    "/**/public_api/{version:1\\.\\d+}/method"
})
public void methodManual1(@PathVariable("version") String version){
}

//handles 1.0-1.6 range, but somewhat ugly
@RequestMapping({
    "/**/public_api/{version:1\\.[0123456]?}/method"
})
public void methodManual1(@PathVariable("version") String version){
}

//fully manual version handling
@RequestMapping({
    "/**/public_api/{version}/method"
})
public void methodManual2(@PathVariable("version") String version){
    int[] versionParts = getVersionParts(version);
    //manual handling of versions
}

public int[] getVersionParts(String version){
    try{
        String[] versionParts = version.split("\\.");
        int[] result = new int[versionParts.length];
        for(int i=0;i<versionParts.length;i++){
            result[i] = Integer.parseInt(versionParts[i]);
        }
        return result;
    }catch (Exception ex) {
        return null;
    }
}

基于最后一种方法，您实际上可以实现您想要的东西。

例如，您可以拥有一个仅包含带有版本处理的方法 stab 的控制器。

在该处理中，您可以（使用反射/AOP/代码生成库）在某些 spring 服务/组件或同一类中查找具有相同名称/签名和需要 @VersionRange 的方法，并通过所有参数调用它。

Answer 4

我已经实现了一个解决方案，可以完美地解决其余版本控制的问题。

一般来说，REST 版本控制有 3 种主要方法：

• Path-based approch，其中客户端在 URL 中定义版本：

  http://localhost:9001/api/v1/user
  http://localhost:9001/api/v2/user
  

• Content-Type头，客户端在Accept头中定义版本：

  http://localhost:9001/api/v1/user with 
  Accept: application/vnd.app-1.0+json OR application/vnd.app-2.0+json
  

• 自定义标头，其中客户端在自定义标头中定义版本。

first 方法的问题是，如果您更改版本，比如说从 v1 -> v2，可能您需要复制粘贴没有的 v1 资源'未更改为 v2 路径

第二种方法的问题是，像http://swagger.io/这样的一些工具无法区分具有相同路径但不同Content-Type的操作（检查问题https://github.com/OAI/OpenAPI-Specification/issues/146）

解决方案

由于我经常使用其他文档工具，因此我更喜欢使用第一种方法。我的解决方案使用第一种方法处理问题，因此您无需将端点复制粘贴到新版本。

假设我们有用户控制器的 v1 和 v2 版本：

package com.mspapant.example.restVersion.controller;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.ResponseBody;

/**
 * The user controller.
 *
 * @author : Manos Papantonakos on 19/8/2016.
 */
@Controller
@Api(value = "user", description = "Operations about users")
public class UserController {

    /**
     * Return the user.
     *
     * @return the user
     */
    @ResponseBody
    @RequestMapping(method = RequestMethod.GET, value = "/api/v1/user")
    @ApiOperation(value = "Returns user", notes = "Returns the user", tags = {"GET", "User"})
    public String getUserV1() {
         return "User V1";
    }

    /**
     * Return the user.
     *
     * @return the user
     */
    @ResponseBody
    @RequestMapping(method = RequestMethod.GET, value = "/api/v2/user")
    @ApiOperation(value = "Returns user", notes = "Returns the user", tags = {"GET", "User"})
    public String getUserV2() {
         return "User V2";
    }
 }

要求是，如果我为用户资源请求 v1，我必须接受 "User V1" 响应，否则如果我请求 v2、v3 等我必须接受 "User V2" 响应。

为了在 spring 中实现这一点，我们需要覆盖默认的 RequestMappingHandlerMapping 行为：

package com.mspapant.example.restVersion.conf.mapping;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.web.method.HandlerMethod;
import org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerMapping;

import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletRequestWrapper;

public class VersionRequestMappingHandlerMapping extends RequestMappingHandlerMapping {

    @Value("${server.apiContext}")
    private String apiContext;

    @Value("${server.versionContext}")
    private String versionContext;

    @Override
    protected HandlerMethod lookupHandlerMethod(String lookupPath, HttpServletRequest request) throws Exception {
        HandlerMethod method = super.lookupHandlerMethod(lookupPath, request);
        if (method == null && lookupPath.contains(getApiAndVersionContext())) {
            String afterAPIURL = lookupPath.substring(lookupPath.indexOf(getApiAndVersionContext()) + getApiAndVersionContext().length());
            String version = afterAPIURL.substring(0, afterAPIURL.indexOf("/"));
            String path = afterAPIURL.substring(version.length() + 1);

            int previousVersion = getPreviousVersion(version);
            if (previousVersion != 0) {
                lookupPath = getApiAndVersionContext() + previousVersion + "/" + path;
                final String lookupFinal = lookupPath;
                return lookupHandlerMethod(lookupPath, new HttpServletRequestWrapper(request) {
                    @Override
                    public String getRequestURI() {
                        return lookupFinal;
                    }

                    @Override
                    public String getServletPath() {
                        return lookupFinal;
                    }});
            }
        }
        return method;
    }

    private String getApiAndVersionContext() {
        return "/" + apiContext + "/" + versionContext;
    }

    private int getPreviousVersion(final String version) {
        return new Integer(version) - 1 ;
    }

}

实现读取 URL 中的版本并从 spring 请求解析 URL。如果此 URL 不存在（例如客户端请求 v3），那么我们尝试使用 v2 以此类推，直到我们找到资源的最新版本。

为了查看此实施的好处，假设我们有两个资源：用户和公司：

http://localhost:9001/api/v{version}/user
http://localhost:9001/api/v{version}/company

假设我们对公司“合同”进行了更改，导致客户违约。所以我们实现了http://localhost:9001/api/v2/company，并要求客户在v1上改为v2。

所以来自客户端的新请求是：

http://localhost:9001/api/v2/user
http://localhost:9001/api/v2/company

代替：

http://localhost:9001/api/v1/user
http://localhost:9001/api/v1/company

这里最好的部分是，使用此解决方案，客户将从 v1 获取用户信息，从 v2 获取公司信息无需创建新的（相同的）来自用户 v2 的端点！

其他文档 正如我之前所说，我选择基于 URL 的版本控制方法的原因是，像 swagger 这样的一些工具不会以不同的方式记录具有相同 URL 但不同内容类型的端点。使用此解决方案，两个端点都会显示，因为它们的 URL 不同：

GIT

解决方案实施： https://github.com/mspapant/restVersioningExample/

Answer 5

@RequestMapping 注释支持headers 元素，允许您缩小匹配请求的范围。特别是您可以在此处使用Accept 标头。

@RequestMapping(headers = {
    "Accept=application/vnd.company.app-1.0+json",
    "Accept=application/vnd.company.app-1.1+json"
})

这与您所描述的不完全一样，因为它不直接处理范围，但该元素确实支持 * 通配符以及 !=。因此，至少对于所有版本都支持相关端点的情况，甚至是给定主要版本的所有次要版本（例如 1.*），您可以避免使用通配符。

我认为我以前没有真正使用过这个元素（如果我不记得了），所以我只是离开了文档

http://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/web/bind/annotation/RequestMapping.html

Answer 6

我已经尝试使用 URI Versioning 对我的 API 进行版本控制，例如：

/api/v1/orders
/api/v2/orders

但在尝试完成这项工作时存在一些挑战：如何使用不同版本组织代码？如何同时管理两个（或更多）版本？删除某些版本有什么影响？

我发现最好的替代方法不是对整个 API 进行版本控制，而是控制每个端点上的版本。这种模式称为Versioning using Accept header 或Versioning through content negotiation：

这种方法允许我们对单个资源表示进行版本化 而不是对整个 API 进行版本控制，这为我们提供了更细粒度的 控制版本控制。它还创造了一个更小的足迹 代码库，因为我们不必分叉整个应用程序 创建一个新版本。这种方法的另一个优点是它 不需要实现由引入的 URI 路由规则 通过 URI 路径进行版本控制。

在 Spring 上的实现

首先，您创建一个具有produces 属性的控制器，该属性将默认应用于同一类中的每个端点。

@RestController
@RequestMapping(value = "/api/orders/", produces = "application/vnd.company.etc.v1+json")
public class OrderController {

}

之后，我们可以想象一个可能的场景，您有两个版本（v1 和 v2）用于“创建订单”的端点：

@Deprecated
@PostMapping
public ResponseEntity<OrderResponse> createV1(
        @RequestBody OrderRequest orderRequest) {

    OrderResponse response = createOrderService.createOrder(orderRequest);
    return new ResponseEntity<>(response, HttpStatus.CREATED);
}

@PostMapping(
        produces = "application/vnd.company.etc.v2+json",
        consumes = "application/vnd.company.etc.v2+json")
public ResponseEntity<OrderResponseV2> createV2(
        @RequestBody OrderRequestV2 orderRequest) {

    OrderResponse response = createOrderService.createOrder(orderRequest);
    return new ResponseEntity<>(response, HttpStatus.CREATED);
}

完成！只需使用所需的 Http Header 版本调用每个端点：

Content-Type: application/vnd.company.etc.v1+json

或者，调用 v2：

Content-Type: application/vnd.company.etc.v2+json

关于您的担忧：

由于并非 API 中的所有方法都在同一个版本中更改，因此我 不想去我的每个控制器并改变任何东西 版本之间没有变化的处理程序

如前所述，此策略使用其实际版本维护每个控制器和端点。您只修改已修改且需要新版本的端点。

大摇大摆呢？

使用此策略设置不同版本的 Swagger 也很容易。 See this answer 了解更多详情。

Answer 7

在产生中你可以有否定。所以对于method1说produces="!...1.7"并且在method2中是肯定的。

produces 也是一个数组，所以对于 method1，你可以说 produces={"...1.6","!...1.7","...1.8"} 等（接受除 1.7 之外的所有内容）

当然不如您想象的范围那么理想，但我认为如果这在您的系统中并不常见，那么维护起来比其他自定义内容更容易。祝你好运！

Answer 8

如果只使用继承来建模版本控制呢？这就是我在我的项目中使用的，它不需要特殊的弹簧配置，并且得到我想要的。

@RestController
@RequestMapping(value = "/test/1")
@Deprecated
public class Test1 {
...Fields Getters Setters...
    @RequestMapping(method = RequestMethod.GET)
    @Deprecated
    public Test getTest(Long id) {
        return serviceClass.getTestById(id);
    }
    @RequestMapping(method = RequestMethod.PUT)
    public Test getTest(Test test) {
        return serviceClass.updateTest(test);
    }

}

@RestController
@RequestMapping(value = "/test/2")
public class Test2 extends Test1 {
...Fields Getters Setters...
    @Override
    @RequestMapping(method = RequestMethod.GET)
    public Test getTest(Long id) {
        return serviceClass.getAUpdated(id);
    }

    @RequestMapping(method = RequestMethod.DELETE)
    public Test deleteTest(Long id) {
        return serviceClass.deleteTestById(id);
    }
}

这种设置允许很少的代码重复，并且能够以很少的工作将方法覆盖到新版本的 api 中。它还省去了使用版本切换逻辑使源代码复杂化的需要。如果您不在版本中编写端点代码，它将默认获取以前的版本。

与其他人所做的相比，这似乎更容易。有什么我想念的吗？

Answer 9

你可以使用AOP，围绕拦截

考虑拥有一个接收所有/**/public_api/* 的请求映射，并且在此方法中什么都不做；

@RequestMapping({
    "/**/public_api/*"
})
public void method2(Model model){
}

之后

@Override
public void around(Method method, Object[] args, Object target)
    throws Throwable {
       // look for the requested version from model parameter, call it desired range
       // check the target object for @VersionRange annotation with reflection and acquire version ranges, call the function if it is in the desired range


}

唯一的限制是所有的都必须在同一个控制器中。

有关 AOP 配置，请查看http://www.mkyong.com/spring/spring-aop-examples-advice/