author: van , ggfanwentao@gmail.com
中文 | 点击跳转
Ip-Limiter is a lightweight, annotation-based IP rate limiting component based on JVM cache, designed for easy integration into projects and to meet multi-threading scenarios.
Contains detailed demonstration code
Demo Project Repository: https://github.com/DDAaTao/ip-limiter-example
Demo China Project Repository: https://gitee.com/fanwentaomayun/ip-limiter-example
Ip-Limit features include:
- Annotation-based usage, simple and convenient, can be added to Controller classes or specific API methods.
- Minimal intrusion into business logic; no need for extensive configuration, yet supports various scenarios.
- Provides group-level uniform rate limiting, serving both single interface and multiple interfaces within a group.
- Supports configuration through property files and dynamic external configuration (addition and deletion) of blacklists and whitelists.
# Configuration in a properties file, note that ',' is used as a delimiter
my.white.ip.list=172.16.50.21,172.16.50.22,172.16.50.23
// Usage in code
@IpLimit(limitType = LimitType.WHITE_LIST, whiteList = "${my.white.ip.list}")
// or
@IpLimit(limitType = LimitType.WHITE_LIST, whiteList = {"${my.white.ip.list}","172.16.50.35"})
- Black and white list IP rules support multiple fuzzy pattern configurations and IPv6:
- 172.*.*.1
- 172.*.1
- 172.*
- *.21
- *
Core rate limiting modes - LimitType class:
- DEFAULT - Follows the default rate limiting strategy, without considering black and white list parameters.
- WHITE_LIST - Considers only the whitelist strategy; requests not in the whitelist are all rejected.
- BLACK_LIST - Considers only the blacklist strategy; requests not in the blacklist are not rate-limited.
- DEFAULT_WITH_WHITE_LIST - Builds upon the default rate limiting strategy, where IPs in the whitelist are not rate-limited.
- DEFAULT_WITH_BLACK_LIST - Builds upon the default rate limiting strategy, directly returning a 403 error for IPs in the blacklist.
- DEFAULT_WITH_WHITE_AND_BLACK_LIST - Builds upon the default rate limiting strategy, directly returning a 403 error for IPs in the blacklist and allowing IPs in the whitelist to proceed.
- Include the Ip-Limit dependency (available on Maven Central).
<!-- Recommend using the latest version {ip-limiter.version} -->
<dependency>
<groupId>io.github.DDAaTao</groupId>
<artifactId>ip-limiter</artifactId>
<version>1.0.3</version>
</dependency>
- Add @EnableIpLimit to the web application class or any class that can be scanned by Spring.
- Add the @IpLimit annotation to the methods (endpoints) where you want to apply IP rate limiting, and adjust the parameters according to your needs.
If your project does not include guava and spring-context packages, you need to manually include them; otherwise, you may encounter a java.lang.NoSuchMethodError exception.
Starting from version 1.0.1, these dependencies are included by default. If your project already has these dependencies, consider excluding them.
/**
* By default, when requests exceed rate limits, it logs an error and throws an IpLimitException.
* Users can capture and customize the exception handling through a global exception handler.
* Callbacks or hook methods may be added in the future.
* */
@Slf4j
@ControllerAdvice
public class BaseExceptionHandler {
@ExceptionHandler(IpLimitException.class)
@ResponseBody
public RestApiResult<Object> resolveCommonException(IpLimitException e) {
log.error("IpLimitException Intercept. Please try again later.. " + e.getMessage());
// Here, you can perform rate limit callback processing using e.getRequestIp() and e.getGroupName()
return RestApiResult.fail("IpLimitException Intercept. Please try again later.. ");
}
}
In SpringCloud projects or most projects, there is usually an existing authentication mechanism, such as Spring Security. In such cases, when there is a need to integrate with external interfaces, there are two approaches. One is to handle it through third-party protocols like OAuth2, but this can be a complex integration process.
Especially in the case of internal network projects that already have robust security measures, another approach can be used, which is the whitelist method, denoted as LimitType.WHITE_LIST.
Alternatively, you can add rate limiting rules on top of the whitelist to ensure system availability, using LimitType.DEFAULT_WITH_WHITE_LIST.
Starting from version 1.0.3, IpLimitUtils utility class is provided, which allows dynamic configuration of black and white lists. This dynamic configuration data is combined with the configuration specified in annotations.
IpLimitUtils offers the following methods
putWhiteIpGroup
- Allows dynamic addition of new entries to the whitelist.removeWhiteIpGroup
- Dynamically clears the whitelist for a specific group.deleteWhiteIpGroupArrayStr
- Allows dynamic removal of a specific arrayStr entry from the whitelist for a group.putBlackIpGroup
- Allows dynamic addition of new entries to the blacklist.removeBlackIpGroup
- Dynamically clears the blacklist for a specific group.deleteBlackIpGroupArrayStr
- Allows dynamic removal of a specific arrayStr entry from the blacklist for a group.
With these methods, you can store black and white list data in third-party sources like databases and then dynamically initialize or modify blacklist configurations.
- Currently, it does not support Spring 6.x.
Bold indicates important version updates; strikethrough indicates deprecated versions, not recommended for use.
1.0.1Implemented sliding window rate limiting mode.- 1.0.2 Adjusted specifications and added a link to example projects.
- 1.0.3 Introduced dynamic configuration of black and white lists for user customization.
- User-customized rate limiters.
- Global rate limiting and per-IP rate limiting.
- Adding rate limiting monitoring and callback for monitoring data (currently handled via @ExceptionHandler(IpLimitException.class)).
- IP cache statistics data can be stored in other data sources to avoid excessive JVM cache usage.
- Support for using a specified field (e.g., account) for rate limiting.
- More flexible exception handling mechanisms.
- Support Spring-Gateway