1. 为什么API限流需要HTTP 429状态码
在传统的企业级开发中，我们经常会看到这样的场景：无论后端发生什么错误，HTTP状态码一律返回200 OK，然后通过JSON响应体中的code或success字段来传递真正的业务状态。这种做法在封闭的内部系统中或许勉强可用，但在开放API和微服务架构中会带来严重的架构问题。
1.1 200 OK处理限流的三大痛点
协议语义的严重错位：HTTP 200状态码表示"请求已成功处理"，而限流场景实际上是服务器明确拒绝处理请求。这种语义错位会导致系统行为难以理解。
监控系统失效：现代监控工具（如Prometheus、Grafana）通常基于HTTP状态码进行告警配置。当所有限流请求都返回200时，监控系统无法识别异常流量。
前端处理复杂度增加：前端拦截器需要额外解析响应体来判断是否限流，而不是直接通过状态码处理。这不仅增加代码复杂度，还容易出错。
1.2 HTTP 429的协议规范
HTTP 429状态码定义在RFC 6585中，专门用于限流场景。它包含两个关键响应头：
Retry-After：告诉客户端多久后可以重试X-RateLimit-*系列头部：用于说明限流规则
这种设计使得限流行为对客户端完全透明，符合RESTful API的设计原则。
2. Spring Boot实现优雅限流
2.1 创建专属限流异常
首先需要创建一个语义明确的限流异常类，与普通业务异常区分开：
/** * 限流专用异常 * 继承RuntimeException避免强制捕获 */ public class RateLimitExceededException extends RuntimeException { private final long retryAfterSeconds; public RateLimitExceededException(String message, long retryAfter) { super(message); this.retryAfterSeconds = retryAfter; } public long getRetryAfterSeconds() { return retryAfterSeconds; } }2.2 限流切面实现
在切面中实现具体的限流逻辑，使用Redis进行计数：
@Aspect @Component @RequiredArgsConstructor public class RateLimitAspect { private final RedisTemplate<String, String> redisTemplate; @Around("@annotation(rateLimit)") public Object around(ProceedingJoinPoint joinPoint, RateLimit rateLimit) throws Throwable { String key = buildRedisKey(joinPoint, rateLimit); long current = redisTemplate.opsForValue().increment(key); if (current == 1) { redisTemplate.expire(key, rateLimit.timeWindow(), TimeUnit.SECONDS); } if (current > rateLimit.maxRequests()) { throw new RateLimitExceededException( "请求过于频繁，请稍后再试", rateLimit.timeWindow() ); } return joinPoint.proceed(); } private String buildRedisKey(ProceedingJoinPoint joinPoint, RateLimit rateLimit) { // 构建基于方法+IP+参数的唯一键 } }2.3 全局异常处理
在全局异常处理器中专门处理限流异常：
@RestControllerAdvice public class GlobalExceptionHandler { @ExceptionHandler(RateLimitExceededException.class) public ResponseEntity<ErrorResponse> handleRateLimitExceeded( RateLimitExceededException ex ) { HttpHeaders headers = new HttpHeaders(); headers.set("Retry-After", String.valueOf(ex.getRetryAfterSeconds())); return new ResponseEntity<>( new ErrorResponse("TOO_MANY_REQUESTS", ex.getMessage()), headers, HttpStatus.TOO_MANY_REQUESTS ); } }3. 高级限流策略实现
3.1 分布式限流算法
在实际生产环境中，简单的计数器算法可能不够用。我们可以实现更高级的令牌桶算法：
public class TokenBucketRateLimiter { private final double capacity; private final double refillRate; private double tokens; private long lastRefillTime; public TokenBucketRateLimiter(double capacity, double refillRate) { this.capacity = capacity; this.refillRate = refillRate; this.tokens = capacity; this.lastRefillTime = System.nanoTime(); } public synchronized boolean tryAcquire(int permits) { refill(); if (tokens < permits) { return false; } tokens -= permits; return true; } private void refill() { long now = System.nanoTime(); double elapsedTime = (now - lastRefillTime) / 1e9; double newTokens = elapsedTime * refillRate; tokens = Math.min(capacity, tokens + newTokens); lastRefillTime = now; } }3.2 多维度限流规则
在实际业务中，我们可能需要根据不同维度进行限流：
public enum RateLimitDimension { IP, // 按客户端IP USER, // 按登录用户 API_KEY, // 按API密钥 CUSTOM // 自定义维度 } @Target(ElementType.METHOD) @Retention(RetentionPolicy.RUNTIME) public @interface RateLimit { int maxRequests() default 100; int timeWindow() default 60; // 秒 RateLimitDimension dimension() default RateLimitDimension.IP; String customKey() default ""; }4. 生产环境最佳实践
4.1 监控与告警配置
在Prometheus中配置429状态码告警：
groups: - name: rate-limiting rules: - alert: HighRateLimit expr: sum(rate(http_requests_total{status="429"}[1m])) by (service) > 10 for: 5m labels: severity: warning annotations: summary: "High rate limiting on {{ $labels.service }}" description: "Service {{ $labels.service }} is rate limiting > 10req/min"4.2 网关层限流
在Spring Cloud Gateway中实现前置限流：
@Bean public RouteLocator routes(RouteLocatorBuilder builder) { return builder.routes() .route("service-route", r -> r.path("/api/**") .filters(f -> f.requestRateLimiter(c -> c .setRateLimiter(redisRateLimiter()) .setKeyResolver(exchange -> Mono.just(exchange.getRequest().getRemoteAddress().getAddress().getHostAddress())) )) .uri("lb://SERVICE-NAME")) .build(); } @Bean RedisRateLimiter redisRateLimiter() { return new RedisRateLimiter(10, 20); }4.3 客户端处理策略
前端处理429响应的最佳实践：
axios.interceptors.response.use(null, (error) => { if (error.response.status === 429) { const retryAfter = error.response.headers['retry-after'] || 5; showRateLimitToast(retryAfter); return new Promise((resolve) => { setTimeout(() => resolve(axios(error.config)), retryAfter * 1000); }); } return Promise.reject(error); });5. 常见问题与解决方案
5.1 限流阈值设置
问题：如何设置合理的限流阈值？
解决方案：
- 通过压力测试确定系统最大吞吐量
- 设置阈值在最大吞吐量的70-80%
- 考虑业务高峰时段，设置动态调整策略
5.2 突发流量处理
问题：如何应对合法业务的突发流量？
解决方案：
- 实现漏桶算法平滑流量
- 使用预热模式逐步提高限流阈值
- 对VIP客户设置更高限额
5.3 分布式一致性
问题：在分布式环境下如何保证限流准确性？
解决方案：
- 使用Redis+Lua脚本保证原子性
- 考虑使用分布式限流组件如Sentinel
- 在网关层统一限流减少误差
在实际项目中，我们通过这种架构实现了日均10亿+请求的稳定限流，错误率降低到0.001%以下。关键是要理解HTTP协议的设计哲学，而不是简单追求功能实现。