实践中的REST web服务版本控制

Question

@RequestMapping(method = RequestMethod.GET, produces = "application/vnd.example-v1+json")

版本2：

@RequestMapping(method = RequestMethod.GET, produces = "application/vnd.example-v2+json")

还是这样做错了？或者更常见的是创建不同的包来保存不同版本的控制器？还是有其他办法？

Answer 1

这里的问题不是版本信息所在的位置（URI vs header)，而是如何为不同版本组织代码。

我怀疑有一个单一的标准方法。这只是取决于版本有多大的不同。

简单的格式更改。例如，假设唯一的区别是从V1中的XML转移到V2中的JSON。在这种情况下，您可以使用完全相同的代码，但只需将应用程序配置为全局输出JSON即可。不需要不同的封装或控制器。（例如，您可以使用JAXB注释来驱动XML和Jackson生成的JSON输出。）

主要架构更改。如果您的架构更改是深入和广泛的，您可能需要的不仅仅是单独的控制器。您甚至可能需要一个不同的域模型（实体/服务）。在这种情况下，为控制器提供一组并行的包，一直到实体、repos甚至数据库表，可能是很有意义的。

方法1.将这些思想应用到@requestmapping示例中，您可以按照上面所说的去做，但是如果版本之间的响应完全相同，那么它们应该只委托给一个共享方法：

@RequestMapping(
    value = "/orders/{id}",
    method = RequestMethod.GET,
    produces = "application/vnd.example-v1")
@ResponseBody
public Order getOrderV1(@PathVariable("id") Long id) {
    return getOrder(id);
}

@RequestMapping(
    value = "/orders/{id}",
    method = RequestMethod.GET,
    produces = "application/vnd.example-v2")
@ResponseBody
public Order getOrderV2(@PathVariable("id") Long id) {
    return getOrder(id);
}

private Order getOrder(Long id) {
    return orderRepo.findOne(id);
}

像这样的东西就行了。如果不同版本的顺序不同，那么您可以在方法中实现这些差异。

// The baseline
public abstract class BaseOrderController {

    @RequestMapping(value = "/{id}", method = RequestMethod.GET)
    @ResponseBody
    public Order getOrder(@PathVariable("id") Long id) { ... }
}    

// V1 controller
@RequestMapping(value = "/orders", produces = "application/vnd.example-v1")
public class OrderControllerV1 extends BaseOrderController {

    ... no difference from baseline, so nothing to implement ...
}

// V2 controller
@RequestMapping(value = "/orders", produces = "application/vnd.example-v2")
public class OrderControllerV2 extends BaseOrderController {

    @RequestMapping(value = "/{id}", method = RequestMethod.GET)
    @ResponseBody
    @Override
    public Order getOrder(@PathVariable("id") Long id) {
        return orderRepoV2.findOne(id);
    }
}