kk-anti-reptile: Spring Boot Anti‑Crawler Component and Integration Guide

kk-anti-reptile is a reusable anti‑reptile (anti‑crawler) component designed for distributed systems built with Spring Boot (both 1.x and 2.x) and requires Redis for state storage.

System Requirements

Spring Boot application (any version)

Redis instance

Working Process

The component registers a Servlet Filter via Spring’s FilterRegistrationBean . Inside the filter, a responsibility‑chain pattern weaves various filtering rules, each exposed through an abstract interface for easy extension.

If a request fails any rule, the filter returns HTTP status 509 and serves a verification page (CAPTCHA). After the user solves the CAPTCHA, the rule chain is reset and the request can proceed.

Built‑in Rules

ip‑rule

Counts requests within a configurable time window; requests exceeding the maximum are blocked. Parameters such as window size, max count, and IP whitelist are configurable.

ua‑rule

Analyzes the User‑Agent header to extract OS, device, and browser information, allowing filtering based on these dimensions.

After a Rule Is Hit

The system blocks the request and generates a CAPTCHA with six possible formats (Chinese characters, alphanumeric, arithmetic; each can be static image or GIF). The CAPTCHA is hard to solve programmatically, effectively deterring large‑scale crawling.

Integration – Backend

Add the Maven dependency:

<dependency>
  <groupId>cn.keking.project</groupId>
  <artifactId>kk-anti-reptile</artifactId>
  <version>1.0.0‑SNAPSHOT</version>
</dependency>

Enable the component:

anti.reptile.manager.enabled=true

If the project uses Apollo configuration, enable bootstrap:

apollo.bootstrap.enabled=true

When Redisson is present, kk-anti-reptile automatically obtains a RedissonClient . If not, configure Redis manually:

spring.redisson.address=redis://192.168.1.204:6379
spring.redisson.password=xxx

Integration – Frontend

Intercept Axios responses globally. When a 509 status is received, open a new window to display the CAPTCHA HTML, inject the backend baseUrl , and allow the user to solve it.

import axios from 'axios';
import { baseUrl } from './config';

axios.interceptors.response.use(
  data => data,
  error => {
    if (error.response.status === 509) {
      const html = error.response.data;
      const verifyWindow = window.open('', '_blank', 'height=400,width=560');
      verifyWindow.document.write(html);
      verifyWindow.document.getElementById('baseUrl').value = baseUrl;
    }
    return Promise.reject(error);
  }
);
export default axios;

Notes

Apollo client must have bootstrap enabled (version ≥0.10.0).

Redisson is required for automatic Redis client detection.

The article also provides a configuration overview screenshot showing all properties prefixed with anti.reptile.manager .