Stop Hand‑Coding Captchas: Complete Spring Boot Guide from Custom Logic to Hutool

Captchas are the first line of defense in login, registration and password‑reset scenarios; without them, bots can easily breach APIs, while a poorly implemented captcha leads to redundant code, maintenance headaches, and rigid UI.

The article compares two solutions for Spring Boot projects:

Fully custom captcha generation (suitable for heavy customization).

Rapid integration using Hutool (the optimal choice for most projects).

Why Captchas Are Almost Indispensable

They distinguish humans from programs by combining random characters with interference elements, raising the cost of scripted attacks. Typical use cases include preventing brute‑force login, bulk account creation, credential stuffing during password reset, and confirming critical operations.

Approach 1: Custom Captcha Utility

When a project demands precise control over style, font, or interference rules, a hand‑written solution is unavoidable. The implementation follows these steps:

Generate random characters.

Draw background.

Draw interference lines.

Render characters.

Store the result in HttpSession.

Write the image to the response stream.

Project structure:

src/main/java
└── com
    └── icoderoad
        └── common
            └── util
                └── CaptchaCodeUtil.java

Key parts of CaptchaCodeUtil include random color generation, line drawing, character rendering, session storage, and JPEG output. The controller invokes the utility via a /captcha/custom endpoint, sets appropriate cache‑control headers, and streams the image.

This method offers full control but incurs high maintenance and limited extensibility.

Approach 2: Hutool Captcha Integration (Strongly Recommended)

To avoid reinventing the wheel, add the following Maven dependency:

<dependency>
    <groupId>cn.hutool</groupId>
    <artifactId>hutool-captcha</artifactId>
    <version>5.8.6</version>
</dependency>

Hutool provides four ready‑made captcha types, each with a concise controller method:

LineCaptcha – CaptchaUtil.createLineCaptcha(130, 38, 5, 5) CircleCaptcha – CaptchaUtil.createCircleCaptcha(130, 38, 5, 20) ShearCaptcha – CaptchaUtil.createShearCaptcha(130, 38, 5, 5) GifCaptcha – CaptchaUtil.createGifCaptcha(130, 38, 5) Each endpoint sets image/jpeg content type, disables caching, and writes the image to the response.

Custom content can be configured, e.g., a numeric captcha using RandomGenerator("0123456789", 4) or an arithmetic captcha with MathGenerator, storing the generated code in the session for later verification.

Testing and Best Practices

Send GET requests to the captcha endpoints and verify the response is an image.

Refresh multiple times to ensure the image changes.

If the image does not change, check cache‑control headers.

Key practical recommendations:

Store captcha values in Session or Redis.

Clear the value immediately after successful verification.

Rate‑limit the captcha endpoint.

For high‑security scenarios, combine with SMS or IP‑based risk control.

Conclusion

When extreme customization is required, a custom implementation provides full control but at the cost of higher maintenance. For the vast majority of cases, Hutool delivers a stable, efficient solution with minimal code. In real projects, 99 % of situations do not require hand‑crafted captchas, allowing developers to focus on core business logic.