How to Integrate EasyCaptcha with Spring Boot 3: A Complete Guide

Captcha is widely used to protect systems from automated attacks. This article introduces the open‑source EasyCaptcha library, which supports five captcha types and demonstrates how to use it in a Spring Boot 3.5.0 application.

Supported Captcha Types

The library can generate arithmetic, Chinese, GIF, PNG, and font‑based captchas. Example images are shown below.

Adding the Dependency

<dependency>
  <groupId>com.github.whvcse</groupId>
  <artifactId>easy-captcha</artifactId>
  <version>1.6.2</version>
</dependency>

You can also download the JAR directly from the GitHub repository:

https://github.com/ele-admin/EasyCaptcha

Basic Usage

Creating different captcha objects and outputting the image:

public class Test {
  public static void main(String[] args) throws Exception {
    // PNG type
    SpecCaptcha captcha = new SpecCaptcha(130, 48);
    captcha.text(); // get characters
    captcha.textChar(); // get character array
    // Output to file
    captcha.out(Files.newOutputStream(Path.of("e:/captcha.png"), StandardOpenOption.CREATE_NEW));
  }
}

For arithmetic captchas, len defines the number of operands (default two). text() returns the result of the expression, which should be stored in the session for verification.

Character Type and Font Settings

SpecCaptcha captcha = new SpecCaptcha(130, 48, 5);
captcha.setCharType(Captcha.TYPE_ONLY_NUMBER); // numeric only
captcha.setFont(Captcha.FONT_1); // built‑in font
// or custom font
captcha.setFont(new Font("楷体", Font.PLAIN, 28));

Base64 Output

SpecCaptcha specCaptcha = new SpecCaptcha(130, 48, 5);
String base64 = specCaptcha.toBase64(); // includes data:image/png;base64,
String base64NoHeader = specCaptcha.toBase64(""); // without header

Integrating with Spring Boot

A controller that generates a GIF captcha, stores the verification code in Redis for five minutes, and returns the image (or Base64) to the front end:

@RestController
public class CaptchaController {
  private final StringRedisTemplate stringRedisTemplate;
  public CaptchaController(StringRedisTemplate stringRedisTemplate) {
    this.stringRedisTemplate = stringRedisTemplate;
  }

  @GetMapping("/captcha")
  public void captcha(HttpServletRequest request, HttpServletResponse response) throws Exception {
    GifCaptcha captcha = new GifCaptcha(130, 48);
    captcha.setCharType(Captcha.TYPE_ONLY_CHAR);
    String verCode = captcha.text().toLowerCase();
    String key = request.getSession().getId();
    stringRedisTemplate.opsForValue().set(key, verCode, 5, TimeUnit.MINUTES);
    captcha.out(response.getOutputStream());
  }

  @GetMapping("/login")
  public ResponseEntity<?> login(String username, String password, String code, HttpServletRequest request) {
    String redisCode = stringRedisTemplate.opsForValue().get(request.getSession().getId());
    if (code == null || !redisCode.equalsIgnoreCase(code.trim())) {
      return ResponseEntity.ok("验证码错误");
    }
    return ResponseEntity.ok("登录成功");
  }
}

The article originally ends with a call for likes and shares, which has been omitted as non‑core content.