1. 项目概述与核心价值

最近在重构一个老项目的登录模块，客户明确要求增加图形验证码功能，以提升安全性，抵御自动化脚本的恶意登录尝试。这其实是一个在WEB开发中非常经典且高频的需求，无论是初创公司的小应用，还是中大型企业的管理系统，登录环节的验证码几乎是标配。这个需求看似简单，前端画个图，后端生成并校验一下，但真要把它做得健壮、安全、用户体验好，里面有不少细节需要抠。

这个项目采用了典型的前后端分离架构：前端使用最基础的HTML、CSS和JavaScript（为了普适性，不依赖特定框架），后端则是目前Java领域最流行的Spring Boot。我们将实现一个完整的流程：用户打开登录页，前端从后端获取一个随机的验证码图片并显示；用户填写用户名、密码和看到的验证码后提交；后端需要验证验证码是否正确且在有效期内，然后再去校验用户凭证。整个过程会涉及到前后端的数据交互、Session或Token的状态管理、验证码的生成与存储策略等核心问题。接下来，我会把这个功能的实现拆解开来，不仅告诉你每一步怎么写代码，更会重点分享我在实际项目中踩过的坑和总结的最佳实践，比如如何防止验证码被绕过、如何设计合理的过期时间、以及如何让验证码对用户更友好。

2. 技术方案选型与整体设计思路

2.1 为什么选择“服务器端生成，Session存储”方案？

验证码的实现方案有很多，比如前端生成、后端校验，或者完全由后端生成和校验。经过多次项目实践，我强烈推荐并采用“服务器端生成，服务器端存储并校验”的方案。具体来说，就是由Spring Boot后端生成验证码图片和对应的正确文本，将文本存储在服务器端的Session中（或分布式缓存里），同时将图片以Base64编码或图片流的方式返回给前端。用户提交时，后端比对提交的验证码和Session中存储的是否一致。

这么做的核心理由有三个：

1. 安全性是首要考量：验证码的核心目的是增加机器识别的难度。如果让前端（JavaScript）生成验证码，那么验证码的答案要么硬编码在JS里（形同虚设），要么需要从后端获取答案，这反而增加了逻辑复杂性和潜在的安全风险。由后端完全控制生成和存储，密钥（正确答案）不泄露到客户端，从根本上更安全。
2. 状态管理清晰：使用HttpSession来关联一次验证码请求和校验请求是最自然的方式。Session ID通过Cookie（或Token）在每次请求中自动携带，后端可以轻松地通过同一个Session来存取验证码文本，无需前端额外传递标识符。
3. 兼容性与可控性强：生成图片、添加干扰线、扭曲变形等抗识别操作，在后端用Java库（如Graphics2D）实现起来功能强大且成熟。同时，验证码的过期时间、尝试次数限制等安全策略，在后端也更容易实施和统一管理。

注意：在分布式或微服务架构下，Session需要共享（例如存入Redis），否则用户请求可能被负载均衡到不同服务器，导致找不到对应的Session。本项目假设为单机或已配置Session共享的环境。

2.2 前端与后端的职责划分

一个清晰的职责划分能让代码更易维护：

• 前端职责：

  • 提供登录表单界面（用户名、密码、验证码输入框、验证码图片）。
  • 向特定后端接口发起请求，获取验证码图片并动态显示。
  • 用户点击验证码图片时，刷新验证码。
  • 提交登录表单时，将用户名、密码和用户输入的验证码一并发送给后端。
  • 处理后端返回的登录结果（成功跳转或失败提示）。

• 后端职责：

  • 提供一个GET接口，用于生成验证码。该接口生成随机文本、创建图片，将文本存入当前Session，并将图片以image/png格式输出。
  • 提供一个POST接口，用于处理登录请求。该接口首先从Session中取出之前存储的验证码文本，与用户提交的进行比对（通常忽略大小写）。如果验证码错误或过期，直接返回错误，不再进行数据库用户名密码校验。如果验证码正确，则继续校验用户名和密码。
  • 管理验证码的生命周期（生成、存储、校验、失效）。

2.3 核心工具与依赖

• 后端（Spring Boot）：
  • spring-boot-starter-web: 提供Web MVC支持。
  • Java AWT / Graphics2D: Java标准库，用于绘制验证码图片。无需额外依赖。
  • （可选）spring-boot-starter-data-redis: 如果做分布式Session共享。
• 前端：纯原生技术栈，无需任何框架或构建工具，仅需浏览器支持。

这个方案的优势在于依赖极简，原理清晰，非常适合作为理解前后端交互和基础安全机制的入门与实践项目。

3. 后端实现：Spring Boot验证码生成与校验

3.1 创建验证码生成工具类

首先，我们在后端创建一个工具类CaptchaUtil，它的任务是生成随机字符串以及对应的图片。我将一个经过多次项目打磨的版本分享出来，它包含了随机字符、颜色、干扰线和扭曲等常见抗识别特性。

import javax.imageio.ImageIO; import java.awt.*; import java.awt.geom.AffineTransform; import java.awt.image.BufferedImage; import java.io.ByteArrayOutputStream; import java.io.IOException; import java.util.Base64; import java.util.Random; public class CaptchaUtil { // 验证码字符集，去掉容易混淆的字符如0, O, 1, I, l等 private static final String CHAR_SET = "23456789abcdefghjkmnpqrstuvwxyzABCDEFGHJKMNPQRSTUVWXYZ"; private static final int CODE_LENGTH = 4; // 验证码长度 private static final int IMG_WIDTH = 120; private static final int IMG_HEIGHT = 40; private static final Random random = new Random(); /** * 生成随机验证码文本 */ public static String generateRandomCode() { StringBuilder sb = new StringBuilder(CODE_LENGTH); for (int i = 0; i < CODE_LENGTH; i++) { int index = random.nextInt(CHAR_SET.length()); sb.append(CHAR_SET.charAt(index)); } return sb.toString(); } /** * 根据验证码文本生成图片，并返回Base64编码字符串 * @param code 验证码文本 * @return Base64编码的图片字符串（如 "data:image/png;base64,iVBORw0KGgoAAAAN..."） */ public static String generateImageBase64(String code) throws IOException { BufferedImage image = new BufferedImage(IMG_WIDTH, IMG_HEIGHT, BufferedImage.TYPE_INT_RGB); Graphics2D g2d = image.createGraphics(); // 1. 设置背景色（浅色） g2d.setColor(Color.WHITE); g2d.fillRect(0, 0, IMG_WIDTH, IMG_HEIGHT); // 2. 设置字体并绘制验证码文本 Font font = new Font("Arial", Font.BOLD | Font.ITALIC, 30); g2d.setFont(font); for (int i = 0; i < code.length(); i++) { // 为每个字符设置随机颜色 g2d.setColor(getRandomColor()); // 对每个字符进行轻微随机旋转和位移，增加识别难度 AffineTransform affine = new AffineTransform(); affine.rotate(Math.toRadians(random.nextInt(30) - 15), 0, 0); double scale = 0.8 + random.nextDouble() * 0.4; // 缩放0.8~1.2 affine.scale(scale, scale); Font rotatedFont = font.deriveFont(affine); g2d.setFont(rotatedFont); int x = 20 + i * 25; // 字符水平位置 int y = 30 + random.nextInt(10); // 字符垂直位置轻微抖动 g2d.drawString(String.valueOf(code.charAt(i)), x, y); } // 3. 添加干扰线 g2d.setColor(Color.LIGHT_GRAY); for (int i = 0; i < 5; i++) { int x1 = random.nextInt(IMG_WIDTH); int y1 = random.nextInt(IMG_HEIGHT); int x2 = random.nextInt(IMG_WIDTH); int y2 = random.nextInt(IMG_HEIGHT); g2d.drawLine(x1, y1, x2, y2); } // 4. 添加噪点 for (int i = 0; i < 50; i++) { int x = random.nextInt(IMG_WIDTH); int y = random.nextInt(IMG_HEIGHT); image.setRGB(x, y, getRandomColor().getRGB()); } g2d.dispose(); // 将图片转换为Base64 ByteArrayOutputStream baos = new ByteArrayOutputStream(); ImageIO.write(image, "png", baos); String base64String = Base64.getEncoder().encodeToString(baos.toByteArray()); return "data:image/png;base64," + base64String; } private static Color getRandomColor() { // 避免颜色过浅，设置一个下限 int r = 30 + random.nextInt(180); int g = 30 + random.nextInt(180); int b = 30 + random.nextInt(180); return new Color(r, g, b); } }

关键点解析：

• 字符集选择：去除了0/O、1/I/l等容易混淆的字符，提升用户体验。
• 图形扭曲：使用AffineTransform对每个字符进行随机旋转和缩放，这是抵御简单OCR识别的重要手段。
• 干扰元素：干扰线和随机噪点能有效破坏图片的规律性。
• Base64输出：将图片直接编码成Base64字符串返回，前端可以直接用在<img>标签的src属性中，避免了额外的图片文件请求，简化了前端逻辑。

3.2 设计验证码相关的控制器(Controller)

接下来，我们创建两个核心的API接口。

import org.springframework.web.bind.annotation.*; import javax.servlet.http.HttpServletRequest; import javax.servlet.http.HttpSession; import java.io.IOException; import java.util.HashMap; import java.util.Map; @RestController @RequestMapping("/api/captcha") public class CaptchaController { /** * 获取验证码图片 * GET /api/captcha/image */ @GetMapping("/image") public Map<String, String> getCaptchaImage(HttpServletRequest request) throws IOException { // 1. 生成随机验证码文本 String code = CaptchaUtil.generateRandomCode(); // 2. 将验证码文本存入Session HttpSession session = request.getSession(); session.setAttribute("captcha", code); // 可以同时存入生成时间，用于后续过期校验 session.setAttribute("captcha_time", System.currentTimeMillis()); // 3. 生成图片并返回Base64 String imageBase64 = CaptchaUtil.generateImageBase64(code); Map<String, String> result = new HashMap<>(); result.put("image", imageBase64); // 前端img.src直接使用 // 实际项目中，除非调试，否则不应将code传回前端 // result.put("code", code); return result; } /** * 校验验证码（通常不单独提供，集成在登录接口中） * 这里为了演示分离出来 * POST /api/captcha/verify */ @PostMapping("/verify") public Map<String, Object> verifyCaptcha(@RequestParam String userInput, HttpServletRequest request) { HttpSession session = request.getSession(false); // false表示如果session不存在则不创建 Map<String, Object> result = new HashMap<>(); if (session == null) { result.put("success", false); result.put("message", "验证码已过期，请刷新"); return result; } String savedCode = (String) session.getAttribute("captcha"); Long generateTime = (Long) session.getAttribute("captcha_time"); // 立即清除session中的验证码，确保一次性使用 session.removeAttribute("captcha"); session.removeAttribute("captcha_time"); if (savedCode == null || generateTime == null) { result.put("success", false); result.put("message", "验证码已失效，请刷新"); return result; } // 校验过期时间（例如5分钟） long expireTime = 5 * 60 * 1000; // 5分钟 if (System.currentTimeMillis() - generateTime > expireTime) { result.put("success", false); result.put("message", "验证码已过期，请刷新"); return result; } // 校验验证码文本（忽略大小写） if (!savedCode.equalsIgnoreCase(userInput)) { result.put("success", false); result.put("message", "验证码错误"); return result; } result.put("success", true); result.put("message", "验证码正确"); return result; } }

关键点解析：

• Session存储：将验证码文本和生成时间戳存入当前HttpSession。Session由Servlet容器管理，通过Cookie中的JSESSIONID关联。
• 一次性使用：在verifyCaptcha方法中，一旦读取了验证码，无论对错，都立即调用session.removeAttribute将其清除。这是防止“验证码重放攻击”的关键——同一个验证码只能被校验一次。
• 过期校验：除了校验文本是否正确，还校验生成时间是否在允许的有效期内（如5分钟）。这避免了验证码被长期保留并尝试破解。
• 忽略大小写：equalsIgnoreCase让用户体验更好，用户无需关心大小写。从安全角度看，验证码的复杂度（长度、字符集）才是关键，大小写敏感性带来的安全提升有限，却会损害体验。

3.3 集成验证码校验的登录接口

最后，我们将验证码校验逻辑整合到实际的登录接口中。这里假设你已有一个UserService来处理用户名密码的认证。

import org.springframework.beans.factory.annotation.Autowired; import org.springframework.web.bind.annotation.*; import javax.servlet.http.HttpServletRequest; import javax.servlet.http.HttpSession; import java.util.HashMap; import java.util.Map; @RestController @RequestMapping("/api/auth") public class AuthController { @Autowired private UserService userService; // 假设的用户服务 @PostMapping("/login") public Map<String, Object> login(@RequestBody LoginForm loginForm, HttpServletRequest request) { Map<String, Object> result = new HashMap<>(); // --- 第一步：验证码校验 --- HttpSession session = request.getSession(false); if (session == null) { return buildErrorResult("会话无效，请刷新页面"); } String savedCode = (String) session.getAttribute("captcha"); Long generateTime = (Long) session.getAttribute("captcha_time"); session.removeAttribute("captcha"); // 使用后立即清除 session.removeAttribute("captcha_time"); if (savedCode == null || generateTime == null) { return buildErrorResult("验证码已失效，请刷新"); } // 过期校验 if (System.currentTimeMillis() - generateTime > 5 * 60 * 1000) { return buildErrorResult("验证码已过期，请刷新"); } // 文本校验 if (!savedCode.equalsIgnoreCase(loginForm.getCaptcha())) { return buildErrorResult("验证码错误"); } // --- 验证码校验通过 --- // --- 第二步：用户名密码校验 --- boolean authSuccess = userService.authenticate(loginForm.getUsername(), loginForm.getPassword()); if (!authSuccess) { return buildErrorResult("用户名或密码错误"); } // --- 登录成功，创建用户会话 --- // 清除旧的验证码session，创建新的用户登录session session.invalidate(); HttpSession newSession = request.getSession(true); newSession.setAttribute("user", loginForm.getUsername()); // 可以设置session超时时间等 result.put("success", true); result.put("message", "登录成功"); result.put("user", loginForm.getUsername()); // 可以返回一个Token用于后续接口认证 // result.put("token", generateToken(...)); return result; } private Map<String, Object> buildErrorResult(String message) { Map<String, Object> result = new HashMap<>(); result.put("success", false); result.put("message", message); return result; } // 登录表单数据接收类 public static class LoginForm { private String username; private String password; private String captcha; // getters and setters ... } }

实操心得：在登录接口中，验证码校验必须放在用户名密码校验之前。这是一个重要的安全实践。如果先查数据库验证用户名密码，攻击者可以通过枚举常见用户名来探测哪些账号是存在的（用户名枚举攻击）。先校验验证码，即使验证码被破解（概率低），也能为系统增加一层缓冲。此外，验证码错误和用户名密码错误的返回信息可以保持一致（如“用户名、密码或验证码错误”），避免给攻击者透露过多系统状态信息。

4. 前端实现：动态交互与用户体验

后端API准备好后，前端的工作就是将它们串联起来，提供一个流畅的登录界面。

4.1 构建登录页面(HTML/CSS)

我们先创建一个简洁的登录页面login.html。

<!DOCTYPE html> <html lang="zh-CN"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>系统登录</title> <style> * { margin: 0; padding: 0; box-sizing: border-box; } body { font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif; background: linear-gradient(135deg, #f5f7fa 0%, #c3cfe2 100%); min-height: 100vh; display: flex; justify-content: center; align-items: center; padding: 20px; } .login-container { background-color: white; padding: 40px; border-radius: 12px; box-shadow: 0 10px 30px rgba(0, 0, 0, 0.1); width: 100%; max-width: 400px; } h2 { text-align: center; margin-bottom: 30px; color: #333; font-weight: 500; } .form-group { margin-bottom: 20px; } label { display: block; margin-bottom: 8px; color: #555; font-size: 14px; font-weight: 500; } input[type="text"], input[type="password"] { width: 100%; padding: 12px 15px; border: 1px solid #ddd; border-radius: 6px; font-size: 16px; transition: border-color 0.3s; } input:focus { outline: none; border-color: #4a90e2; box-shadow: 0 0 0 2px rgba(74, 144, 226, 0.2); } .captcha-group { display: flex; gap: 10px; align-items: flex-end; } .captcha-input { flex: 1; } .captcha-img-container { flex-shrink: 0; border: 1px solid #ddd; border-radius: 6px; overflow: hidden; cursor: pointer; height: 46px; /* 与输入框对齐 */ display: flex; align-items: center; justify-content: center; background-color: #f9f9f9; } #captchaImage { height: 100%; display: block; } .hint { font-size: 12px; color: #888; margin-top: 5px; text-align: center; } .btn-submit { width: 100%; padding: 14px; background-color: #4a90e2; color: white; border: none; border-radius: 6px; font-size: 16px; font-weight: 600; cursor: pointer; transition: background-color 0.3s; margin-top: 10px; } .btn-submit:hover { background-color: #3a7bc8; } .btn-submit:disabled { background-color: #a0c4f7; cursor: not-allowed; } .message { padding: 12px; border-radius: 6px; margin-top: 20px; font-size: 14px; text-align: center; display: none; } .message.error { background-color: #fee; color: #c33; border: 1px solid #fcc; } .message.success { background-color: #efffef; color: #2a7; border: 1px solid #cfc; } </style> </head> <body> <div class="login-container"> <h2>用户登录</h2> <form id="loginForm"> <div class="form-group"> <label for="username">用户名</label> <input type="text" id="username" name="username" placeholder="请输入用户名" required> </div> <div class="form-group"> <label for="password">密码</label> <input type="password" id="password" name="password" placeholder="请输入密码" required> </div> <div class="form-group"> <label for="captcha">验证码</label> <div class="captcha-group"> <input type="text" id="captcha" name="captcha" class="captcha-input" placeholder="请输入验证码" required maxlength="4"> <div class="captcha-img-container" id="captchaBox" title="点击刷新验证码"> <!-- 验证码图片将通过JS动态插入 --> <img id="captchaImage" src="" alt="验证码加载中"> </div> </div> <div class="hint">看不清？点击图片刷新</div> </div> <button type="submit" class="btn-submit" id="submitBtn">登录</button> </form> <div id="messageBox" class="message"></div> </div> <script src="login.js"></script> <!-- 引入外部JS --> </body> </html>

这个页面布局清晰，包含了用户名、密码、验证码输入框和验证码图片区域。验证码图片区域被设计成可点击的，用于刷新验证码。

4.2 实现前端交互逻辑(JavaScript)

现在创建核心的JavaScript文件login.js，它负责获取验证码、刷新验证码、处理表单提交。

// login.js document.addEventListener('DOMContentLoaded', function() { const captchaImage = document.getElementById('captchaImage'); const captchaBox = document.getElementById('captchaBox'); const loginForm = document.getElementById('loginForm'); const submitBtn = document.getElementById('submitBtn'); const messageBox = document.getElementById('messageBox'); // 后端API地址（根据实际部署地址修改） const API_BASE = 'http://localhost:8080/api'; const CAPTCHA_IMAGE_URL = `${API_BASE}/captcha/image`; const LOGIN_URL = `${API_BASE}/auth/login`; // 1. 页面加载时，首次获取验证码 fetchCaptcha(); // 2. 点击验证码图片区域，刷新验证码 captchaBox.addEventListener('click', fetchCaptcha); // 3. 处理表单提交 loginForm.addEventListener('submit', async function(event) { event.preventDefault(); // 阻止表单默认提交行为 const username = document.getElementById('username').value.trim(); const password = document.getElementById('password').value; const captcha = document.getElementById('captcha').value.trim(); // 简单的前端验证 if (!username || !password || !captcha) { showMessage('请填写所有字段', 'error'); return; } // 禁用提交按钮，防止重复提交 submitBtn.disabled = true; submitBtn.textContent = '登录中...'; try { const response = await fetch(LOGIN_URL, { method: 'POST', headers: { 'Content-Type': 'application/json', }, body: JSON.stringify({ username, password, captcha }), credentials: 'include' // 重要：发送Cookie（包含JSESSIONID） }); const result = await response.json(); if (result.success) { showMessage(`登录成功！欢迎 ${result.user}`, 'success'); // 登录成功后的操作，例如跳转到首页 // setTimeout(() => { window.location.href = '/dashboard'; }, 1500); console.log('登录成功，用户信息:', result); } else { showMessage(result.message || '登录失败', 'error'); // 登录失败，刷新验证码，让用户重新输入 fetchCaptcha(); document.getElementById('captcha').value = ''; // 清空验证码输入框 document.getElementById('captcha').focus(); // 聚焦到验证码输入框 } } catch (error) { console.error('登录请求失败:', error); showMessage('网络错误或服务器异常，请稍后重试', 'error'); } finally { // 恢复提交按钮状态 submitBtn.disabled = false; submitBtn.textContent = '登录'; } }); /** * 从后端获取验证码图片并显示 */ async function fetchCaptcha() { // 显示加载状态 captchaImage.alt = '正在加载验证码...'; captchaImage.src = ''; try { const response = await fetch(CAPTCHA_IMAGE_URL, { credentials: 'include' // 必须包含，以确保与登录接口使用同一个Session }); if (!response.ok) { throw new Error(`HTTP error! status: ${response.status}`); } const data = await response.json(); // 后端返回的 data.image 是完整的 data:image/png;base64,... 字符串 captchaImage.src = data.image; captchaImage.alt = '验证码图片'; // 清空输入框，给予用户提示 document.getElementById('captcha').value = ''; console.log('验证码已刷新'); } catch (error) { console.error('获取验证码失败:', error); captchaImage.alt = '验证码加载失败'; showMessage('验证码加载失败，请检查网络或刷新页面', 'error'); } } /** * 在页面上方显示提示信息 * @param {string} text 提示文本 * @param {string} type 类型 'success' 或 'error' */ function showMessage(text, type) { messageBox.textContent = text; messageBox.className = `message ${type}`; messageBox.style.display = 'block'; // 3秒后自动隐藏（成功信息可快些，错误信息可保留久些） const hideDelay = type === 'success' ? 1500 : 4000; setTimeout(() => { messageBox.style.display = 'none'; }, hideDelay); } });

关键点解析：

• credentials: 'include'：这是整个前后端联调中最容易出错的点。在fetch请求中设置这个选项，浏览器才会在请求中自动携带当前域名下的Cookie（对于我们这个例子，就是包含JSESSIONID的Cookie）。没有这个，前后端的Session就无法关联，后端在/api/auth/login接口中就通过request.getSession(false)获取不到之前存储验证码的Session，导致验证码校验永远失败。
• 用户体验优化：
  • 点击刷新：为验证码图片容器绑定点击事件，提升易用性。
  • 登录失败后自动刷新验证码：一旦登录失败（无论是验证码错还是密码错），立即调用fetchCaptcha()获取一个新的验证码。这是安全最佳实践，防止攻击者针对同一个验证码进行多次暴力尝试。
  • 焦点管理：验证码错误后，自动清空输入框并将焦点定位到验证码框，方便用户重新输入。
  • 按钮防重复提交：提交时禁用按钮并改变文字，请求结束后恢复，防止用户连续点击导致重复请求。
• 错误处理：对网络请求失败、服务器错误等进行了基本的捕获和用户提示，增强了健壮性。

5. 部署、测试与安全强化要点

5.1 项目运行与基础测试

1. 启动后端：将Spring Boot项目导入IDE（如IntelliJ IDEA）或使用Maven命令mvn spring-boot:run启动。默认端口通常是8080。
2. 运行前端：由于前端是纯静态文件，你可以直接用浏览器打开login.html文件。但请注意，如果HTML文件是通过file://协议打开的，某些浏览器（如Chrome）出于安全策略，对跨域请求中的credentials: 'include限制更严格，可能导致Cookie发送失败。
3. 解决跨域与Cookie问题（开发环境）：
   • 最佳实践：使用一个简单的HTTP服务器来提供前端页面。例如，在login.html所在目录下运行npx http-server -p 3000（需要Node.js环境），然后通过http://localhost:3000/login.html访问。
   • 后端配置CORS：在Spring Boot后端添加CORS配置，允许前端服务器的源（如http://localhost:3000）进行跨域请求，并允许携带凭证（Cookie）。

   import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.web.servlet.config.annotation.CorsRegistry; import org.springframework.web.servlet.config.annotation.WebMvcConfigurer; @Configuration public class WebConfig implements WebMvcConfigurer { @Override public void addCorsMappings(CorsRegistry registry) { registry.addMapping("/api/**") // 针对所有/api/开头的接口 .allowedOrigins("http://localhost:3000") // 你的前端服务器地址 .allowedMethods("GET", "POST", "PUT", "DELETE", "OPTIONS") .allowCredentials(true) // 允许携带Cookie .maxAge(3600); } }

4. 测试流程：
   • 打开登录页，应自动加载验证码图片。
   • 点击验证码图片，应能刷新。
   • 输入错误的验证码，点击登录，应提示“验证码错误”，并且验证码图片会自动刷新。
   • 输入正确的验证码但错误的密码，应提示“用户名或密码错误”，验证码也会刷新。
   • 输入正确的验证码和密码（假设你有一个测试用户），应提示“登录成功”。

5.2 进阶安全考量与优化

上面的实现是一个基础且可用的版本。但在生产环境中，还需要考虑更多安全加固措施：

1. 验证码复杂度与刷新策略：

   • 长度与字符集：4-6位字符是平衡安全与用户体验的常见选择。可以动态调整，在检测到频繁错误请求时，临时增加长度或使用更复杂的字符集（如中文）。
   • 刷新频率：除了用户点击，可以设置验证码的自动过期时间（如5分钟）。我们的代码已经实现了。

2. 防御暴力破解：

   • 尝试次数限制：在Session或Redis中记录针对某个Session或IP的验证码错误次数。例如，5分钟内连续错误5次，则锁定该Session/IP一段时间（如15分钟内禁止获取或验证验证码），或者要求输入更复杂的验证码（如滑动拼图、点选等）。
   • 接口限流：对/api/auth/login和/api/captcha/image接口实施限流（例如使用Spring Boot的Resilience4j或Sentinel），防止攻击者高频请求消耗资源。

3. 会话安全：

   • Session固定攻击防护：在用户登录成功后，我们使用了session.invalidate()并创建了新Session (request.getSession(true))。这非常重要，它防止了攻击者先获取一个带验证码的Session，然后诱骗用户使用这个Session登录，从而绕过验证码。
   • Token替代Session：对于纯RESTful API，可以考虑使用JWT等Token机制。此时，验证码的关联就不能用Session了。一个常见的方案是：生成验证码时，同时生成一个随机UUID作为captchaKey，将captchaKey: code存入Redis（设置过期时间）。将captchaKey返回给前端（可以放在响应头或JSON里）。前端提交登录时，需要同时提交captchaKey和用户输入的验证码。后端根据captchaKey从Redis中取出正确的验证码进行比对。

4. 验证码类型扩展：

   • 图形验证码对可访问性（如视障用户）不友好。可以考虑提供语音验证码作为备选方案。
   • 对于更高安全等级的场景，可以引入行为验证码，如谷歌的reCAPTCHA v2/v3、极验等，它们能更好地区分人和机器。

5. 日志与监控：

   • 记录验证码验证失败和登录失败的日志，包括时间、IP、Session ID、使用的验证码（可脱敏）等。这些日志对于分析攻击行为和进行安全审计至关重要。

5.3 常见问题排查实录

在实际开发和联调中，你可能会遇到以下问题：

• 问题1：验证码一直显示“验证码已失效”或“验证码错误”，但控制台没有Java异常。

  • 排查：首先检查浏览器开发者工具的“网络(Network)”选项卡。
    1. 查看获取验证码的GET /api/captcha/image请求是否成功，响应里是否有image字段。
    2. 查看该请求的响应头是否包含Set-Cookie: JSESSIONID=xxx。如果没有，说明后端Session创建可能有问题。
    3. 查看登录的POST /api/auth/login请求的请求头中是否包含了Cookie: JSESSIONID=xxx（与上一步的ID一致）。如果没有，检查前端fetch请求是否设置了credentials: 'include'。
    4. 检查后端CORS配置是否正确，特别是allowCredentials(true)是否设置。
  • 根本原因：前后端Session未成功关联。这是此类问题最常见的原因。

• 问题2：验证码图片显示为破碎图标或无法加载。

  • 排查：
    1. 检查CaptchaUtil.generateImageBase64方法生成的字符串是否以data:image/png;base64,开头。
    2. 检查浏览器控制台是否有关于图片格式的报错。
    3. 将后端返回的image字符串复制出来，在线Base64解码或直接放在浏览器地址栏看是否能显示图片。
  • 可能原因：图片生成过程中ImageIO.write抛出异常未被捕获，导致返回了异常的字符串或空字符串。

• 问题3：登录成功后，后续请求（如获取用户信息）又提示未登录。

  • 排查：检查登录成功后，后续的API请求是否也携带了Cookie（即设置了credentials: 'include'）。在前后端分离项目中，所有需要认证的请求都必须携带凭证。
  • 解决方案：确保所有需要会话的API请求都正确配置了凭证携带。或者，登录成功后后端返回一个Token（如JWT），前端将其存储在localStorage中，并在后续请求的Authorization头中携带，从而完全摆脱对Session的依赖。

• 问题4：在手机端或高DPI屏幕上，验证码图片显示模糊。

  • 解决方案：在CaptchaUtil中，将BufferedImage的宽度和高度按设备像素比进行倍增。例如，检测到高DPI屏幕，将IMG_WIDTH和IMG_HEIGHT乘以2，同时将字体大小和绘图坐标也相应缩放，最后生成一个高分辨率的图片。前端通过CSS设置img { width: 120px; height: 40px; }来固定显示尺寸，这样在高分屏上就会更清晰。

这个从零实现的验证码登录模块，涵盖了从原理到实践，从基础功能到安全优化的完整链条。它不仅是功能的堆砌，更是对WEB应用安全基础、前后端交互细节的一次深入实践。理解并处理好Session管理、CORS、凭证携带这些“细枝末节”，往往比实现功能本身更能体现一个开发者的功底。希望这份详细的拆解和实录，能帮助你扎实地掌握这个必备功能，并在自己的项目中游刃有余地应用和扩展。