不推荐使用分页参数

Question

我最近请求将spring REST分页参数“Page”和“Size”重命名为“PageIndex”和“PageSize”。我的控制器采用一个可分页的对象作为参数。话虽如此，我理解我可以通过设置以下属性来重命名这些参数，如下所示：

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分页参数。需要明确的是，如果这个问题所涉及的endpoint如下所示，并且不包括一组常用的分页参数，这些参数通常用于以下内容的某些排列或组合（但不限于）：

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

...然后创建一个具有相同URL的第二个endpoint（但是所有带有required的参数都标记为false），在我尝试运行API时会给我一个不明确的映射。因此，除非有一种巧妙的方法来区分这些endpoint（使用不推荐参数的endpoint和使用新参数的新endpoint），否则这个解决方案似乎需要两个以上的endpoint，……或者最好有一种巧妙的“银弹”方法来处理这个问题。

Answer 1

使用两个endpoint：一个与不推荐使用的API一起使用，一个与新的API一起使用。在deprecated API中，将deprecated参数转换为新参数，调用您的内部服务，将响应转换为deprecated响应。

稍后，在所有客户端迁移到新API之后，或者在预定义的迁移周期之后，您可以决定删除不推荐使用的endpoint。

更新

@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

支持2个版本API的好方法是使用2个endpoint。如果您想通过一个endpoint提供两个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;
    ...
}

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

我的建议是：对于那些想要使用不推荐的API的人，提供一个单独的endpoint。他们不需要改变他们的代码，只需要改变配置参数以指向一个带有不推荐使用的API的endpoint。如果他们还想使用不推荐使用的API，这对他们来说是一个正常的价格。