Current Version:2.0.1-SNAPSHOT
JDK Baseline:17
Group ID:io.github.easy4j
Artifact ID:kaptcha-spring-boot-starter
License:Apache License 2.0
1. Positioning
kaptcha-spring-boot-starter is a Spring Boot starter that integrates kaptcha for applications using kaptcha. It provides auto-configuration, property binding, and ready-to-use beans so that applications can consume kaptcha capabilities with minimal setup.
| Dimension |
Description |
| Type |
Spring Boot Starter |
| Consumers |
Spring Boot applications using kaptcha |
| Core Capabilities |
auto-configuration, property binding, ready-to-use beans for kaptcha |
| JDK |
17 |
| Coordinates |
io.github.easy4j:kaptcha-spring-boot-starter:2.0.1-SNAPSHOT |
| Config Prefix |
kaptcha |
2. Core Capabilities
| Capability |
Status |
Description |
| Auto-configuration |
✅ Stable |
Registers kaptcha beans automatically |
| Property Binding |
✅ Stable |
Binds kaptcha.* to KaptchaProperties |
KaptchaResolver bean |
✅ Stable |
Auto-registered via KaptchaAutoConfiguration |
3. Requirements and Compatibility
| Dependency |
Minimum |
Evidence |
| JDK |
17 |
pom.xml |
| Spring Boot |
2.6.0 |
pom.xml parent |
| Maven |
3.6+ |
Maven Enforcer |
4. Auto-configuration
The starter auto-configures the following beans:
| Bean |
Condition |
Missing Behavior |
KaptchaResolver |
classpath + property |
not created |
Auto-configuration registration:
META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports (Spring Boot 2.7+ / 3.x / 4.x)
META-INF/spring.factories (Spring Boot 2.x legacy)
5. Dependency
<dependency>
<groupId>io.github.easy4j</groupId>
<artifactId>kaptcha-spring-boot-starter</artifactId>
<version>2.0.1-SNAPSHOT</version>
</dependency>
No additional easy4j component dependencies.
6. Quick Start
6.1 Add dependency
Add the dependency above to your pom.xml.
6.2 Start the application
@SpringBootApplication
public class Application {
public static void main(String[] args) {
SpringApplication.run(Application.class, args);
}
}
The starter registers a servlet at GET /kaptcha. Open that URL to fetch the image. The text and creation time are stored in the HTTP session.
6.3 Verify the answer
import javax.servlet.http.HttpServletRequest;
import com.google.code.kaptcha.spring.boot.ext.KaptchaResolver;
import com.google.code.kaptcha.spring.boot.ext.exception.CaptchaIncorrectException;
import com.google.code.kaptcha.spring.boot.ext.exception.CaptchaTimeoutException;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class CaptchaController {
private final KaptchaResolver resolver;
public CaptchaController(KaptchaResolver resolver) {
this.resolver = resolver;
}
@PostMapping("/captcha/verify")
public boolean verify(HttpServletRequest request, @RequestParam String answer)
throws CaptchaIncorrectException, CaptchaTimeoutException {
return resolver.validCaptcha(request, answer);
}
}
Fetch GET /kaptcha, then send POST /captcha/verify?answer=... with the same session cookie. An incorrect answer returns false; missing or expired answers raise the resolver exceptions. Map those exceptions to your application's HTTP responses as needed.
7. Configuration Reference
7.1 Config Prefix
kaptcha
7.2 Configuration Items
| Property |
Type |
Default |
Required |
Description |
Sensitive |
kaptcha.pattern |
string |
/kaptcha |
No |
Captcha image servlet path |
No |
kaptcha.captcha-timeout |
long |
60000 |
No |
Answer lifetime in milliseconds |
No |
8. Version Lines and Compatibility
| Branch |
JDK |
Spring Boot |
Component Version |
Status |
2.3.x / 2.7.x |
8+ |
2.3.x / 2.7.x |
1.0.x |
Maintenance |
3.0.x ~ 3.5.x |
17 |
3.x |
2.0.x |
Maintenance |
4.0.x / 4.1.x |
17+ |
4.x |
3.0.x |
Active |
9. Build and Test
mvn clean verify
mvn -pl kaptcha-spring-boot-starter -am test
10. Troubleshooting
| Symptom |
Diagnosis |
Resolution |
| Bean not created |
Check auto-configuration report |
Verify kaptcha.enabled=true and classpath |
ClassNotFoundException |
Missing dependency |
Add the required module |
| Version conflict |
mvn dependency:tree |
Use BOM for version alignment |
11. Contribution
- Fork the repository.
- Create a feature branch.
- Run
mvn clean verify before submitting.
- Submit a pull request.
12. License
This project is licensed under the Apache License, Version 2.0.