一、概述
fluent api（流式接口）是软件工程中面向对象API的一种实现方式，以提供更为可读的源码。从表现上来看，接口调用呈现链式调用（瀑布式调用），看起来非常流畅，荡气回肠。
事实上，即使是初级的JAVA程序员，对于flent api也应该不陌生；在拼接字符串时，一定写过以下的代码：
StringBuilder sb = new StringBuilder()
.append(1)
.append("2")
.append(1.1);
这就是一种fluent api的具体体现方式，只是没有用一个高大上的专有词汇武装它而已。
二、设计方法
fluent api 通常采取方法链式调用（瀑布调用）来转发一系列对象调用的上下文。这个上下文通常是：
- 通过被调方法的返回值定义
- 自引用，新的上下文等于老的上下文
- 返回一个空的上下文来终止
设计一个好的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<Country> 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。
参考
- tkmybatis 官网：https://github.com/abel533/Mapper
- lombok 官网： https://projectlombok.org/
