做 AI 应用的朋友应该都有体会：同一张图，老手能生成得又快又稳，新手可能连接口都调不明白，或者好不容易调通了，一上线就被刷爆了配额。这段时间我正好把一个 AI 生图功能从零接入到一个 Spring Boot 3 的现有后端里，从最初的"能出图"到后来的"稳、快、不烧钱"，踩了不少坑，也沉淀了一套比较完整的做法。这篇就把它拆开揉碎，手把手复现一遍，重点是两件事：一是怎么设计一条工业级的 AI 生图管道（也就是从用户请求进来，到最后拿到图片 URL 的完整链路），二是怎么挡住恶意刷接口的流量。
先说点背景。gpt-image-2.5 这类图像生成接口，核心能力其实不复杂：你传一段 Prompt（提示词）和一些生成参数，它给你返回一张或多张图。但放在生产环境里，事情远没有这么简单。直接调用有什么问题？第一，生图接口普遍偏慢，同步等待会让 HTTP 请求长时间挂起，用户体验差不说，应用服务器的线程也被白白占着；第二，生成结果需要二次获取，逻辑上天然是异步的；第三，生图是有成本的，如果接口直接被公开，恶意用户拿你的 Key 疯狂刷图，账单会非常难看。所以，接入的核心不是"调通 API"，而是"把 API 包成一个可控、可靠、可计费的业务能力"。
这篇分享面向的是有一定 Java 基础、想在自己的后端项目里集成 AI 生图能力的开发者。零基础的同学也能跟上，但至少要了解 Spring Boot 的基本概念、HTTP 调用和 Redis 的基本用法。我会把设计思路、核心代码、参数选型、常见坑位全部摊开讲，你可以直接照着抄，也可以根据项目情况做裁剪。
1. 整体架构设计与选型思路
1.1 为什么不能直接调接口，管道层到底解决什么问题
很多人在接入 AI 生图时第一个想法是：Controller 里直接调用 gpt-image-2.5 的 HTTP 接口，返回图片 URL 完事。Demo 可以，生产不行，原因有三个。
第一，超时与资源占用。生图接口慢的时候能跑到几十秒甚至分钟级。在 Spring Boot 默认的 Tomcat 线程模型下，一个请求占一个线程，慢请求会把线程池打满，其他接口跟着遭殃。虽然也能调大 ThreadPool，但治标不治本，服务器资源经不起这么消耗。
第二，状态不可控。调用第三方接口，你没法假设它永远成功。网络抖动、服务端过载、限流，各种异常都可能发生。如果同步调用失败了，用户看到的只有一个 500，让他重试？重试后又可能重复扣费，没法收敛。
第三，成本不可控。生图接口是按张计费的，而且费用不低。一旦你的接口被脚本刷，轻则账户欠费，重则服务被供应商熔断拉黑。这不是危言耸听，开放平台被薅羊毛的案例太多了。
所以我们要做的"管道"，本质上是加一个中间层。用户请求进来后，先经过校验、限流、配额扣减，然后丢到一个异步队列里，由后台任务去消费并调用上游 API，完成后把结果存起来，用户通过轮询或回调拿到最终图片。这中间，所有不可控的因素都被隔离在业务层之外，最终暴露给用户的是一套简洁可控的接口。
1.2 技术选型：为什么是 Spring Boot 3 + Redis + 数据库任务表
先看整体组件选型，每个都有它的理由。
Spring Boot 3 是基础，这个没什么好说的，项目本身就是基于它。需要注意 Spring Boot 3 基于 Jakarta EE 9+，很多老代码里的 javax 包要换成 jakarta，这个后面代码里会体现。
异步处理我选的是数据库任务表 + 线程池方案，没有直接上 MQ。原因是这个场景的并发量通常没那么大，生图是重操作，但提交频率可控，用 MQ 反而增加运维复杂度。任务表的好处是天然支持持久化、状态查询和失败重试，看一眼表就能知道当前系统有多少任务在跑、卡在哪一步。如果往后流量涨了，可以平滑迁移到 MQ，代码层面只需要改提交任务和消费任务的实现。
缓存和限流用 Redis。限流需要原子计数和过期时间，Redis 的 INCR + EXPIRE 或者 Lua 脚本是最合适的。配额扣减也是同样道理，必须是原子操作，不能两个请求同时扣到一个额度上。
HTTP 客户端我用的 Spring Boot 3 自带的 RestClient（也可以换成 WebClient 或 OkHttp，选型逻辑我后面会讲）。RestClient 是 Spring 6.1 引入的同步 HTTP 客户端，API 风格集成了 RestTemplate 的简单和 WebClient 的链式流畅，足够用。
存储结构上，任务表是核心。它记录了任务的唯一 ID、用户 ID、状态、请求参数、结果信息、失败原因、重试次数等。状态机是这个表的灵魂：PENDING（排队中）、PROCESSING（生成中）、SUCCESS（成功）、FAILED（失败）。后续可以扩展出 CANCELLED（取消）等状态，但核心四个够了。
2. 项目搭建与基础配置
2.1 依赖引入与版本选择
我的项目是基于 Spring Boot 3.2.x 构建的，Java 版本用的 17。如果你是老项目，需要注意 Spring Boot 3 对 Java 版本的最低要求是 17，版本太老的话先升级。
pom.xml 里的核心依赖如下：
<parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>3.2.5</version> <relativePath/> </parent> <dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-data-redis</artifactId> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-validation</artifactId> </dependency> <dependency> <groupId>com.mysql</groupId> <artifactId>mysql-connector-j</artifactId> <scope>runtime</scope> </dependency> <dependency> <groupId>org.mybatis.spring.boot</groupId> <artifactId>mybatis-spring-boot-starter</artifactId> <version>3.0.3</version> </dependency> </dependencies>MyBatis 用的是 3.0.3，因为这是适配 Spring Boot 3 的版本线。你如果喜欢 JPA 也不是不行，但生图任务表这种偏轻量、SQL 比较直观的场景，MyBatis 更容易写出可控的 SQL，特别是批量更新状态、分页查询这种操作。
Redis 这边配置好连接信息就可以了。需要注意的是，如果你的 Redis 是集群模式，Lua 脚本要保证 key 都在同一个 slot 里，后面写限量脚本时会再提。
2.2 HTTP 客户端配置：超时、连接池与重试
调用 gpt-image-2.5 这类接口，HTTP 客户端的配置直接决定了稳定性和性能。我踩过的坑是：最开始用默认配置，结果一个慢请求拖死了整个连接池，所有后续请求都在等连接。
用 RestClient 需要先构建一个 HttpClient。我建议用 JdkClientHttpRequestFactory（JDK 自带的 HTTP Client）或者 Apache HttpClient。这里用 Apache HttpClient，因为连接池、超时、重试配置更灵活。
@Configuration public class HttpClientConfig { @Bean public RestClient restClient() { PoolingHttpClientConnectionManager connectionManager = PoolingHttpClientConnectionManagerBuilder.create() .setMaxTotal(100) .setDefaultMaxPerRoute(50) .build(); RequestConfig requestConfig = RequestConfig.custom() .setConnectTimeout(5000) .setSocketTimeout(60000) .setConnectionRequestTimeout(5000) .build(); CloseableHttpClient httpClient = HttpClients.custom() .setConnectionManager(connectionManager) .setDefaultRequestConfig(requestConfig) .setRetryHandler(new DefaultHttpRequestRetryHandler(2, true)) .build(); ClientHttpRequestFactory factory = new HttpComponentsClientHttpRequestFactory(httpClient); return RestClient.builder() .requestFactory(factory) .baseUrl("https://api.example.com") // 替换成 gpt-image-2.5 的实际地址 .build(); } }这里的参数是我调整过的。连接超时设成 5 秒，够建连了；socket 超时设成 60 秒，给生图接口留足时间，毕竟它是真慢；连接池 maxTotal 100，单路由 50，这是基于"生图并发不会太高"的预估，如果你要支持更多并发，按比例上调就行。
注意：
DefaultHttpRequestRetryHandler的重试默认会重试所有异常，但只对幂等请求安全。生图请求不是幂等的，所以重试策略要谨慎，我建议重试次数不要超过 2 次，而且最好在业务层做带状态控制的补偿重试，而不是在 HTTP 层盲目重投同一个请求。
2.3 数据库表结构设计：任务表是整条管道的心脏
任务表设计得够不够稳，直接决定了管道的上限。我先给出表结构，然后再说为什么每个字段都是必要的。
CREATE TABLE `image_task` ( `id` bigint NOT NULL AUTO_INCREMENT, `task_id` varchar(64) NOT NULL COMMENT '业务任务唯一ID', `user_id` varchar(64) NOT NULL COMMENT '用户ID', `status` tinyint NOT NULL DEFAULT '0' COMMENT '0-排队中 1-生成中 2-成功 3-失败', `prompt` text NOT NULL COMMENT '提示词', `size` varchar(16) DEFAULT NULL COMMENT '图片尺寸', `quality` varchar(16) DEFAULT NULL COMMENT '质量参数', `n` int NOT NULL DEFAULT '1' COMMENT '生成数量', `image_urls` json DEFAULT NULL COMMENT '结果图片URL列表', `error_msg` varchar(512) DEFAULT NULL COMMENT '失败原因', `retry_count` int NOT NULL DEFAULT '0' COMMENT '已重试次数', `cost_credits` int DEFAULT '0' COMMENT '消耗的配额点数', `created_at` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP, `updated_at` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, PRIMARY KEY (`id`), UNIQUE KEY `uk_task_id` (`task_id`), KEY `idx_user_status` (`user_id`, `status`), KEY `idx_status_created` (`status`, `created_at`) ) COMMENT='AI生图任务表';几个字段的意义要说一下。
task_id 是业务侧的唯一 ID，由我们自己生成，不要让数据库自增主键直接暴露给用户。原因后面讲防刷时再说。
status 用 tinyint 是方便索引和比较，也不容易被字符串拼写坑到。0 到 3 四个状态，含义清晰。
prompt、size、quality、n 这些参数必须存下来，一方面业务上需要展示历史记录，另一方面失败重试时要从库里重新构造上游请求，不能依赖用户再传一次。
image_urls 用 JSON 类型，因为一次可能生成多张图，存一个字段比搞关联表简单得多，查询也方便。
retry_count 必须记，这是控制重试次数、防止死循环的抓手。cost_credits 是配额审计用的，后面会详细说。
3. gpt-image-2.5 接口对接与核心调用实现
3.1 请求参数映射与 DTO 设计
对接任何一个外部 API，第一步都是把外部接口的请求和响应映射成我们自己的内部模型。这里我先根据常见的图像生成接口参数约定设计 DTO，同时保留向 gpt-image-2.5 实际文档靠拢的扩展能力。
创建任务的请求 DTO：
public record ImageGenerationRequest( @NotBlank(message = "提示词不能为空") @Size(max = 1000, message = "提示词长度不能超过1000字符") String prompt, @Pattern(regexp = "256x256|512x512|1024x1024|1536x1024|1024x1536", message = "不支持的图片尺寸") String size, @Pattern(regexp = "standard|hd", message = "不支持的画质参数") String quality, @Min(value = 1, message = "生成数量最少为1") @Max(value = 4, message = "生成数量最多为4") Integer n ) {}我为什么会这么设计参数？因为这些参数决定了上游请求的价格。n 设上限是 4，一个用户一次最多生成 4 张，防止他拿一个任务生成 100 张图刷爆你的成本。实际对接时，你还需要对照 gpt-image-2.5 的接口文档做字段校准，比如有些接口支持 style 参数（vivid、natural），有些支持 response_format（url、b64_json），这些字段必须以你实际拿到的文档为准，我的 DTO 只是骨架。
对于第三方 AI 接口的响应，我处理成统一的外部响应结构，核心关注点有两个：请求是否成功、结果的获取方式是直接返回 URL 还是返回一个异步任务 ID。这两种模式在对接时差别很大，后面会讲到。
3.2 上游接口调用与两种响应模式的处理
gpt-image-2.5 这类接口，我用的是同步调用模式（即发起请求后，等待接口返回生成结果）。调用流程通常是：构建 JSON body，设置 Authorization 请求头，POST 到 /v1/images/generations 之类的路径，然后解析结果里的图片 URL 或 base64 数据。
按这个模式写代码：
@Service public class ImageGenerationClient { private final RestClient restClient; public ImageCallResult generate(ImageTask task) { Map<String, Object> body = new HashMap<>(); body.put("prompt", task.getPrompt()); body.put("size", task.getSize() == null ? "1024x1024" : task.getSize()); body.put("quality", task.getQuality() == null ? "standard" : task.getQuality()); body.put("n", task.getN() == null ? 1 : task.getN()); try { Map<String, Object> resp = restClient.post() .uri("/v1/images/generations") .header("Authorization", "Bearer " + apiKey) .contentType(MediaType.APPLICATION_JSON) .body(body) .retrieve() .body(new ParameterizedTypeReference<Map<String, Object>>() {}); List<String> urls = extractImageUrls(resp); return ImageCallResult.success(urls); } catch (RestClientResponseException e) { return ImageCallResult.failed("上游接口异常: " + e.getStatusCode()); } catch (Exception e) { return ImageCallResult.failed("调用异常: " + e.getMessage()); } } }这里我把上游错误全部捕获并转换成统一结果，而不是直接抛出异常，原因在于：调用失败不一定是系统故障，可能只是上游限流或临时过载，任务应该进入"可重试"状态，而不是直接把异常抛给上层导致任务标记失败。这就在代码层面给重试留了后门。
这里有第二种情况需要单独说明：如果 gpt-image-2.5 实际采用的是异步任务模式——也就是提交后返回一个任务 ID，需要后台轮询获取结果——那处理逻辑就要调整。常见的处理套路是加一个"提交生成任务"的接口和"查询任务结果"的接口，提交成功的任务持久化保存上游的任务 ID，然后由后台的 StatusPoller 定时查询上游状态，直到拿到最终结果。这两种模式选哪一种，完全取决于 gpt-image-2.5 的官方文档怎么定义，接入前一定要先确认，不然整个管道的状态机都要重写。
3.3 参数校验与内容安全检查
生图接口跟普通接口还不太一样，Prompt 是有安全风险的。比如用户提交一个包含违规内容的 Prompt，上游接口可能直接拒绝，返回 400；或者返回的图存在内容合规问题。所以参数校验不能只靠 Bean Validation，还要引入内容安全检查。
我在接入层加了一个 PromptGuard，核心逻辑是：对 Prompt 做长度控制之外，还会跑一个关键词/分类模型过滤。如果公司有现成的文本审核服务，直接调；没有的话，至少做一层敏感词过滤，并且对疑似风险内容返回错误提示而不是发往上游。
@Component public class PromptGuard { public boolean validate(String prompt) { if (prompt == null || prompt.isBlank()) { return false; } if (prompt.length() > 1000) { return false; } // 这里可以接第三方内容审核服务，或者加载本地敏感词库 return !containsSensitiveWords(prompt); } }不要觉得这一步多此一举。内容审核不做好，上游接口会拒绝你的请求、封禁你的 Key，甚至影响整个账号的服务可用性。这笔账必须提前算。
4. 工业级生图管道的异步处理与状态流转
4.1 线程池与任务队列的参数怎么定
任务提交后不能同步处理，必须异步化。我用的方案是：将任务写入数据库后，放入一个内存队列（BlockingQueue），后台线程从队列里消费并执行。为什么要保留数据库？因为数据库是持久化的事实源，内存队列是临时调度层。如果进程挂了，重启后可以把状态为"排队中"或"生成中"的任务重新捞出来继续跑，这就是"可靠性"的兜底。
线程池配置我写在这里：
@Configuration public class TaskExecutorConfig { @Bean("imageTaskExecutor") public ThreadPoolTaskExecutor imageTaskExecutor() { ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor(); executor.setCorePoolSize(4); executor.setMaxPoolSize(8); executor.setQueueCapacity(1000); executor.setKeepAliveSeconds(60); executor.setThreadNamePrefix("image-gen-"); executor.setRejectedExecutionHandler(new ThreadPoolExecutor.CallerRunsPolicy()); executor.initialize(); return executor; } }参数怎么定的？核心线程 4，最大 8，队列 1000。计算依据是：单次生图平均耗时 10~20 秒，核心 4 个线程意味着每秒最多处理大概 0.2 到 0.4 个任务，那 1000 的队列够不够？如果一个高峰期涌入 500 个任务，处理完大约需要 20 到 40 分钟，队列会积压，但不会立即崩。Max 8 是在瞬时流量上来时拉高吞吐，但注意最大线程和队列容量是配套的，队列满后才会创建新线程到 Max，而不是一开始就 8 个线程跑。
拒绝策略我选的 CallerRunsPolicy。这意味着队列满了之后，新提交的任务会由提交任务的线程自己执行，也就是说用户请求会被阻塞在提交环节。这在生图场景里其实是合理的——它告诉用户"当前系统繁忙，请等待"，而不是直接丢弃任务。从实现上看像是"反压"机制，保护了系统不被突然的流量击垮。
4.2 任务状态机与失败重试策略
异步管道的核心是状态流转。画不出来图没关系，但状态不能乱。我的状态机规则如下：
- 初始状态：PENDING（0）
- PENDING -> PROCESSING（1）：消费线程从队列取出任务时更新
- PROCESSING -> SUCCESS（2）：上游调用成功，拿到图片 URL
- PROCESSING -> PENDING（重试）：调用失败且重试次数未达上限
- PROCESSING -> FAILED（3）：重试次数耗尽或不可恢复的错误
对应的更新 SQL 很简单，但要注意状态更新的原子性。在 MySQL 里我用的乐观锁思路，更新时带上当前状态条件：
UPDATE image_task SET status = 1, updated_at = NOW() WHERE task_id = #{taskId} AND status = 0如果影响行数为 0，说明状态已经被其他线程修改了，当前线程不应该继续处理。这样能防止同一个任务被多个线程重复消费。这个细节非常关键，尤其是在应用多实例部署的时候，不加这个条件，两个实例会同时捞到同一个 PENDING 任务，造成上游重复调用。
重试策略我是这样设计的：失败后不立即重试，而是用一个带延迟的重试队列。最简单的方式是记录 next_retry_time 字段，后台扫描线程定时捞取"当前时间 > next_retry_time 且 retry_count < max_retry"的任务。重试间隔可以用指数退避：第一次失败后 1 分钟，第二次 5 分钟，第三次 30 分钟，第三次是上限，再失败就标记 FAILED。这个策略是针对第三方接口的不稳定性设计的，不是所有失败都值得立即重试。
注意：重试必须区分"可重试失败"和"不可重试失败"。参数错误（400）、鉴权失败（401）、配额不足（429 但为国家限流）这些属于不可重试；超时、502、503、连接异常属于可重试。我见过有人把所有失败都丢进重试队列，结果 400 的请求重试 10 次还是 400，纯粹浪费配额。
4.3 结果通知：轮询、回调还是 WebSocket
任务完成后，用户怎么拿到图片？三种方式都有适合的场景，我分别说下利弊。
轮询最简单，也最通用。客户端提交任务拿到 taskId 后，每隔几秒 GET 一次任务详情，状态变成 SUCCESS 后取图片 URL。问题是对服务器有一定的请求压力，轮询间隔太短浪费资源，太长用户感知慢。我的经验是建议轮询间隔至少 2 秒，前端通过 setTimeout 递归调用来实现，而不是 setInterval 高频轰炸。
Webhook 回调适合服务端有回调地址的客户端。任务完成时，服务端主动 POST 通知到指定的 callback URL。这种模式体验好，但对客户端服务端的公网可达性有要求，很多小项目没有这个条件。而且回调很容易因为网络原因丢失，需要额外做重试和补偿查询。
WebSocket 是前两种的折中，服务端主动推送状态变更，延迟最低，体验最好。但需要维护长连接，复杂度高一些，一般用于内部管理系统。
我最终的做法是"轮询为主 + Webhook 可选"。对外暴露的接口是 RESTful 的，客户端轮询最简单；同时预留了 callback_url 字段，在任务完成时异步调一次。这个方案兼顾了通用性和可用性。
4.4 控制器的完整实现
任务提交和查询的 Controller 长这样：
@RestController @RequestMapping("/api/v1/generations") public class ImageGenerationController { @PostMapping public ResponseEntity<?> submit(@Valid @RequestBody ImageGenerationRequest req) { // 前置参数校验和内容审核 if (!promptGuard.validate(req.prompt())) { return ResponseEntity.badRequest().body(Map.of("error", "prompt 包含违规内容")); } // 配额检查和扣减，稍后详述 boolean quotaOk = quotaManager.tryConsume(currentUserId, estimateCredits(req)); if (!quotaOk) { return ResponseEntity.status(429).body(Map.of("error", "配额不足")); } // 创建任务并提交到管道 ImageTask task = taskService.createTask(currentUserId, req); taskQueue.submit(task); // 返回任务ID，客户端凭此轮询 return ResponseEntity.accepted().body(Map.of("task_id", task.getTaskId())); } @GetMapping("/{taskId}") public ResponseEntity<?> query(@PathVariable String taskId) { ImageTask task = taskService.getByTaskId(taskId); if (task == null) { return ResponseEntity.notFound().build(); } return ResponseEntity.ok(buildTaskDetail(task)); } }从这里能看到，Controller 层很薄，它做的事情是：参数走 Bean Validation，内容走 PromptGuard，配额走 QuotaManager，然后创建任务、丢进队列、返回 taskId。真正干活的是后台的消费线程。这就是管道化的核心思路——接口本身只负责接收意图，不负责生成。
Controller 层的代码和使用方式就这些了，部署多实例时任务状态竞争、死信队列这些高级话题，后面在排查实录里再展开。
5. 防刷架构：限流、配额与幂等设计
5.1 防刷的几个层次：入口限流、用户配额、接口防重
防刷不能只靠一层，拦截器挡掉一部分，业务层再挡一部分，最后配额系统兜底，三层配合才有效。我的划分是这样的：
第一层是接口级别的限流。用 Redis + Lua 脚本，对每个用户+每个接口维度做滑动窗口限流。比如一个用户每分钟最多提交 5 次生图任务，超过就返回 429。这层的目的是拦住脚本的疯狂请求，保护系统稳定性。
第二层是用户维度的配额管理。每个用户每天最多消耗多少 Credits（可以理解成积分），提交任务时尝试扣减，扣减成功才允许创建任务。这层管的是"总量控制"，防止用户把一天的预算一口气刷完。
第三层是幂等设计。用 Idempotency-Key 请求头，用户在提交任务时带一个自己的唯一键，如果同一用户带相同 Key 重复提交，系统直接返回上一次的 task_id，而不是创建新任务。这防止了客户端在网络超时时发起的重试被重复扣费。
三层防刷缺一不可。只做限流，用户今天刷完额度明天继续刷；只做配额，高并发下配额扣减的原子性很难保证；只做幂等，恶意用户通过改写 Key 照样刷爆。
5.2 基于 Redis 的滑动窗口限流实现
限流的算法选择上，我用的滑动窗口而不是固定窗口，原因是不想出现临界问题（比如固定窗口在每分钟的最后一秒请求突发，理论上能打到两倍上限）。滑动窗口的实现我用 Lua 脚本，因为要保证计数和过期检查是原子的。
-- 参数: key, windowStart, windowSize, maxRequests local key = KEYS[1] local currentTime = tonumber(ARGV[1]) local windowSize = tonumber(ARGV[2]) local maxRequests = tonumber(ARGV[3]) -- 移除窗口之前的计数 redis.call('ZREMRANGEBYSCORE', key, 0, currentTime - windowSize) -- 统计当前窗口内请求数 local count = redis.call('ZCARD', key) if count >= maxRequests then return 0 end redis.call('ZADD', key, currentTime, currentTime) redis.call('PEXPIRE', key, windowSize) return 1这样每次请求进来，脚本先清理窗口外的旧数据，再统计当前窗口内的数量，达到上限就拒绝。ZSET 里的 score 和时间戳，member 用时间戳是因为同一毫秒可能会有重复成员，实际使用时我会拼上随机后缀保证唯一性。执行逻辑：
public boolean allow(String userId, String action) { long now = System.currentTimeMillis(); List<String> keys = List.of("rate:" + userId + ":" + action); Long result = redisTemplate.execute(rateLimitScript, keys, String.valueOf(now), String.valueOf(60000), String.valueOf(5)); return result != null && result == 1; }参数（1000ms…我写的是 60000 窗口、5 次上限）只是个示范，实际要按你的业务量调。比如提交生图任务限流 5 次/分钟，查询任务详情限流 60 次/分钟，因为查询是轻量操作，频次可以放宽。
注意：如果你的 Redis 是集群模式，Lua 脚本里用到的 key 必须保证在同一个哈希槽。最简单的方法是对同一个用户限流时只用一个 key，像上面这样，天然在同一个 slot。如果脚本涉及多个 key，就要用哈希标签 {} 来强制路由。
5.3 配额扣减的原子性问题
配额扣减比限流更敏感，因为涉及钱。不能用"先检查再扣减"的非原子操作——在高并发下两个请求同时读到余额充足，同时扣减，最后超卖。
推荐的做法是用 Redis 的 DECR 一次性扣减。但单纯 DECR 有两个问题：余额可能被扣成负数，以及不知道扣之前的余额余多少。所以用 Lua 保证判断与扣减的一体性：
-- 参数: key, cost, minQuota local key = KEYS[1] local cost = tonumber(ARGV[1]) local current = tonumber(redis.call('GET', key) or '0') if current < cost then return -1 end redis.call('DECRBY', key, cost) return current - cost这段逻辑的意思很直白——余额不够就返回 -1，不扣减；够就扣掉并返回剩余余额。它把"检查余额"和"扣减余额"合并成了一个原子操作，彻底消灭了超卖问题。
配额的数据结构我用的是 Redis Hash，每个用户一个 key（quota:user:{userId}），field 是 date（比如 2025-01-15），value 是剩余配额，每天自动过期。之所以不用定时任务清零，而是用带日期的 field，是因为 Redis 的过期时间是以 key 为单位的，用 field 维度天然支持多天数据共存，也方便追溯历史消耗。
配额在生图任务真正成功时才是最终扣减，但提交时预占配额，失败后归还。这个设计很重要，不然失败重试会重复扣费。
5.4 幂等设计与签名机制（开放平台场景）
如果你的接口是面向第三方的开放 API，那防刷还要再提高一个档次。除了限流和配额外，还得有身份认证和防篡改签名。
经典做法是 appKey + appSecret 机制。客户端调用接口时带四个参数：appKey（身份标识）、timestamp（时间戳）、nonce（随机字符串）、sign（签名）。签名是对 appKey + timestamp + nonce + 业务参数按约定拼接后做 HMAC-SHA256。服务端验证：
- appKey 是否存在、是否被禁用
- timestamp 与服务器时间差是否超过 5 分钟（防重放）
- nonce 是否被使用过（用 Redis SETNX，比如 10 分钟过期，防重放）
- sign 是否一致（防篡改）
签名校验放在拦截器里，没有正确的签名请求根本不进 Controller。这一步对开放平台是必须的，否则别人只要拿到你的 Base URL 就能直接刷。
幂等这一层我单独说一个细节：Idempotency-Key 头应该由用户生成，服务端同一用户+同一 Key 只能创建一次任务。实现上在 image_task 表加唯一索引（user_id, idempotency_key），创建任务时如果触发了唯一键冲突，就查出已有任务返回。这种方式是在数据库层面保证幂等，比"查询再判断"更可靠。
6. 常见问题与排查实录
6.1 任务一直卡在排队中，消费线程没跑
这是个高频问题。现象是任务表里 status=0 的记录越来越多，但后台日志里看不到消费记录。
排查路径：先看线程池状态，是不是核心线程全部挂掉了？我遇到过一次是 HTTP 客户端的连接池被打满，所有消费线程阻塞在获取连接上，看起来就是"任务进了队列，但没人处理"。定位方法：jstack 抓线程栈，看到所有线程阻塞在 HttpClient 的连接池获取上，基本就是连接池参数和生图耗时之间的平衡没算好，调大连接池或降低并发就能缓解。
另一种常见原因是数据库连接池太小。消费线程每处理一个任务都要更新数据库，如果数据源连接被别的接口占满，也会出现类似卡住的表现。这种坑在压测环境最容易爆，生产环境反而少见，因为业务量没那么大。
6.2 上游返回 429，自己的限流策略反而先触发了
很多人对接第三方 AI 接口时，优先考虑"我自己别被打崩"，结果忽略了上游也有自己的限流。如果 gpt-image-2.5 的限流是每分钟 60 次请求，你自己的本地限流如果设置得太宽（比如每分钟 200 次），那么冲到上游的第 61 个请求就会被打回来。 对方返回 429 并带着 Retry-After 响应头时，一定要读取并尊重它。我的做法是解析 Retry-After 的值，把该任务丢回重试队列，并设置 next_retry_time = now + retryAfter + 500ms 的缓冲。
更主动的办法是提前做并发控制。我习惯在消费线程上加一个轻量的 Semaphore，限制同时进行中的上游调用数量不超过上游限流阈值的 80%，给上游留点余量。这个缓冲很重要，能明显减少 429 和 5xx。
6.3 重试机制导致任务重复扣费
这是最肉疼的坑。我最早实现失败重试时，用了 HTTP 层的自动重试。上游接口真的超时了，但请求可能其实已经到达服务器并且完成了生成（只是响应体没回来），HTTP 层再次重试就等于让上游生成了两张图，但你的业务表里只记录了第一次调用的失败状态。
这一点我在设计时如何处理？HTTP 层的重试必须关掉或者只用于连接失败场景，真正的重试放在业务层，用任务表的状态和 retry_count 控制。每次调用前生成一个幂等请求 ID（UUID），放进 body 里发给上游，如果上游支持 Idempotency-Key 头，就带上。下次重试同一任务的请求，用同一个 ID，上游就能识别出这是同一个请求，拒绝重复处理或者返回相同结果。
但要注意，gpt-image-2.5 这类接口不一定支持幂等头，所以至少要做到"重试前确认上一次调用确实失败"。比如超时后，不要立刻重试，先调用查询接口确认该次请求在远端是否成功，如果成功就直接把结果捞回来，失败才重试。这个"确认型重试"虽然慢一点，但保住了配额。
6.4 多实例部署时任务被重复消费
应用从单实例扩到多实例后，任务表方案最大的问题暴露了：两台机器同时去捞 PENDING 任务，可能捞到同一个任务。我前面提到过使用 UPDATE 语句带状态条件来抢占。这里再补充完整方案。
每台机器的消费线程从数据库里捞任务时不能直接 select，要使用原子性抢占：
UPDATE image_task SET status = 1, updated_at = NOW(), retry_count = IF(status = 0, retry_count, retry_count) WHERE task_id = #{taskId} AND status = 0如果影响行数为 1，说明这台实例抢到了任务，可以继续。如果为 0，说明已经被别的实例抢走，直接跳过。这个方案没有引入分布式锁，就靠一条带条件的 UPDATE，简单且可靠。等到任务真正返回成功后再把状态改成 2，失败则改回 0 进入重试。
6.5 常见问题速查表
我直接把半年里遇到最多的几个问题整理成表格，方便你对照排查。
| 现象 | 可能原因 | 排查与解决 |
|---|---|---|
| 任务提交后长时间排队中 | 消费线程被阻塞或线程池配置过小 | 查看线程池活动线程数，jstack 定位是否卡在 HTTP/数据库连接 |
| 大量请求返回 429 | 限流阈值设置不合理 | 调大滑动窗口或上限，但注意不能超过上游限额 |
| 上游频繁 5xx | 触发了对方限流阈值 | 用 Semaphore 控制并发到上游阈值的 80%，留出缓冲 |
| 同一任务重复生成 | 重试时请求 ID 不一致 | 使用幂等请求 ID，重试确认机制 |
| 配额扣成负数 | 扣减非原子 | 使用 Lua 脚本合并检查与扣减 |
| 多实例重复消费 | 没有用状态条件抢占 | UPDATE ... WHERE status=0，影响行数判断 |
| 图片 URL 访问超时 | 文件存储或 CDN 回流慢 | 上传到自己的 OSS/COS 或 CDN，不要直接回源引用 |
7. 上线后的几个建议
讲完核心代码和排查实录，最后分享几条我个人在上线后体会特别深的事情。
第一，日志和监控一定要早做。管道类系统最怕盲人摸象，任务卡在哪一层、上游慢不慢、重试占了多少，这些不看监控根本不知道。我在每个关键节点加了埋点：任务提交、消费开始、上游调用耗时、状态流转、结果返回。各阶段的耗时分布一眼能看到瓶颈，上游接口性能下降也能第一时间发现。
第二，配额审计不能省。每次任务消耗了多少 Credits，用户剩余多少，任务成功后实际扣了多少，要有完整记录。不然月底对账时，用户说"我没生成几张图凭什么扣这么多"，你什么都拿不出来。我在 image_task 表里保留了 cost_credits 字段，再配合一张配额流水表，每一笔扣减都有据可查。
第三，图片结果要管理起来。第三方接口返回的 URL 有时效性，或者直接被对方 CDN 托管的图片随时可能失效。上线第一天我就发现了这个问题，用户的图片第二天就 404 了。解决方案是：任务成功后，后台立即把图片下载下来转存到自己的 OSS/COS，再在数据库里更新为内部 URL。这一步虽然增加了一些开发量，但长期价值很大，图片可控、访问速度可控、还能做合规审核。
第四，提示词的未来再生成价值很高。用户提交过的 prompt 和生成的图片配对后，是很有价值的数据资产，可以做"灵感库""相似推荐"等上层功能。所以数据库表结构设计时，尽量预留扩展字段和关联表的空间，别把逻辑写死在单个表里。
这套管道和防刷架构跑下来，实测一个高峰期几千个任务进来，系统稳定、没有超卖、没有重复生成，账单也完全可控。整体代码量不大，但每一行都有它存在的理由，这就是工业级和 demo 的区别。如果你按照这篇的思路去接 gpt-image-2.5 或者往后的各类图像模型接口，核心骨架是不变的：异步管道保证可靠性，状态机控制生命周期，配额和限流守住成本边界。把这三点抓住，你的 AI 生图能力就能从"能跑"进化到"能扛事"。
