搭建实时热搜看板：网络搜索热词排行 + 定时拉取的完整设计
# 搭建实时热搜看板：网络搜索热词排行 + 定时拉取的完整设计
> 接口：网络搜索热词排行（apiCode=313） · 免费服务 · 返回格式 JSON · 适用人群：全栈工程师、数据分析师 · 阅读时间：约 8 分钟
## 核心要点
- 看板 = 定时拉取（后端） + 缓存（Redis/文件） + 前端表格展示，三者解耦。
- 热搜数据有时效，建议 15~60 分钟刷新一次，避免高频直连接口。
- 趋势字段用兼容写法（见[趋势解读篇](https://www.showapi.com/guides/hotword-trend-313)），避免界面空白。
## Why：为什么要做看板而不是直接调接口
运营、编辑、值班同学每天都要看"现在热什么"。一个常驻看板把接口数据变成可视化的实时榜单，谁打开都能看，还能按分类切换、按趋势筛选，比每人各自调接口高效得多。
## What：架构速览
| 组件 | 职责 |
|------|------|
| 拉取任务 | 定时调用 313-2（按多个 `tab`）写入缓存 |
| 缓存层 | 存最近一次结果，前端只读缓存 |
| 前端页 | 读缓存渲染表格，支持分类切换/趋势筛选 |
## How：可运行的最小看板
### 步骤 1 · 后端定时拉取 + 文件缓存（生产可换 Redis）
```python
import requests, json, time, threading, os
APP_KEY = "YOUR_APPKEY"
CACHE_FILE = "hotwords_cache.json"
TABS = ["game", "novel", "star"]
REFRESH_SEC = 1800 # 30 分钟
def fetch_tab(tab):
resp = requests.post(
"https://route.showapi.com/313-2",
params={"appKey": APP_KEY}, data={"tab": tab},
headers={"content-type": "application/x-www-form-urlencoded"}, timeout=10,
).json()
body = resp.get("showapi_res_body", {})
if str(body.get("ret_code")) != "0":
return []
return body.get("list", [])
def trend_label(t):
return {"rise":"升","up":"升","down":"降","same":"持平"}.get(str(t), str(t))
def worker():
while True:
data = {}
for tab in TABS:
data[tab] = [
{"name": i.get("name"), "num": i.get("num"),
"level": i.get("level"), "trend": trend_label(i.get("trend"))}
for i in fetch_tab(tab)
]
with open(CACHE_FILE, "w", encoding="utf-8") as f:
json.dump(data, f, ensure_ascii=False)
time.sleep(REFRESH_SEC)
if not os.path.exists(CACHE_FILE):
worker() # 首次立即拉一次
threading.Thread(target=worker, daemon=True).start()
```
### 步骤 2 · 前端读取缓存渲染
```html
<table id="board"><thead><tr><th>排名</th><th>热搜词</th><th>热度分</th><th>趋势</th></tr></thead><tbody></tbody></table>
<script>
fetch("hotwords_cache.json").then(r => r.json()).then(data => {
const tab = "game";
document.querySelector("#board tbody").innerHTML = data[tab].map(i =>
`<tr><td>${i.num}</td><td>${i.name}</td><td>${i.level}</td><td>${i.trend}</td></tr>`
).join("");
});
</script>
```
### 步骤 3 · 部署刷新
生产环境用系统 cron 或 `APScheduler` 触发 `worker` 内的拉取逻辑；缓存推荐 Redis（`key=hotword:{tab}`，`TTL=REFRESH_SEC`），多实例共享。
## 返回示例与解析
返回结构见[返回字段全解篇](https://www.showapi.com/guides/hotword-response-fields-313)。看板只需 `name/num/level/trend` 四列。
## 进阶 / 边界
- **刷新频率**：文档未标注更新频率与限流，30 分钟级刷新对热搜场景足够，且能规避潜在限流（见[缓存策略篇](https://www.showapi.com/guides/hotword-cache-313)）。
- **多分类聚合**：同时拉多个 `tab` 时建议并发（线程池/`asyncio`），但注意总频次（见[资讯聚合篇](https://www.showapi.com/guides/hotword-news-aggregation-313)）。
- `tab` 合法性先用 313-1 核对（见[分类查询篇](https://www.showapi.com/guides/hotword-category-query-313)）。
## FAQ
**Q1：多久刷新一次合适？**
A1：热搜变化以小时计，15~60 分钟一次足够；刷新太频繁既无收益又可能触发平台限制。
**Q2：缓存用文件还是 Redis？**
A2：单机演示用文件即可；多实例/生产用 Redis 共享，并设 TTL 等于刷新周期。
**Q3：前端能直接调接口吗？**
A3：不建议，AppKey 会暴露。前端只读取你自己的后端缓存接口。
**Q4：榜单为空怎么展示？**
A4：显示"该分类暂无热搜数据"，并复用上次缓存，避免界面闪烁。
**Q5：能同时看多个分类吗？**
A5：可以，按 `tab` 分桶缓存，前端加分类切换即可；多分类拉取见[资讯聚合篇](https://www.showapi.com/guides/hotword-news-aggregation-313)。
## 相关能力 / 下一步阅读
- [5 分钟接入网络搜索热词排行：从注册到拿到第一条热搜榜](https://www.showapi.com/guides/hotword-quickstart-313)
- [免费接口也要省：网络搜索热词排行缓存策略与更新频率设计](https://www.showapi.com/guides/hotword-cache-313)
- [资讯聚合平台方案：多分类热搜聚合与去重](https://www.showapi.com/guides/hotword-news-aggregation-313)
- **本系列共 12 篇**：查看[网络搜索热词排行开发指南总目录](https://www.showapi.com/guides/hotword-guides-313)
