SaaS平台的API网关设计认证、限流与版本管理的统一架构API网关是SaaS平台的门面承载着认证鉴权、流量控制、版本路由、协议转换等关键职责。一个设计良好的网关能让后端服务专注于业务逻辑而一个糟糕的网关则会成为整个平台的单点瓶颈。本文复盘一套生产级API网关的完整设计方案。一、网关整体架构二、多认证方式的统一适配2.1 认证策略矩阵SaaS平台的API通常需要支持多种认证方式不同场景适用不同策略认证方式适用场景安全级别复杂度API Key服务端集成、自动化脚本中低JWT BearerWeb前端、移动端高中OAuth2.0第三方应用授权高高HMAC签名高安全要求的内部服务极高高2.2 统一认证过滤器Component Order(1) public class UnifiedAuthFilter implements GlobalFilter { private final MapAuthType, AuthHandler authHandlers; public UnifiedAuthFilter(ListAuthHandler handlers) { this.authHandlers handlers.stream() .collect(Collectors.toMap(AuthHandler::supportedType, h - h)); } Override public MonoVoid filter(ServerWebExchange exchange, GatewayFilterChain chain) { ServerHttpRequest request exchange.getRequest(); // 1. 识别认证类型 AuthType authType detectAuthType(request); if (authType AuthType.NONE) { return unauthorized(exchange, Missing authentication credentials); } // 2. 委托给对应的Handler AuthHandler handler authHandlers.get(authType); if (handler null) { return unauthorized(exchange, Unsupported auth type: authType); } // 3. 执行认证 return handler.authenticate(request) .flatMap(principal - { // 将认证结果写入上下文后续过滤器可直接使用 exchange.getAttributes().put(principal, principal); exchange.getAttributes().put(tenantId, principal.getTenantId()); return chain.filter(exchange); }) .onErrorResume(AuthException.class, e - unauthorized(exchange, e.getMessage())); } private AuthType detectAuthType(ServerHttpRequest request) { HttpHeaders headers request.getHeaders(); if (headers.containsKey(X-Api-Key)) { return AuthType.API_KEY; } String auth headers.getFirst(HttpHeaders.AUTHORIZATION); if (auth ! null) { if (auth.startsWith(Bearer )) { return AuthType.JWT; } if (auth.startsWith(HMAC )) { return AuthType.HMAC; } } // OAuth2 通过 query param 或 header if (request.getQueryParams().containsKey(access_token)) { return AuthType.OAUTH2; } return AuthType.NONE; } }2.3 各认证Handler实现Component public class JwtAuthHandler implements AuthHandler { private final JwtTokenProvider tokenProvider; private final TenantConfigService tenantConfig; Override public AuthType supportedType() { return AuthType.JWT; } Override public MonoPrincipal authenticate(ServerHttpRequest request) { String token extractToken(request); return Mono.fromCallable(() - { // 1. 验证签名和有效期 Claims claims tokenProvider.validateToken(token); // 2. 检查令牌是否被吊销Redis黑名单 String jti claims.getId(); if (tokenProvider.isRevoked(jti)) { throw new AuthException(Token has been revoked); } // 3. 构造Principal return Principal.builder() .userId(claims.getSubject()) .tenantId(claims.get(tenant_id, String.class)) .roles(claims.get(roles, List.class)) .permissions(claims.get(permissions, List.class)) .tokenId(jti) .build(); }); } } Component public class ApiKeyAuthHandler implements AuthHandler { private final LoadingCacheString, ApiKeyInfo apiKeyCache; public ApiKeyAuthHandler() { this.apiKeyCache Caffeine.newBuilder() .maximumSize(50_000) .expireAfterWrite(1, TimeUnit.MINUTES) .build(this::loadApiKey); } Override public AuthType supportedType() { return AuthType.API_KEY; } Override public MonoPrincipal authenticate(ServerHttpRequest request) { String apiKey request.getHeaders().getFirst(X-Api-Key); return Mono.fromCallable(() - { ApiKeyInfo info apiKeyCache.get(apiKey); if (info null || info.isExpired()) { throw new AuthException(Invalid or expired API Key); } // 更新最后使用时间 apiKeyRepository.updateLastUsed(apiKey, Instant.now()); return Principal.builder() .userId(info.getUserId()) .tenantId(info.getTenantId()) .apiKeyId(info.getId()) .scopes(info.getScopes()) .build(); }); } }三、租户级API级的双重限流3.1 限流维度设计3.2 限流过滤器实现Component Order(2) public class RateLimitFilter implements GlobalFilter { private final StringRedisTemplate redis; private final RateLimitConfigService configService; Override public MonoVoid filter(ServerWebExchange exchange, GatewayFilterChain chain) { Principal principal exchange.getAttribute(principal); String path exchange.getRequest().getURI().getPath(); // 获取限流配置租户级 API级 RateLimitPolicy policy configService.getPolicy( principal.getTenantId(), path); if (policy null) { return chain.filter(exchange); // 无限流配置直接放行 } // 执行多层限流检查 return checkRateLimit(principal, path, policy) .flatMap(allowed - { if (allowed) { return chain.filter(exchange); } return rateLimited(exchange, policy); }); } private MonoBoolean checkRateLimit(Principal principal, String path, RateLimitPolicy policy) { long now System.currentTimeMillis(); // L1: 全局检查 if (!checkGlobalRate(now, policy.getGlobalQps())) { return Mono.just(false); } // L2: 租户级检查 String tenantKey rate:tenant: principal.getTenantId(); if (!checkSlidingWindow(tenantKey, now, policy.getTenantQpm())) { return Mono.just(false); } // L3: API级检查 String apiKey rate:api: principal.getTenantId() : normalizePath(path); if (!checkSlidingWindow(apiKey, now, policy.getApiQpm())) { return Mono.just(false); } return Mono.just(true); } /** * 滑动窗口限流 - Lua保证原子性 */ private boolean checkSlidingWindow(String key, long now, long limit) { String luaScript local key KEYS[1] local now tonumber(ARGV[1]) local window now - 60000 local limit tonumber(ARGV[2]) -- 移除过期记录 redis.call(ZREMRANGEBYSCORE, key, 0, window) -- 当前窗口计数 local count redis.call(ZCARD, key) if count limit then return 0 end -- 添加当前请求使用纳秒精度避免碰撞 redis.call(ZADD, key, now, now .. : .. redis.call(INCR, key .. :seq)) redis.call(EXPIRE, key, 120) return 1 ; ListLong result redis.execute( new DefaultRedisScript(luaScript, List.class), List.of(key), String.valueOf(now), String.valueOf(limit) ); return result.get(0) 1L; } }四、API版本管理与兼容性保障4.1 版本策略对比策略实现方式优势劣势URL路径/api/v1/orders直观、易调试URL不够RESTful请求头Accept: application/vnd.apijson;version2RESTful规范调试不便查询参数/api/orders?version2实现简单污染查询参数实际选择URL路径作为主策略 请求头作为辅助。4.2 版本路由实现Component public class ApiVersionRouter { private final MapString, MapString, RouteHandler versionRoutes; public ApiVersionRouter(ListRouteHandler handlers) { // 构建两级路由表{api: {version: handler}} this.versionRoutes handlers.stream() .collect(Collectors.groupingBy( RouteHandler::getApiName, Collectors.toMap(RouteHandler::getVersion, h - h) )); } /** * 解析版本并路由到对应的Handler */ public RouteHandler resolve(ServerHttpRequest request) { String path request.getURI().getPath(); String apiName extractApiName(path); // 策略1: URL路径版本 (优先级高) String urlVersion extractVersionFromPath(path); if (urlVersion ! null) { return getHandler(apiName, urlVersion); } // 策略2: Accept Header版本 String headerVersion extractVersionFromHeader(request); if (headerVersion ! null) { return getHandler(apiName, headerVersion); } // 策略3: 默认最新版本 return getLatestHandler(apiName); } /** * 版本兼容性检查与降级 */ public boolean isCompatible(String requested, String available) { Version req Version.parse(requested); Version avail Version.parse(available); // 主版本号必须一致不兼容的Breaking Change if (req.getMajor() ! avail.getMajor()) { return false; } // 请求的次版本号不能高于服务端客户端太新 if (req.getMinor() avail.getMinor()) { return false; } return true; } } RestController public class OrderController { GetMapping(/api/v1/orders/{id}) public OrderResponseV1 getOrderV1(PathVariable String id) { // V1版本基础字段 return orderService.getBasicOrder(id); } GetMapping(/api/v2/orders/{id}) public OrderResponseV2 getOrderV2(PathVariable String id) { // V2版本新增折扣、优惠券等字段 return orderService.getEnhancedOrder(id); } GetMapping(value /api/v3/orders/{id}, produces application/vnd.api.v3json) public OrderResponseV3 getOrderV3(PathVariable String id) { // V3版本新增AI推荐相关字段 return orderService.getAIEnhancedOrder(id); } }4.3 API文档与SDK自动生成Configuration public class OpenApiDocGenerator { Bean public GroupedOpenApi publicApi() { return GroupedOpenApi.builder() .group(public-api-v2) .pathsToMatch(/api/v2/**) .addOpenApiCustomizer(openApi - { // 自动注入租户认证说明 openApi.getComponents() .addSecuritySchemes(ApiKey, new SecurityScheme() .type(SecurityScheme.Type.APIKEY) .in(SecurityScheme.In.HEADER) .name(X-Api-Key) .description(租户API密钥在控制台「API管理」页面获取)); // 自动注入限流说明 openApi.getPaths().forEach((path, item) - { item.readOperations().forEach(op - { op.addExtension(x-rate-limit, Map.of( default, 1000 requests per minute, burst, 2000 requests per minute )); }); }); }) .build(); } /** * 根据OpenAPI规范自动生成SDK */ Scheduled(cron 0 0 6 * * ?) // 每天6点重新生成 public void generateSDKs() { String openApiSpec fetchOpenApiSpec(); // 使用OpenAPI Generator生成多语言SDK List.of(java, python, typescript, go).forEach(lang - { CodegenConfig config new CodegenConfig() .setInputSpec(openApiSpec) .setGeneratorName(lang) .setOutputDir(/repos/sdk/ lang) .setAdditionalProperty(groupId, com.saas.platform) .setAdditionalProperty(artifactId, saas-sdk- lang); DefaultGenerator generator new DefaultGenerator(); generator.opts(config).generate(); }); } }五、总结SaaS平台的API网关设计核心在于五个统一统一认证通过认证类型自动检测 Handler策略模式一套代码适配API Key/JWT/OAuth2/HMAC等多种认证方式。统一限流租户级→API级→用户级三层限流Redis滑动窗口保证精确性和原子性。统一版本管理URL路径为主要版本载体配合Header兼容主版本号不一致直接拒绝保证Breaking Change的安全。统一文档OpenAPI 3.0规范自动生成嵌入认证说明和限流参数。统一监控将认证成功率、限流拒绝率、各版本API调用分布等指标统一上报到Prometheus。生产环境运行数据单网关节点QPS稳定在8000认证延迟P99 5ms限流精度误差 0.1%。网关层是整个SaaS平台的第一公里值得投入足够的设计精力。