Builder和Setter

1
package com.shai.builder02;
2

3
/**
4
 * Builder 模式 vs 普通 setter 写法对比
5
 *
6
 * <p>本类通过同一个场景（构建 HttpRequest）展示两种写法的本质差异。
7
 */
8
public class BuilderVsSetterComparison {
9

10
    // =========================================================================
11
    // 方式一：传统 setter 写法
12
    // =========================================================================
13

14
    /**
15
     * 传统 setter 写法的 HttpRequest（可变对象）
16
     *
17
     * <p>问题：
18
     * <ol>
19
     *   <li><b>对象可变</b>：build 完之后任何人都能继续调用 setter 修改状态，线程不安全</li>
20
     *   <li><b>无法保证完整性</b>：调用方可能忘记设置必填字段，编译器不报错，运行时才崩</li>
21
     *   <li><b>校验分散</b>：每个 setter 各自校验，或者根本没有校验，逻辑散落各处</li>
22
     *   <li><b>顺序无约束</b>：setter 可以任意顺序调用，无法表达"先设置 A 才能设置 B"的依赖关系</li>
23
     *   <li><b>无法做组合操作</b>：jsonBody() 需要同时设置 body + Content-Type，setter 做不到原子性</li>
24
     * </ol>
25
     */
26
    static class MutableHttpRequest {
27
        private String method;
28
        private String url;
29
        private String body;
30
        private String contentType;
31
        private int timeoutMs;
32

33
        // setter 只是简单赋值，无法做组合操作
34
        public void setMethod(String method) { this.method = method; }
35
        public void setUrl(String url) { this.url = url; }
36
        public void setBody(String body) { this.body = body; }
37
        public void setContentType(String contentType) { this.contentType = contentType; }
38
        public void setTimeoutMs(int timeoutMs) { this.timeoutMs = timeoutMs; }
39

40
        @Override
41
        public String toString() {
42
            return "MutableHttpRequest{method=" + method + ", url=" + url
43
                    + ", body=" + body + ", contentType=" + contentType
44
                    + ", timeoutMs=" + timeoutMs + "}";
45
        }
46
    }
47

48
    // =========================================================================
49
    // 方式二：Builder 写法（见 HttpRequest.java）
50
    // =========================================================================
51
    //
52
    // Builder 的核心价值不是"链式调用好看"，而是：
53
    //
54
    // 1. 【不可变对象】build() 之后字段全是 final，任何人无法修改，天然线程安全
55
    //
56
    // 2. 【构造完整性保证】必填参数放在 Builder 构造方法里，编译器强制传入
57
    //    new Builder("GET", "https://...") ← 不传就编译报错
58
    //
59
    // 3. 【集中校验 + 组合操作】
60
    //    jsonBody(json) 一次调用同时完成：
61
    //      - 设置 body
62
    //      - 自动追加 Content-Type 头
63
    //    setter 写法需要调用方自己记得同时调两个 setter，容易漏
64
    //
65
    // 4. 【单位/格式转换封装在 Builder 内部】
66
    //    timeoutSeconds(30) → 内部换算为 30000ms，调用方不需要关心单位
67
    //    setter 写法：setTimeoutMs(30 * 1000) ← 调用方自己算，容易出错
68
    //
69
    // 5. 【build() 做最终整体校验】
70
    //    POST 必须有 body，这个规则只在 build() 里写一次，
71
    //    setter 写法无法在"所有字段都设置完之后"做整体校验
72
    //
73
    // 6. 【自动生成派生字段】
74
    //    build() 自动生成 requestId、createdAt，
75
    //    setter 写法需要调用方手动设置，或者在某个 init() 方法里，容易忘
76

77
    public static void main(String[] args) {
78
        System.out.println("=== 方式一：setter 写法（问题演示）===");
79

80
        MutableHttpRequest req1 = new MutableHttpRequest();
81
        req1.setMethod("POST");
82
        req1.setUrl("https://api.example.com/users");
83
        req1.setBody("{\"username\":\"shai\"}");
84
        // 问题1：调用方必须自己记得同时设置 Content-Type，容易漏
85
        req1.setContentType("application/json");
86
        // 问题2：调用方自己换算单位，容易出错
87
        req1.setTimeoutMs(30 * 1000);
88
        // 问题3：build 完之后还能继续修改，破坏对象状态
89
        req1.setMethod("DELETE"); // 随时可以改，不安全
90
        System.out.println(req1);
91

92
        System.out.println("\n=== 方式二：Builder 写法（HttpRequest）===");
93

94
        HttpRequest req2 = HttpRequest
95
                .newRequest("POST", "https://api.example.com/users")
96
                // jsonBody 一次调用同时设置 body + Content-Type，原子操作
97
                .jsonBody("{\"username\":\"shai\"}")
98
                // 传秒，内部自动换算毫秒
99
                .timeoutSeconds(30)
100
                // build() 自动生成 requestId 和 createdAt
101
                .build();
102
        // req2 的字段全是 final，build 之后无法修改，安全
103
        System.out.println(req2);
104
    }
105
}

1
package com.shai.builder02;
2

3
import java.time.LocalDateTime;
4
import java.time.format.DateTimeFormatter;
5
import java.util.ArrayList;
6
import java.util.Collections;
7
import java.util.List;
8

9
/**
10
 * Builder 进阶示例：HttpRequest 构建器
11
 *
12
 * <p>演示 Builder 中不只是简单 set，还包含：
13
 * <ul>
14
 *   <li>参数校验（URL 格式、超时范围）</li>
15
 *   <li>方法调用（添加 Header、添加 QueryParam）</li>
16
 *   <li>条件逻辑（自动追加 Content-Type、自动生成 RequestId）</li>
17
 *   <li>格式转换（超时单位换算、URL 拼接 QueryString）</li>
18
 *   <li>build() 中的最终校验与组装</li>
19
 * </ul>
20
 */
21
public class HttpRequest {
22

23
    private final String method;
24
    private final String url;
25
    private final List<String> headers;
26
    private final String body;
27
    private final int timeoutMs;
28
    private final String requestId;
29
    private final LocalDateTime createdAt;
30

31
    private HttpRequest(Builder builder) {
32
        this.method = builder.method;
33
        this.url = builder.buildUrl();
34
        this.headers = Collections.unmodifiableList(builder.headers);
35
        this.body = builder.body;
36
        this.timeoutMs = builder.timeoutMs;
37
        this.requestId = builder.requestId;
38
        this.createdAt = builder.createdAt;
39
    }
40

41
    @Override
42
    public String toString() {
43
        DateTimeFormatter fmt = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss");
44
        return "\n=== HttpRequest ===" +
45
                "\n  requestId : " + requestId +
46
                "\n  createdAt : " + createdAt.format(fmt) +
47
                "\n  method    : " + method +
48
                "\n  url       : " + url +
49
                "\n  headers   : " + headers +
50
                "\n  body      : " + body +
51
                "\n  timeoutMs : " + timeoutMs + " ms";
52
    }
53

54
    // -----------------------------------------------------------------------
55
    // Builder
56
    // -----------------------------------------------------------------------
57

58
    public static Builder newRequest(String method, String baseUrl) {
59
        return new Builder(method, baseUrl);
60
    }
61

62
    public static final class Builder {
63

64
        private final String method;
65
        private final String baseUrl;
66
        private final List<String> queryParams = new ArrayList<>();
67
        private final List<String> headers = new ArrayList<>();
68
        private String body;
69
        private int timeoutMs = 5_000;
70
        private String requestId;
71
        private LocalDateTime createdAt;
72

73
        private Builder(String method, String baseUrl) {
74
            if (method == null || method.isBlank()) {
75
                throw new IllegalArgumentException("HTTP method 不能为空");
76
            }
77
            if (baseUrl == null || !baseUrl.startsWith("http")) {
78
                throw new IllegalArgumentException("baseUrl 必须以 http/https 开头，当前值：" + baseUrl);
79
            }
80
            this.method = method.toUpperCase();
81
            this.baseUrl = baseUrl;
82
        }
83

84
        /**
85
         * 添加请求头（key: value 格式）
86
         * Builder 内部做格式化，调用方只需传 key/value
87
         */
88
        public Builder header(String key, String value) {
89
            if (key == null || key.isBlank()) {
90
                throw new IllegalArgumentException("Header key 不能为空");
91
            }
92
            // 方法调用：格式化后加入列表
93
            headers.add(key.trim() + ": " + (value == null ? "" : value.trim()));
94
            return this;
95
        }
96

97
        /**
98
         * 添加 Query 参数（自动 URL 编码拼接）
99
         */
100
        public Builder queryParam(String key, Object value) {
101
            if (key != null && !key.isBlank()) {
102
                // 方法调用：转字符串并追加
103
                queryParams.add(key + "=" + value);
104
            }
105
            return this;
106
        }
107

108
        /**
109
         * 设置 JSON Body，同时自动追加 Content-Type 头
110
         * 条件逻辑：有 body 才加 Content-Type
111
         */
112
        public Builder jsonBody(String json) {
113
            this.body = json;
114
            // 条件逻辑：自动追加 Content-Type
115
            header("Content-Type", "application/json;charset=UTF-8");
116
            return this;
117
        }
118

119
        /**
120
         * 设置超时（秒），Builder 内部换算为毫秒
121
         * 格式转换：秒 → 毫秒
122
         */
123
        public Builder timeoutSeconds(int seconds) {
124
            if (seconds <= 0 || seconds > 300) {
125
                throw new IllegalArgumentException("超时时间必须在 1~300 秒之间，当前值：" + seconds);
126
            }
127
            // 单位换算
128
            this.timeoutMs = seconds * 1_000;
129
            return this;
130
        }
131

132
        /**
133
         * 手动指定 RequestId；若不调用，build() 时自动生成
134
         */
135
        public Builder requestId(String requestId) {
136
            this.requestId = requestId;
137
            return this;
138
        }
139

140
        /**
141
         * 组装最终 URL（baseUrl + QueryString）
142
         */
143
        private String buildUrl() {
144
            if (queryParams.isEmpty()) {
145
                return baseUrl;
146
            }
147
            return baseUrl + "?" + String.join("&", queryParams);
148
        }
149

150
        /**
151
         * 最终构建：自动生成 requestId、createdAt，并做整体校验
152
         */
153
        public HttpRequest build() {
154
            // 自动生成 requestId（若未手动指定）
155
            if (requestId == null || requestId.isBlank()) {
156
                requestId = "REQ-" + System.currentTimeMillis();
157
            }
158
            // 自动记录创建时间
159
            createdAt = LocalDateTime.now();
160

161
            // 整体校验：POST/PUT 必须有 body
162
            if (("POST".equals(method) || "PUT".equals(method)) && (body == null || body.isBlank())) {
163
                throw new IllegalStateException(method + " 请求必须提供 body");
164
            }
165

166
            return new HttpRequest(this);
167
        }
168
    }
169

170
    // -----------------------------------------------------------------------
171
    // 演示入口
172
    // -----------------------------------------------------------------------
173

174
    public static void main(String[] args) {
175
        // 示例 1：GET 请求，带 QueryParam 和自定义 Header
176
        HttpRequest getRequest = HttpRequest
177
                .newRequest("GET", "https://api.example.com/users")
178
                .queryParam("page", 1)
179
                .queryParam("size", 20)
180
                .queryParam("keyword", "shai")
181
                .header("Authorization", "Bearer token-abc123")
182
                .header("Accept", "application/json")
183
                .timeoutSeconds(10)
184
                .build();
185

186
        System.out.println(getRequest);
187

188
        // 示例 2：POST 请求，带 JSON Body（自动追加 Content-Type）
189
        HttpRequest postRequest = HttpRequest
190
                .newRequest("POST", "https://api.example.com/users")
191
                .header("Authorization", "Bearer token-abc123")
192
                .jsonBody("{\"username\":\"shai\",\"email\":\"[email protected]\"}")
193
                .timeoutSeconds(30)
194
                .requestId("MY-REQ-001")
195
                .build();
196

197
        System.out.println(postRequest);
198
    }
199
}