8

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

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

想象一下,有@Service一层只是当前版本(在我们的例子中是 V2)。

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

现在的问题是:

  • ~.web.* @Controller从java包的角度如何组织不同的?
  • 如何注释~.web.* @Controller他们知道他们的版本的不同之处?以RequestMapping? 或者是否可以在 V1 java 包中使用 context:component-scan 配置它们?
  • 如何组织转换器?放在哪里,如何命名?嗯。像 QuestionsV1ToV2 控制器?
  • 是否需要 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);
    }
}
4

2 回答 2

10

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

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

考虑到这一点,让我们考虑一些目标:(直接从API 演进

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

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

1.添加到资源的表示

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

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

2. 删除或更改现有表示

对语言的此类扩展/更改可以利用 Accept 标头和 Content Negotiation - 表示使用自定义供应商 MIME 媒体类型进行版本控制。这些文章对此进行了更深入的介绍:API 版本控制REST Web 服务版本控制。

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

3. 标准不兼容的变化

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

REST API 应该遵守HATEOAS 约束- 大多数 URI 应该由客户端发现,而不是硬编码。更改这样的 URI 不应被视为不兼容的更改 - 新的 URI 可以替换旧的 URI,客户端将能够重新发现 URI 并仍然有效。

4. 主要不兼容的变化

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

在技​​术方面,我发现:

  • DAO 和服务层不应该根据版本而改变
  • 在 Service 层之上使用 Facade 层(和 DTO)意味着每个版本都有自己的 Facade 和 DTO
  • 干净地分开这两个版本,有两个带有两个的 web 上下文DispatcherServlets可能是有意义的,因为它允许 URI 空间的干净分离
  • 组件扫描应该是细粒度的,并且只在该上下文中选择与该特定版本相关的内容
  • @RequestMapping属性 -producesconsumes很有帮助

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

希望这可以帮助。

于 2013-06-20T14:52:24.320 回答
2

这就是我们在项目中所做的:

    • {developer}.{customer}.{project}.core-@Service还有@Dao东西
    • {developer}.{customer}.{project}.core.model- 模型实体,这是整个core包的工作原理
    • {developer}.{customer}.{project}.api.rest.v1.resource- @ControllerREST资源
    • {developer}.{customer}.{project}.api.rest.v1.model- v1 API 的 DTO
    • {developer}.{customer}.{project}.api.rest.v1.mapper- DTO 和核心模型实体之间的映射器

如果核心不断发展(并且不断发展),它只涉及API 映射器。资源和 DTO 保持不变。

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

我不得不说,我们还没有升级到v2 API——但这已经落后了,因为v1已经是史前的并且在某些方面与核心模型不兼容(不同的模型属性、不同的模型关系、过时和不一致的命名。 ..)。

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

请求映射是手动写入每个 REST 资源中的。所以每个资源都有/v1/...它的映射。

我不能 100% 确信我们的方法是正确的解决方案,甚至接近它。但这很简单。我们将看到v2将如何适应。

于 2013-06-20T09:05:45.350 回答