Question

几乎所有API都处理不同的发行版本。通常你会看到这种版本：

但是我没有找到一个描述如何在Spring堆栈中组织它们的源代码。我想在每个控制器上都有一个/v1前缀，如@RequestMapping("/v1/questions")，这不是最佳方法。

想象一下，只有当前版本的@Service层（在我们的例子中为V2）。

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

现在的问题是：

如何从java包的角度组织不同的~.web.* @Controller？
如何注释他们知道其版本的不同~.web.* @Controller？以RequestMapping的方式？或者是否可以使用上下文配置它们：在V1 java包中进行组件扫描？
如何组织转换器？把它们放在哪里，如何命名它们？水木清华。像QuestionsV1ToV2控制器？
是否有DTO图层重新征集？因为我们的Domain必须同时处理许多版本？

一个例子看起来像这样（我在各处添加了包）：

// 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标头和内容协商 - 使用自定义供应商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

希望这会有所帮助。

Answer 2

这就是我们在项目中所做的事情：

包
- {developer}.{customer}.{project}.core - @Service和@Dao内容
- {developer}.{customer}.{project}.core.model - 模型实体，这是整个core包与
- {developer}.{customer}.{project}.api.rest.v1.resource - @Controller REST资源
- {developer}.{customer}.{project}.api.rest.v1.model - v1 API的DTO
- {developer}.{customer}.{project}.api.rest.v1.mapper - DTO与核心模型实体之间的映射器

如果 core 发展（并且不断发展），它只涉及 API映射器。资源和DTO保持不变。

自从我们引入 v1 API以来，我们的核心及其模型发生了很大变化。当然，我们正在对 v1 进行一些向后兼容的更改 - 引入新的搜索参数，资源或基于参数的响应修饰符。

而且我必须说我们还没有进入 v2 API - 但是这已经落后了，因为 v1 已经是史前的，并且在某些方面与之不兼容核心模型（不同的模型属性，不同的模型关系，过时和不一致的命名......）。

如果我们想在版本之间重用一些代码，我可以想象它会放在{developer}.{customer}.{project}.api.rest.base中。

请求映射在每个REST资源中手动编写。因此，每个资源的映射都有/v1/...。

我并不完全相信我们的方式是正确的解决方案，甚至接近它。但这很简单。我们将看到 v2 如何适应。

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

2 个答案:

1。添加到资源的表示

2。删除或更改现有的表示

3。标准不兼容的更改

4。主要不兼容的变更

在技术方面，我发现：