如何设计一个更通用的查询接口
临近放假,手头的事情没那么多,老是摸鱼也不好,还是写写博客吧。
今天来聊聊:如何设计一个通用的查询接口。
从一个场景开始
首先,我们从一个简单的场景开始。现在,我需要一个订单列表,用来查询【我的订单】,支持分页,且支持高级搜索。
整个查询流程
我们先来设计下整个查询的流程,我认为大致如下图。简单来说就是:接收查询条件 -》 校验条件 -》添加条件 -》 执行查询 -》 转换 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<Page<Order2MyListVO>> queryPage(@RequestBody OrderQuery query) {
return DataResponse.of(orderService.queryPage(query));
}
}
Service
@Service
public class OrderService {
@Resource
private OrderGateway orderGateway;
public Page<Order2MyListVO> queryPage(OrderQuery query) {
// 校验
validate(query);
// 添加条件
addCon(query);
// 执行查询
Page<OrderE> 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<Object, Page<Order2MyListVO>> convertMethod = x -> {
Page<OrderE> sourcePage = (Page<OrderE>)x;
return ConvertUtils.convertPage(sourcePage, OrderConverter::convert2MyListVO);
};
query.setConvertMethod(convertMethod);
return null;
}
}
要不要万能VO?
上面的例子中,针对不同的场景,我会提供不同的 VO。但有些人会尝试用一个万能的 VO 来应对所有的场景,我认为,这是非常不利于维护的做法。随着场景的增加,你的 VO 字段会越来越多,你根本区分不出来哪些场景需要哪些字段,最重要的是,这种通用 VO 让很多场景不得不去查询一些不需要的字段,而耗费性能。
结语
以上就是我对查询接口设计的一些想法,虽然不算成熟,但也不是纸上谈兵,因为我们的订单系统现在采用的就是这种方式,目前落地效果还是可以的。当然,可能是因为业务还没那么复杂吧。
最后,感谢阅读,欢迎交流、指正。
本文为原创文章,转载请附上原文出处链接:https://www.cnblogs.com/ZhangZiSheng001/p/15822105.html