周公解梦 API 免费档位与调用限制说明：如何避免触发限流？
# 周公解梦 API 免费档位与调用限制说明：如何避免触发限流？
> 接口：免费解梦详细（apiCode 1601）· 接入点：解梦详细（1601-2）· **免费但有限制** · 适用人群：已接入、关注成本与稳定性的开发者 · 阅读约 6 分钟
## 核心要点
- 本接口**注册后默认可免费调用**，但「为防止滥用设有使用档次限制」——具体档位数值文档未给出，以[免费档位说明](https://www.showapi.com/free-api)为准，本文不编造数字。
- 限流的本质是「调用次数/频率」约束，客户端做**本地缓存 + 节流**是最直接的解法。
- 同一 `(keyWords, page)` 结果是稳定可复用的，短缓存即可大幅降低调用量。
## Why：这跟我有什么关系
免费不等于无限。你上线一个解梦小工具，用户一多，重复查询同一个热门词（「蛇」「结婚」「掉牙」）会把档位吃满，触发限制。本文给一套可直接落地的缓存与节流方案，让你在免费额度内稳稳跑。
## What：前置条件与接口速览
| 项目 | 说明 |
|------|------|
| 是否免费 | 是（注册后默认可免费调用） |
| 限制机制 | 使用档次限制，防滥用（具体档位见[免费档位说明](https://www.showapi.com/free-api)） |
| 接口地址 | `https://route.showapi.com/1601-2?appKey={your_appKey}` |
| 缓存依据 | `keyWords` + `page` 决定结果，可复用作缓存键 |
| 接入点说明 | 内容参考《周公解梦全书》部分信息，提供解读参考（文化参考，非科学/医疗结论） |
## How：用缓存把调用量降下来
**思路**：以 `(keyWords, page)` 为键做短缓存；命中缓存直接返回，未命中才请求。梦境解读内容更新频率低，缓存几分钟完全够用。
**Python（内存 + Redis 两套写法）**
```python
import requests, hashlib, json, time
APP_KEY = "YOUR_APPKEY"
URL = "https://route.showapi.com/1601-2"
CACHE_TTL = 600 # 10 分钟
_mem = {}
def fetch_dream(keyword: str, page: str = "1", use_cache: bool = True):
key = f"{keyword}|{page}"
if use_cache and key in _mem:
ts, val = _mem[key]
if time.time() - ts < CACHE_TTL:
return val # 命中内存缓存，不请求
resp = requests.post(
URL, params={"appKey": APP_KEY},
data={"keyWords": keyword, "page": page},
headers={"content-type": "application/x-www-form-urlencoded"},
timeout=10,
)
data = resp.json()
if data.get("showapi_res_code") != 0:
raise RuntimeError(data.get("showapi_res_error"))
body = data["showapi_res_body"]
if body.get("ret_code") != "0":
raise RuntimeError(f"ret_code={body.get('ret_code')}")
_mem[key] = (time.time(), body)
return body
```
**Redis 版本（多实例共享缓存）**
```python
import redis, requests, json
r = redis.Redis(host="127.0.0.1", port=6379, db=0)
def fetch_dream_redis(keyword: str, page: str = "1", ttl: int = 600):
cache_key = f"dream:1601:{keyword}:{page}"
hit = r.get(cache_key)
if hit:
return json.loads(hit)
# ... 同上请求逻辑得到 body ...
body = _do_request(keyword, page)
r.set(cache_key, json.dumps(body, ensure_ascii=False), ex=ttl)
return body
```
**节流（令牌桶，控制突发）**
```python
import time
class RateLimiter:
def __init__(self, rate: float, capacity: int):
self.rate, self.capacity = rate, capacity
self.tokens, self.ts = capacity, time.time()
def acquire(self):
now = time.time()
self.tokens = min(self.capacity, self.tokens + (now - self.ts) * self.rate)
self.ts = now
if self.tokens >= 1:
self.tokens -= 1
return True
return False # 被限流，稍后重试
```
## 返回示例与解析
缓存命中时直接复用上一次 `showapi_res_body`；未命中才真实请求，返回结构见《[返回字段全解](https://www.showapi.com/guides/dream-response-fields-1601)》。
## 进阶 / 边界
- **具体档位数值文档未给**：本文不编造任何次数/频率数字；上线前请到[免费档位说明](https://www.showapi.com/free-api)确认你的档位上限，并据此设定缓存 TTL 与令牌桶速率。
- **缓存键要含 page**：分页场景下 `(keyWords, page)` 才能唯一确定结果，只按关键词缓存会串页。
- **重试要退避**：偶发失败时做指数退避（如 0.5s→1s→2s），不要把失败请求无脑重试刷爆档位。
- **内容为文化参考**：展示时加「仅供娱乐参考」提示，不要包装成科学/医疗结论。
## FAQ
**Q1：免费接口一天能调多少次？**
具体档位文档未给出，以[免费档位说明](https://www.showapi.com/free-api)为准；用本文缓存方案可显著减少实际调用。
**Q2：缓存会不会让用户看到过期内容？**
梦境解读更新频率低，10 分钟级 TTL 足够；如对时效性敏感可缩短 TTL 或提供「刷新」入口。
**Q3：被限流了会返回什么？**
按接口约定，`ret_code` 非 0 表示业务失败；具体限流表现以档位说明与返回 `showapi_res_error` 为准，不要假设固定错误码。
**Q4：多台机器怎么共享缓存？**
用 Redis 等中心化缓存（见上文），键统一为 `dream:1601:{keyWords}:{page}`。
**Q5：除了缓存还有别的省额度办法吗？**
控制重试次数、批量离线预取热门词、前端做「加载更多」而非全量预拉，都能降调用。
## 相关能力 / 下一步阅读
- [周公解梦 API：5 分钟接入，从注册到查出第一个梦境解读](https://www.showapi.com/guides/dream-quickstart-1601)
- [周公解梦 API 返回字段全解：ret_code、contentlist、分页字段一文读懂](https://www.showapi.com/guides/dream-response-fields-1601)
- [周公解梦 API 应用场景：娱乐 App / 内容社区 / 客服如何嵌入梦境解读？](https://www.showapi.com/guides/dream-scenarios-1601)
- **本系列共 8 篇**：查看[周公解梦 API 指南总目录](https://www.showapi.com/guides/dream-guides-1601)
