一个扩展搜索API的优化过程

概述

API 是一个服务的门面，就像衣装是人的形象一样。

优雅的 API 设计，能让业务方使用起来倍儿爽，提升开发效率，降低维护成本；糟糕的 API 设计，则让业务方遭心，陷入混沌。

本文将展示一个扩展搜索 API 的优化过程，从中也可以学到一些东西。

现状

找一个上游工程的扩展搜索代码如下：

extendKeywords.add((EsCondition) ConditionFactory.in("order_tags", Arrays.asList("IS_XXX_ORDER")));
extendKeywords.add(new EsCondition("goods_title", Op.match, new Match(goodsTitle, "100%")));

啊啊，真是丑死了 ！ 为什么呢 ？

• 强制类型转换。 让业务方写强制类型转换，简直是让业务方来遭罪的 ！ 这 API 设计简直了 ！
• 暴漏底层细节。 让业务方 new EsCondition ，不仅是暴漏底层细节，还很难看！
• 不方便的传值。 为了传一个 in 的数值，需要写个 Arrays.asList(e) ！
• 遍布的 EsCondition 。 由于 API 设计的很裸，导致上游工程到处弥漫着 EsCondition 的烟雾。

emmm... 其实是我设计的 API 造的孽 ！ 解铃还须系铃人。

优化过程

工厂方法

这种硬的 new EsConditon ，完全可以通过工厂方法和方法重载来消除。此外，为了收拢扩展搜索条件的构建，可以构建一个专门的 ExtendSearchParam 。

public class ExtendSearchParam implements Serializable {
  private static final long serialVersionUID = 2824767430430079287L;

  private List<EsCondition> extendConditions = new ArrayList<>();

  public ExtendSearchParam addEq(String field, Object value) {
    extendConditions.add(new EsCondition(field, Op.eq, value));
    return this;
  }

  public ExtendSearchParam addIn(String field, Object... list) {
    extendConditions.add(new EsCondition(field, Op.in, list));
    return this;
  }

  public ExtendSearchParam addRange(String field, long gte, long lte) {
    extendConditions.add(new EsCondition(field, Op.range, new Range(gte, lte)));
    return this;
  }

  public ExtendSearchParam addMatch(String field, String query) {
    extendConditions.add(new EsCondition(field, Op.match, new Match(query, "100%")));
    return this;
  }

  public ExtendSearchParam addMatch(String field, String query, String match) {
    extendConditions.add(new EsCondition(field, Op.match, new Match(query, match)));
    return this;
  }
}

这里借鉴了 Builder 模式，能够链式地构建扩展搜索条件。这样，业务方就可以舒心地写上：

extendSearchParam.addIn(ORDER_TAGS, "IS_XXX_ORDER").addMatch("goods_title", goodsTitle);

没有了类型强制转换，没有了暴漏底层细节，没有了不方便的传值，还可以一直 add 下去， 世界多美好 ！

拦路虎

很快，就遇到了拦路虎：

private List<EsCondition> dealOrderSourceCondition(String orderSource) {        
     List<EsCondition> result = new ArrayList();
     result.add(new EsCondition(TYPE_ENTRANCE, Op.eq, "wsc"));
     result.add(new EsCondition(TYPE_PLATFORM, Op.eq, "wx"));
     return result;
}

emmm , 写这个方法的小伙伴也是好意，封装一个方法来构建订单来源扩展条件也是好意。不过这给API 重构带来了一点点小小的障碍。

怎么重写这一段呢 ？ 第一想到的是，在 dealOrderSourceCondition 的方法里额外增加一个参数 ExtendSearchParam ，传进去，修改它。也能达到目地。但是，—— 破坏了“不可变”原则。 不可变原则要求，尽可能避免修改入参。修改入参这种行为，很容易导致不起眼的 BUG ，如果在关键流程中做这个事情，有可能导致故障。有线上教训的。

怎么办呢 ？ 又不能修改 dealOrderSourceCondition 的入参，又要把这个方法的扩展搜索条件合并到已有的扩展搜索对象中。

有一种办法 ！ 合并扩展搜索对象 ExtendSearchParam 。 这样，ExtendSearchParam 需要支持一个合并操作：

public ExtendSearchParam merge(ExtendSearchParam extendSearchParam) {
    if (extendSearchParam != null && extendSearchParam.has()) {
      extendConditions.addAll(extendSearchParam.getUnmodifiedExtendSearch());
    }
    return extendSearchParam;
  }

这样，将 dealOrderSourceCondition 的返回值改为 ExtendSearchParam 对象，就能使用 merge 方法来合并扩展搜索条件了。

Yeap ! 想一想，除了 合并操作，还需要支持哪些操作呢 ？API 设计需要考虑周全，可不能遇到一个问题加一个支持啊 ！

辅助方法

为了与原来的 OrderSearchParam 联合使用， 需要加一些辅助方法，比如：

public boolean has() {
    return CollectionUtils.isNotEmpty(extendConditions);
  }

  public List<EsCondition> getUnmodifiedExtendSearch() {
    return Collections.unmodifiableList(extendConditions);
  }

小结

本文讲解了一个扩展搜索 API 的优化过程。好的 API 设计能提升业务方的使用体验，降低维护成本。设计优雅的 API ，需要掌握一些技巧：工厂方法、重载方法、常用操作等。

从工作中不断发现需要优化的地方，掌握方法和技巧去解决， 也是一种提升技能的方式。