Builder — 分離複雜物件的建構與表示

1. 意圖

將一個複雜物件的建構步驟與最終表示分離,使同樣的建構流程可以產生不同的物件,同時消除因可選參數過多而衍生的「伸縮建構子」反模式。

2. UML 類圖

classDiagram
    class Director {
        +construct(Builder)
    }
    class Builder {
        <>
        +buildPartA()
        +buildPartB()
        +getResult() Product
    }
    class ConcreteBuilder {
        -product Product
        +buildPartA()
        +buildPartB()
        +getResult() Product
    }
    class Product
    Director --> Builder
    Builder <|.. ConcreteBuilder
    ConcreteBuilder --> Product

3. 何時用 / 何時別用

用:

  • 建構子有 4 個以上參數,且部分為可選(Effective Java Item 2)
  • 物件不可變(immutable),但欄位多到無法一次傳入
  • 需要在 build() 時做跨欄位的驗證邏輯

別用:

  • 欄位少且全為必填,直接用建構子更清晰
  • 物件非常簡單(考慮改用 Java Record)
  • 效能極敏感路徑(每次 build() 都產生一個中間 Builder 物件)

4. Java 範例

以 HTTP 請求設定為例,展示必填欄位在 Builder 建構子中固定、可選欄位採 fluent 設定:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
public final class HttpRequest {
    private final String method;
    private final String url;
    private final Map<String, String> headers;
    private final String body;
    private final int timeoutMs;

    private HttpRequest(Builder b) {
        this.method     = b.method;
        this.url        = b.url;
        this.headers    = Map.copyOf(b.headers);
        this.body       = b.body;
        this.timeoutMs  = b.timeoutMs;
    }

    public static Builder of(String method, String url) {
        return new Builder(method, url);
    }

    public static final class Builder {
        private final String method;
        private final String url;
        private final Map<String, String> headers = new LinkedHashMap<>();
        private String body;
        private int timeoutMs = 5_000;

        private Builder(String method, String url) {
            if (method == null || method.isBlank()) throw new IllegalArgumentException("method required");
            if (url == null || url.isBlank())       throw new IllegalArgumentException("url required");
            this.method = method;
            this.url    = url;
        }

        public Builder header(String name, String value) {
            headers.put(name, value);
            return this;
        }

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

        public Builder timeoutMs(int ms) {
            if (ms <= 0) throw new IllegalArgumentException("timeoutMs must be positive");
            this.timeoutMs = ms;
            return this;
        }

        public HttpRequest build() {
            return new HttpRequest(this);
        }
    }

    // getters omitted for brevity
}

// 呼叫端
HttpRequest req = HttpRequest.of("POST", "https://api.example.com/users")
    .header("Content-Type", "application/json")
    .header("Authorization", "Bearer token")
    .body("{\"name\":\"Alice\"}")
    .timeoutMs(3_000)
    .build();

5. JDK / Spring 真實案例

案例說明
StringBuilder / StringJoiner最基本的 Builder:累積片段,最後呼叫 toString() 一次性建立不可變字串
Stream.Builder<T>Stream.<String>builder().add("a").add("b").build() — 先收集元素,再建立 Stream
Spring UriComponentsBuilderUriComponentsBuilder.fromHttpUrl(url).queryParam("k","v").build() — 建構 URI,最後 build() 回傳不可變的 UriComponents
Spring MockMvcRequestBuildersMockMvcRequestBuilders.post("/api").content(json).contentType(MediaType.APPLICATION_JSON) — 測試中建構 HTTP 請求

6. 與相近 Pattern 的差異

BuilderFactory MethodPrototype
關注點逐步建構複雜物件決定建立哪個子類複製現有實例
參數多寡適合多可選參數通常參數少從既有狀態複製
回傳時機呼叫 build() 才完成方法呼叫立刻回傳呼叫 clone() 立刻回傳

7. 現代 Java 取代方案

Lombok @Builder 是目前最常見的寫法,它自動生成上述 Builder 樣板:

1
2
3
4
5
6
7
8
@Builder
@Value  // 搭配 @Value 讓欄位 final + getter
public class HttpRequest {
    @NonNull String method;
    @NonNull String url;
    @Builder.Default int timeoutMs = 5_000;
    String body;
}

Lombok 生成的程式碼等同於手寫的靜態內部 Builder 類,加上 toBuilder() 支援 wither-style 複製。

Java Records 適合所有欄位皆必填且數量合理的情境,但沒有內建流式 API;多個可選欄位時仍建議搭配 Builder 或 Lombok:

1
2
3
4
// 適合 Record:欄位少,全必填
public record Point(double x, double y) {}

// 不適合 Record:欄位多且有預設值,用 Builder 更清晰

8. 參考資料

  • GoF Design Patterns (1994), Ch. 3 — Builder
  • Effective Java 3rd Ed., Item 2 — Consider a builder when faced with many constructor parameters
  • Project Lombok documentation — @Builder

留言討論