Fluent Interface 流式接口

一、概述

fluent api（流式接口）是软件工程中面向对象API的一种实现方式，以提供更为可读的源码。从表现上来看，接口调用呈现链式调用（瀑布式调用），看起来非常流畅，荡气回肠。

事实上，即使是初级的JAVA程序员，对于flent api也应该不陌生；在拼接字符串时，一定写过以下的代码：

StringBuilder sb = new StringBuilder()
        .append(1)
        .append("2")
        .append(1.1);

这就是一种fluent api的具体体现方式，只是没有用一个高大上的专有词汇武装它而已。

二、设计方法

fluent api 通常采取方法链式调用（瀑布调用）来转发一系列对象调用的上下文。这个上下文通常是：

1. 通过被调方法的返回值定义
2. 自引用，新的上下文等于老的上下文
3. 返回一个空的上下文来终止

设计一个好的fluent api 并不仅仅是返回一个自引用的“this”那么容易。可读性是fluent api的唯一标准，需要注意如何命名和构造代码。
fluent api中的方法可以链式调用，从而创建方法调用流（就像瀑布一样）。要允许链式方法，只有一条规则：fluent api的方法必须返回非void值

自引用

从实现角度，多数的代码选择返回自引用的“this”使得链式调用成为可能：

class FluentApi {
    public FluentApi foo() {
        // some operation
        return this;
    }
    
    public FluentApi bar() {
    // some operation
    return this;
  }
}

// usage:
FluentApi fa = new FluentApi();
// chain calls
fa.foo().bar();

比较好的一个例子是 tkmybatis 的 Example调用方式：

Example example = Example.builder(Country.class)
        .select("countryname")
        .where(Sqls.custom().andGreaterThan("id", 100))
        .orderByAsc("countrycode")
        .forUpdate()
        .build();
List countries = mapper.selectByExample(example);

合理的返回值

当然，fluent api不只是可以通过返回自引用实现，还可以是任意的非 void对象。只要符合逻辑的，在增强可读性的原则内即可，只是这种比较难把握。

三、最佳实践

实体类构建

实体类（POJO, 各种vo，dto）是业务代码的好伙伴，程序员搬砖多半是与它们打交道。

public class Person implements Serializable {
    private String name;
    private Integer age;
    private String gender;
    // 省略getter setter
}

// 当需要使用实体类作为方法调用的参数时
Person p = new Person();
p.setName("Richard");
p.setAge(18);
p.setGender("F");
Object result = query(p);

如果Person类的属性很多，那么构造Person对象的代码流畅性与可读性，代码看起来很臃肿。
当然可以为Person类提供全属性参数的构造器，这也有弊端，当属性较多，而一些属性又不需要时，不得不插入一些难看的null参数：

Object result = query(new Person("Richard", null, null, null, 18, null, null, "F"));

这也是噩梦吧。

public class Person implements Serializable {
    private String name;
    private Integer age;
    private String gender;

    public Person() {
    }

    public Person(Builder b) {
        this.name = b.name;
        this.age = b.age;
        this.gender = b.gender;
    }

    // 公有static方法返回实体类的builder
    public static Builder builder() {
        return new Builder();
    }

    public static final class Builder {
        // 通常拥有宿主实体类的全部属性
        private String name;
        private Integer age;
        private String gender;

        // 以实体属性名作为方法名，为属性赋值，并返回this builder
        public Builder name(String name) {
            this.name = name;
            return this;
        }

        public Builder age(Integer age) {
            this.age = age;
            return this;
        }

        public Builder gender(String gender) {
            this.gender = gender;
            return this;
        }
        
        //  最后提供一个build方法，使用builder收集来的属性创建实体类
        //  实体类的创建方式多种多样，只要达到目的即可。通常实体类提供全属性的构造器，或者以Builder为参数的构造器。
        public Person build() {
            return new Person(this);
        }
    }
    
    // 省略person类属性的getter setter
}

// fluent api
Object result = query(Person.builder()
        .name("Richard")
        .age(18)
        .gender("F").build());

以上是大动干戈为一个实体类写了builder，更简单的方法是使用 lombok 的 @Builder 注解，自动生成builder构建实体类，具体参看lombok 的官网。

构建工厂

fluent api用作构建工厂时，与实体的原理没啥不同，不过略微复杂，只是在流式方法命名上有所不同而已。

以http client 的builder类 HttpClientBuilder 为例：

public class HttpClientBuilder {

    // 一堆属性
    public static HttpClientBuilder create() {
        return new HttpClientBuilder();
    }

    public final HttpClientBuilder setSSLHostnameVerifier(final HostnameVerifier hostnameVerifier) {
        this.hostnameVerifier = hostnameVerifier;
        return this;
    }

    // 一堆set方法

    public CloseableHttpClient build() {
        // 超级复杂的build方法，构造一个CloseableHttpClient实例
    }
}

与实体类的builder有所不同，这里builder完全是一个构建工厂。

四、总结

fluent api（流式接口）的主要目的是增强代码可读性，为了做到可读性，需要额外编写代码实现builder，不过已经有一系列的代码生成工具（如lombok）来自动生成builder。
fluent api的实现多是 方法返回返回自引用this。

参考

1. tkmybatis 官网：https://github.com/abel533/Mapper
2. lombok 官网： https://projectlombok.org/