java - 如何配置 Spring REST 服务来处理多个版本？

Question

几乎所有的 API 都处理不同的发布版本。您经常会看到这种版本控制:

• http://api.com/v1/questions
• http://api.com/v2/questions
• ..

但我还没有找到描述如何在 Spring 堆栈中组织它们的资源。我想在每个 Controller 上使用 /v1 前缀，如 @RequestMapping("/v1/questions") 并不是最好的方法。

假设当前版本(在我们的例子中是 V2)有一个 @Service 层。

我们的服务应该处理 V1 和 V2 的请求。唯一的变化是 V2 在问题实体上添加了一个新字段(这意味着 V1 问题可以轻松转换为 V2 问题)。

现在的问题是:

• 如何从 java 包的角度组织不同的 ~.web.* @Controller？
• 如何注释他们知道自己版本的不同 ~.web.* @Controller？以 RequestMapping 的方式？或者是否可以在 V1 java 包中使用 context:component-scan 配置它们？
• 如何组织转换器？放在哪里，如何命名？ …像 QuestionsV1ToV2 Controller ？
• 是否需要 DTO 层？因为我们的域必须同时处理多个版本？

一个示例可能如下所示(我在各处添加了包):

// on V1 Question look like this:
public class project.domain.Question
{
    private String question;
}

// on v2 Question looks like this:
public class project.domain.Question
{
    private String question;
    private Date creationDate;
}


@Service
public class project.service.QuestionService
{
    public long create(Question q) {...};
    public Question read(long id) {...};
    public void remove(long id) {...};
    public void update(Question qd) {...};

}


@Controller
@RequestMapping("/v2/question")
public class project.web.v2.QuestionController
{
    @Autowired
    project.service.QuestionService questionService;

    @RequestMapping(method = RequestMethod.POST)
    @ResponseBody
    public long create(Question q)
    {
        return questionService.create(q);
    }
}

@Controller
@RequestMapping("/v1/question")
public class project.web.v1.QuestionController
{
    @Autowired
    project.service.QuestionService questionService;

    @RequestMapping(method = RequestMethod.POST)
    @ResponseBody
    public long create(Question q)
    {
        // this will not work, because the v1 haven't had the 'creationDate' field.
        return questionService.create(q);
    }
}

Answer 1

对 REST API 进行版本控制是一个复杂的问题。首先，让我们确定一些高级版本控制方法:

• URI 版本控制 - 资源被认为是不可变的，我们使用版本指示符在资源表示中创建新的 URI 空间变化
• 语言扩展/版本控制——考虑到正在发生变化的是资源的表示，此解决方案将对表示本身进行版本控制，而不会影响 URI 空间

考虑到这一点，让我们考虑一些目标:(直接来自 API Evolution )

• 保留名称中的兼容更改
• 避免新的主要版本
• 使更改向后兼容
• 考虑向前兼容性

接下来，让我们考虑对 API 进行一些可能的更改:

1。添加到资源的表示

语言的设计应明确考虑向前兼容性，客户应忽略他们不理解的信息。

因此，向资源表示添加信息并不是不兼容的更改。

2。删除或更改现有表示

语言的此类扩展/更改可以利用 Accept header 和内容协商 - 表示使用自定义供应商 MIME 媒体类型进行版本控制。这些文章对此进行了更深入的探讨:API Versioning , Versioning REST Web Services .

因此，这确实代表了客户端的不兼容更改 - 客户端将不得不请求新的表示并理解新的语义，但 URI 空间将保持稳定并且不会受到影响。

3。标准不兼容的更改

这些是资源的含义和它们之间的关系的变化。在这种情况下，我们可以看看更改 Resources 和 URI 结构之间的映射。但是，这并不一定意味着在 URI 中使用版本指示符。

REST API 应遵守HATEOAS 约束 - 大多数 URI 应由客户端发现，而不是硬编码。更改此类 URI 不应被视为不兼容的更改 - 新 URI 可以替换旧 URI，客户端将能够重新发现 URI 并且仍然可以正常工作。

4。主要不兼容的更改

对于此类彻底的更改，URI 中的版本指示符是最后的解决方案。

在技术方面，我发现:

• DAO 和服务层不应该根据版本改变
• 在服务层之上使用 Facade 层(和 DTO)意味着每个版本都有自己的 Facade 和 DTO
• 为了清楚地分离两个版本，拥有两个带有两个 DispatcherServlets 的 Web 上下文可能是有意义的，因为它允许清晰地分离 URI 空间
• 组件扫描应该是细粒度的，并且只挑选与该上下文中的特定版本相关的内容
• @RequestMapping 新属性 - produces 和 consumes 也很有用

其他一些非常有用的资源:

• Version Compatibility Strategies

希望这对您有所帮助。