图片水印裁剪缩略接口：高并发图片处理架构（客户端异步+重试）
# 图片水印裁剪缩略接口：高并发图片处理架构（客户端异步+重试）
> 接口/接入点：图片水印裁剪缩略接口（apiCode=1）· 全部接入点 · 是否免费：免费（有档位限制） · 请求方式：POST/GET · 返回格式：JSON · 适用人群：中高级开发者、架构师 · 阅读时间：8 分钟
## 核心要点
- 图片处理是 IO 密集型，同步阻塞调用在大并发下会把线程/连接池占满。
- 文档**未提供**服务端订阅/回调能力，因此「异步」只能在客户端做：任务入队 → worker 消费 → 结果落库 → 前端轮询/通知。
- 配合[频率控制篇](https://www.showapi.com/guides/image-process-ratelimit-1)的令牌桶与指数退避，才能在免费档位下稳定跑量。
## Why：大并发为什么要异步
一次图片处理几百毫秒，若每个请求都同步等结果，100 个并发就能把服务拖垮，也容易触发免费档位限流。把"请求处理"和"拿到结果"解耦，系统更稳、用户体验更好（先返回"处理中"）。
## What：已知能力边界
- 同步返回：`showapi_res_body.des_pic_url` 即时返回（成功即出图）。
- **无** webhook / 订阅推送 / 异步回调（文档未出现）。所以不要设计"等服务器回调"的流程。
- 所有削峰、重试、落库都在调用方实现。
## How：客户端任务队列削峰
**架构**
```
上传/触发 → 任务表(status=processing) → 队列(Celery/RabbitMQ/Redis)
→ Worker: 调接口(令牌桶+退避) → 结果写回任务表(des_pic_url,status=done)
→ 前端: 轮询/WebSocket 读任务表
```
**Python（Worker 伪代码，含限流）**
```python
import requests, time
def worker(task):
for i in range(3):
r = requests.post("https://route.showapi.com/1-1", params={"appKey":"YOUR_APPKEY"},
data={"type":"rate","rate":"0.6"}, files={"src_img": open(task.path,"rb")}, timeout=10)
body = r.json()["showapi_res_body"]
if str(body.get("ret_code")) == "0":
save_result(task.id, body["des_pic_url"], "done") # 落库
return
time.sleep(2 ** i) # 退避
save_result(task.id, None, "failed")
```
**前端轮询（示意）**
```javascript
async function poll(taskId) {
for (let i=0; i<30; i++) {
const t = await (await fetch(`/api/task/${taskId}`)).json();
if (t.status === "done") return t.des_pic_url;
if (t.status === "failed") throw new Error("处理失败");
await new Promise(r => setTimeout(r, 1000));
}
}
```
## 返回示例
```json
{ "showapi_res_body": { "ret_code": "0", "des_pic_url": "http://app1.showapi.com/temp/1.jpg" } }
```
## 进阶/边界
- 不要为"异步"去等待一个不存在的服务端回调；本接口只有同步返回。
- Worker 并发数要受令牌桶约束，避免自己把免费档位打满。
- `des_pic_url` 可能过期，落库时建议顺手下载归档到自有存储。
## FAQ
**Q1：接口支持回调吗？** 文档未提供订阅/回调，仅同步返回，异步逻辑全在客户端。
**Q2：Worker 挂了任务怎么办？** 任务表留 `processing` 状态，加定时任务捞回重跑（带退避）。
**Q3：前端怎么知道好了？** 轮询任务表，或任务完成时推 WebSocket；不要等接口主动通知。
**Q4：批量商品图？** 见[电商方案](https://www.showapi.com/guides/ecommerce-image-plan-1)，本质就是本架构 + 限流。
## 相关能力 / 下一步阅读
- [图片水印裁剪缩略接口：免费档位限制与频率控制，如何避免触发限流](https://www.showapi.com/guides/image-process-ratelimit-1)
- [图片水印裁剪缩略接口：电商商品图批量水印+缩略一体化方案](https://www.showapi.com/guides/ecommerce-image-plan-1)
- **本系列共 13 篇**：查看[图片水印裁剪缩略接口指南总目录](https://www.showapi.com/guides/image-process-guides-1)
