Java 驗證碼組件 Kaptcha 整合 Spring MVC 完整指南

依賴引入

<dependency>
    <groupId>com.github.penggle</groupId>
    <artifactId>kaptcha</artifactId>
    <version>2.3.2</version> <!-- 現代維護版本 -->
</dependency>

注意： 原 com.google.code.kaptcha 已停止維護，建議使用社區 Fork 版 com.github.penggle:kaptcha，API 完全相容。

Spring Boot 自動配置 (推薦，零 XML)

application.yml

kaptcha:
  border: no
  border.thickness: 0
  textproducer:
    font.color: black
    font.size: 35
    char.length: 4
    char.string: "0123456789"
    font.names: "Arial,Courier"
    char.space: 10
  image.width: 150
  image.height: 50
  background.clear.from: "255,255,255"
  background.clear.to: "255,255,255"
  noise.impl: "com.google.code.kaptcha.impl.NoNoise"
  session.key: "KAPTCHA_SESSION_KEY" # Session 屬性名

Spring Boot 會自動註冊 KaptchaServlet 至 /kaptcha.jpg

傳統 Spring MVC XML 配置 (web.xml)

<servlet>
    <servlet-name>Kaptcha</servlet-name>
    <servlet-class>com.google.code.kaptcha.servlet.KaptchaServlet</servlet-class>
    <init-param>
        <param-name>kaptcha.border</param-name>
        <param-value>no</param-value>
    </init-param>
    <init-param>
        <param-name>kaptcha.textproducer.char.length</param-name>
        <param-value>4</param-value>
    </init-param>
    <init-param>
        <param-name>kaptcha.textproducer.font.size</param-name>
        <param-value>35</param-value>
    </init-param>
    <init-param>
        <param-name>kaptcha.image.width</param-name>
        <param-value>150</param-value>
    </init-param>
    <init-param>
        <param-name>kaptcha.image.height</param-name>
        <param-value>50</param-value>
    </init-param>
    <init-param>
        <param-name>kaptcha.textproducer.char.string</param-name>
        <param-value>0123456789</param-value>
    </init-param>
    <init-param>
        <param-name>kaptcha.noise.impl</param-name>
        <param-value>com.google.code.kaptcha.impl.NoNoise</param-value>
    </init-param>
    <!-- 更多參數參考 Kaptcha 官方文檔 -->
</servlet>
<servlet-mapping>
    <servlet-name>Kaptcha</servlet-name>
    <url-pattern>/kaptcha.jpg</url-pattern>
</servlet-mapping>

前端頁面整合

<img id="captchaImg" src="/kaptcha.jpg" width="150" height="50" 
     style="cursor:pointer; vertical-align:middle;" 
     title="點擊刷新" alt="驗證碼" />
<input type="text" name="captcha" placeholder="輸入驗證碼" />

<script>
    document.getElementById('captchaImg').onclick = function() {
        this.src = '/kaptcha.jpg?' + Date.now(); // 防緩存
    };
</script>

後端驗證 (Controller)

@PostMapping("/login")
public Result login(@RequestParam String username,
                    @RequestParam String password,
                    @RequestParam String captcha,
                    HttpSession session) {
    
    String expected = (String) session.getAttribute(
        com.google.code.kaptcha.Constants.KAPTCHA_SESSION_KEY);
    
    if (expected == null || !expected.equalsIgnoreCase(captcha)) {
        return Result.error("驗證碼錯誤或已過期");
    }
    // 驗證通過，移除防重放
    session.removeAttribute(com.google.code.kaptcha.Constants.KAPTCHA_SESSION_KEY);
    
    // 後續業務邏輯...
    return Result.ok();
}

進階客製化

1. 自定義字符集 (中文/字母/符號)

kaptcha:
  textproducer:
    char.string: "ABCDEFGHJKLMNPQRSTUVWXYZ23456789" # 排除易混淆字符
    char.length: 5

2. 自定義文字渲染器 (繁體中文/藝術字)

@Bean
public DefaultKaptcha customKaptcha() {
    DefaultKaptcha kaptcha = new DefaultKaptcha();
    Properties props = new Properties();
    props.setProperty("kaptcha.textproducer.impl", "com.example.ChineseTextProducer");
    kaptcha.setConfig(new Config(props));
    return kaptcha;
}

3. 算術驗證碼 (如 "12 + 5 = ?")

public class MathTextProducer implements TextProducer {
    @Override
    public String getText() {
        int a = (int)(Math.random() * 20) + 1;
        int b = (int)(Math.random() * 20) + 1;
        return a + " + " + b + " = ?"; // Session 需存儲答案 a+b
    }
    @Override
    public String getText(String s) { return getText(); }
}

常見問題與解決

安全性建議

• **驗證後立即移除 Session 值** 防止重放攻擊
• **限制嘗試次數** (如 5 次鎖定 15 分鐘)
• **關鍵操作 (登入、支付、改密) 必須驗證**
• **考慮升級為圖形驗證 (滑塊/點選/行為分析)** 以對抗 AI 識別

結語

Kaptcha 作為輕量級驗證碼方案，整合 Spring 極其簡單。生產環境請注意：**字符集去混淆、Session 及時清理、失敗次數限制、必要時升級更強驗證碼**。Spring Boot 專案僅需引入依賴 + YAML 配置即可零代碼接入。