Apache Commons Lang ToStringBuilder 使用指南：告別手寫 toString()

為什麼需要 ToStringBuilder？

• 手寫 toString() 繁瑣且易漏欄位
• 新增欄位需同步修改 toString()，維護成本高
• 格式不統一，除錯時難以閱讀
• ToStringBuilder 自動反射欄位，支援多種輸出風格，一行代碼搞定

Maven 依賴

<dependency>
    <groupId>org.apache.commons</groupId>
    <artifactId>commons-lang3</artifactId>
    <version>3.14.0</version> <!-- 請用最新版 -->
</dependency>

核心用法

import org.apache.commons.lang3.builder.ToStringBuilder;
import org.apache.commons.lang3.builder.ToStringStyle;

public class Person {
    private String name;
    private int age;
    private boolean smoker;
    private String[] hobbies;

    // 建構子、Getter/Setter 略...

    @Override
    public String toString() {
        return new ToStringBuilder(this, ToStringStyle.MULTI_LINE_STYLE)
                .append("name", name)
                .append("age", age)
                .append("smoker", smoker)
                .append("hobbies", hobbies)
                .toString();
    }
}

五大內建風格對比

假設物件：Person@182f0db[name=John Doe, age=33, smoker=false, hobbies=[read, swim]]

Person@182f0db[
  name=John Doe
  age=33
  smoker=false
  hobbies=[read, swim]
]

進階技巧

1. 反射自動檢測所有欄位 (含私有)

@Override
public String toString() {
    return ToStringBuilder.reflectionToString(this, ToStringStyle.MULTI_LINE_STYLE);
}

零配置，自動包含繼承鏈所有非 static、非 transient 欄位。

2. 自訂風格

ToStringStyle custom = new ToStringStyle() {
    {
        setArrayStart("[");
        setArrayEnd("]");
        setArraySeparator(", ");
        setFieldSeparator(" | ");
    }
};
return new ToStringBuilder(this, custom).append(...).toString();

3. 排除敏感欄位

return new ToStringBuilder(this, ToStringStyle.MULTI_LINE_STYLE)
    .append("username", username)
    .append("password", "******") // 手動遮罩
    .append("email", email)
    .toString();

4. 效能考量

• 反射版 (reflectionToString) 較慢，高頻呼叫場景建議手動 append
• 生產環境日誌建議關閉詳細 toString 或使用懶評估 (如 Log4j2 StringBuilder 延遲)

替代方案對比