如何设计一个更通用的查询接口
临近放假，手头的事情没那么多，老是摸鱼也不好，还是写写博客吧。
今天来聊聊：如何设计一个通用的查询接口。
从一个场景开始
首先，我们从一个简单的场景开始。现在，我需要一个订单列表，用来查询【我的订单】，支持分页，且支持高级搜索。
整个查询流程
我们先来设计下整个查询的流程，我认为大致如下图。简单来说就是：接收查询条件 -》 校验条件 -》添加条件 -》 执行查询 -》 转换 VO -》 返回结果。
注意，因为不同公司用的语言或者代码分层可能不一样，所以，我们没必要纠结具体的代码实现，只要关注一些更高抽象层级的共性就行了。
一些疑问
看到上图的流程，有的人可能会问一些问题，这里我简单回答下：
- 为什么后端还要设置条件？前端不都设置好了吗？
就拿【我的订单】来说，查询条件中肯定要有【订单所属人】这个条件吧，你放心把这个字段交给前端来设置吗？如果你选择这么做，那么不好意思，这篇文章可能在浪费了您的时间。
- 为什么不建议联表构建 VO？
如果 VO 里的数据都来自同一个 DB，按理来说，我们可以使用联表的方法直接映射 VO，而不需要在代码中将实体转 VO，像 mybatis 这种类库就可以很轻易地做到这一点。但是，我不建议这么做。因为以后你的数据源可能会分库分表，甚至改成第三方接口、ES、redis 等，到时你还能联表吗？当然，我只是建议尽量不要。
- 为什么转 VO，直接返回不行吗？
我们的实体中的字段，有可能太多，也有可能太少。多指的是，我返回了一些不能返回的字段，例如用户密码；少指的是，前端要的字段，实体里不一定有。这时有人可能会问，如果实体里没有不能返回的字段，且能够完全满足前端的所有字段需求，是不是就可以直接返回。这个嘛，你真的能保证吗？
具体代码实现
这里提供一种简单的 java 实现。
Controller
@RestController
@RequestMapping("/order")
public class OrderController {
@Resource
private OrderService orderService;
@PostMapping("/queryPage")
public DataResponse> queryPage(@RequestBody OrderQuery query) {
return DataResponse.of(orderService.queryPage(query));
}
}
Service
@Service
public class OrderService {
@Resource
private OrderGateway orderGateway;
public Page queryPage(OrderQuery query) {
// 校验
validate(query);
// 添加条件
addCon(query);
// 执行查询
Page sourcePage = orderGateway.queryPage(query);
// 转换为VO并返回结果
return ConvertUtils.convertPage(sourcePage, OrderConverter::convert2MyListVO);
}
}
查询场景变多了
好了，说完单个场景，我们再来说说多个场景的情况。我需要增加【商场的订单】、【下属的订单】等等。
加接口or不加？
这时，我们有两种选择：加接口 or 不加接口？如果加接口的话，随着场景的增加，我们的接口会越来越多。我相信更多的人会选择不加接口，即用一个查询接口来搞定所有场景。
如何区分不同场景？
那么问题来了，不加接口的情况下，我们应该怎么设计呢？
我们会发现，不同的场景，查询的流程都是一样的，只是在校验条件、添加条件、转换 VO 三个节点的逻辑上有所区别。对应上图的步骤 2、3、8。于是，针对这三个节点，我们需要根据不同的场景走不同的逻辑，类似于大家常说的策略模式，当然，这样做要有一个前提，就是我们能够区分请求是来自哪个场景。
其中一个实现就是，在 query 中增加一个 scenarioFlag 字段，由调用方传值，当查【我的订单】时值为 OrderQryPage2Me，当查【商场的订单】时值为 OrderQryPage2Market······
如何实现？
这里我还是提供简单的 java 实现。实际使用的话会更复杂一些。
Controller
这时，返回值的泛型就不能写死了，因为同一个接口有可能返回不同的类型。这一点相信很多人都没法接受。
@RestController
@RequestMapping("/order")
public class OrderController {
@Resource
private OrderService orderService;
@PostMapping("/queryPage")
public DataResponse<?> queryPage(@RequestBody OrderQuery query) {
return DataResponse.of(orderService.queryPage(query));
}
}
Service
我用的是阿里的 Cola 框架来处理不同场景的策略分发，每个场景中差异化的逻辑都放在一个可插拔的的扩展点里，而扩展点根据【业务-用例-场景】来划分。具体实现如下。
前面说过，不同场景只是在校验条件、添加条件、转换 VO 三个节点的逻辑上有所区别，然而，还是存在某些场景，连执行查询这个节点的逻辑也不一样。这里也兼容了这种情况。
@Service
public class OrderService {
@Resource
private ExtensionExecutor extensionExecutor;
@Resource
private OrderGateway orderGateway;
public Object queryPage(OrderQuery query) {
// 设置场景
BizScenario bizScenario = BizScenario.valueOf(
ORDER, // 订单业务
ORDER_QUERY, // 订单查询
query.getScenarioFlag() // 具体场景
);
// 根据不同的场景走不同的逻辑：校验、加条件、转VO
// 这里的转VO逻辑还没走，只是把逻辑作为Function设置到query里面
Object result = extensionExecutor.execute(
OrderQryExtPt.class,
bizScenario,
x -> x.extendQuery(query)
);
// 如果返回非空对象，则直接将结果返回，不再走通用查询
if(result != null) {
return result;
}
// 执行通用查询
result = orderGateway.queryPage(query);
// 这里才开始走转VO的逻辑
if(query.getConvertMethod() != null) {
return query.getConvertMethod().apply(result);
}
return result;
}
}
具体的扩展点如下。里面一般就是差异化的三个节点逻辑。
@Extension(
bizId = ORDER, // 订单业务
useCase = ORDER_QUERY, // 订单查询
scenario = OrderQryPage2Me // 我的订单
)
public class OrderQryPage2MeExt implements OrderQryExtPt {
@Override
public Object extendQuery(OrderQuery query) {
// 校验
validate(query);
// 添加条件 zzs001
addCon(query);
// 设置转换VO的逻辑
Function> convertMethod = x -> {
Page sourcePage = (Page)x;
return ConvertUtils.convertPage(sourcePage, OrderConverter::convert2MyListVO);
};
query.setConvertMethod(convertMethod);
return null;
}
}
要不要万能VO？
上面的例子中，针对不同的场景，我会提供不同的 VO。但有些人会尝试用一个万能的 VO 来应对所有的场景，我认为，这是非常不利于维护的做法。随着场景的增加，你的 VO 字段会越来越多，你根本区分不出来哪些场景需要哪些字段，最重要的是，这种通用 VO 让很多场景不得不去查询一些不需要的字段，而耗费性能。
结语
以上就是我对查询接口设计的一些想法，虽然不算成熟，但也不是纸上谈兵，因为我们的订单系统现在采用的就是这种方式，目前落地效果还是可以的。当然，可能是因为业务还没那么复杂吧。
最后，感谢阅读，欢迎交流、指正。
本文为原创文章，转载请附上原文出处链接：