cctg: Fluent API

2023/12/18

Fluent API

fluent API 是一種 OO API design 方式，可讓 API 的使用者，透過 chain method 的方式持續呼叫該物件的 method。在實作這種 API 介面時，method 必須要在最後回傳物件本身的 reference，以最常見的 set methods 來說，以往都是回傳 void，但要改為回傳 this。

在實作支援 Fluent API 這樣的類別時，要注意物件的 immutability 特性，如果該類別是修改物件內部資料的狀態，那麼就直接回傳 this 就好了，但也有可能是持續產生相同類別的新物件。

Difference Between Fluent Interface and Builder Pattern in Java | Baeldung 這個網頁提出了兩種不同的例子

以下是 User 的 Builder，可透過 set method 不斷地修改使用者的各個欄位資料，一直到最後，確認要產生 User 時，就呼叫 build

public static class Builder {
    private String firstName;
    private String lastName;
    private String email;
    private String username;
    private Long id;

    public Builder firstName(String firstName) {
        this.firstName = firstName;
        return this;
    }

    public Builder lastName(String lastName) {
        this.lastName = lastName;
        return this;
    }

    // other methods

    public User build() {
         return new User(firstName, lastName, email, username, id);
    }
}

在使用時

Builder userBuilder = new Builder();
User user = userBuilder
            .firstName("John")
            .lastName("Will")
            .build();

另一個要持續產生新的物件的例子是 Html，因為 html 裡面的 String content 是不能直接修改的，故必須要在 method 最後面都產生一個新的物件

public class HtmlDocument {
    private final String content;

    public HtmlDocument() {
        this("");
    }

    public HtmlDocument(String html) {
        this.content = html;
    }

    public String html() {
        return format("<html>%s</html>", content);
    }

    public HtmlDocument header(String header) {
        return new HtmlDocument(format("%s <h1>%s</h1>", content, header));
    }

    public HtmlDocument paragraph(String paragraph) {
        return new HtmlDocument(format("%s <p>%s</p>", content, paragraph));
    }
}

使用時

HtmlDocument document = new HtmlDocument()
  .header("header")
  .paragraph("paragraph 1")
  .paragraph("paragraph 2");
String html = document.html();