java - 弃用分页参数

Question

我最近收到一个请求，将 spring REST 分页参数“page”和“size”重命名为“pageIndex”和“pageSize”。我的 Controller 采用 Pageable 对象作为参数。也就是说，我知道我可以通过设置以下属性来重命名这些参数，如下所示:

spring.data.rest.page-param-name=pageIndex
spring.data.rest.limit-param-name=pageSize

但是，由于我正在开发的 API 正在被其他开发人员积极使用，因此我需要弃用而不是删除“page”和“size”参数(同时继续保留api 尊重它们的值)，同时支持新的可分页参数名称。我查阅了各种文档和文章，经过一天的搜索，我仍然不清楚如何实现这个任务。

我的 Controller 方法看起来像这样:

@ApiPageable
@RequestMapping(produces = MediaType.APPLICATION_JSON_UTF8_VALUE, method = RequestMethod.GET)
public Page<MyBean> getBeans(@RequestParam(required = false) final String blah,
                               final Pageable pageable) {

    return someService.doSomething(blahStr, pageable); 
}

提前致谢，如果在我的搜索过程中，我可能错过了我正在寻找的关键文档，请为我指明方向并接受我的歉意。

编辑:为了澄清这个问题......重命名并不涉及更改 url。事实上，URL 必须保持相同。相反，被重命名的是一组url 分页参数。需要明确的是，如果这个问题所属的终点看起来像这样，并且不包括一组常见的分页参数，这些参数通常用于(但不限于)以下内容的某些排列或组合:

/beans
/beans?page=2
/beans?size=5
/beans?page=2&size=5
/beans?sort=created,ASC&page=4&size=6

...然后使用相同的 URL 创建第二个端点(但所有必需的参数都标记为 false)，当我尝试运行 API 时，会产生不明确的映射。因此，除非有一种巧妙的方法来区分这些端点(使用已弃用参数的端点和使用新参数的新端点)，否则此解决方案似乎需要两个以上端点，...或者最好有一个巧妙的方法处理这个问题的“银弹”方法。

Answer 1

使用两个端点:一个用于已弃用的 API，另一个用于新 API。在已弃用的 API 中，将已弃用的参数转换为新参数，调用您的内部服务，将响应转换为已弃用的响应。

稍后，在所有客户端迁移到新 API 后，或在预定义的迁移期后，您可以决定删除已弃用的端点。

更新

对于不能(或不想)使用更改后的 API 的客户端，请提供实现旧 API 的端点。该方法如下所示:

@GetMapping(path = "/oldapi/...")
public Page<MyBean> getBeans(
    @RequestParam(required = false) final String blah,
    @RequestParam(value = "pageSize", required = false) Integer pageSize,
    @RequestParam(value = "pageNum", required = false) Integer pageNum,
    @RequestParam(value = "sort", required = false)
) {
    // Create Pageable object from request parameters
    ...
    // Call service or repository with this pageable
    ...
}

在此方法中您可以使用任何参数名称。对于那些需要旧名称的人，您可以保留旧名称。

对于端点的数量:我的意思是 2 个端点:一个 API 名称保持不变，另一个发生变化(您写道我最近有一个重命名请求...)

更新2

支持 2 个版本的 API 的好方法是使用2 个端点。如果您想通过单个端点提供 2 个 API，这可能很容易出错。在简单的情况下这是可能的。例如，您按如下方式定义方法:

@GetMapping(path = "/oldapi/...")
public Page<MyBean> getBeans(
    @RequestParam(value = "size", required = false) Integer size,
    @RequestParam(value = "pageSize", required = false) Integer pageSize,
    @RequestParam(value = "page", required = false) Integer page,
    @RequestParam(value = "pageIndex", required = false) Integer pageIndex,
    ...
) {
    Integer pSize = pageSize != null ? pageSize : size;
    Integer pIndex = pageIndex != null ? pageIndex : page;
    ...
}

保存这样的代码可能非常复杂。例如，如果某些参数是强制性的，那么在单个端点中实现它会很复杂并且容易出错，但如果有两个不同的端点则非常容易。我不鼓励您使用这种方法。

我的建议:为那些想要使用已弃用的 API 的人提供一个单独的端点。他们不必更改代码，只需更改配置参数以指向已弃用的 API 的端点。如果他们仍想使用已弃用的 API，这对他们来说是正常价格。