Lampa如何集成TMDB API:影视目录数据获取与缓存策略完整指南
Lampa如何集成TMDB API:影视目录数据获取与缓存策略完整指南
Lampa 是一款运行在电视和桌面端的免费流媒体应用,它的电影、剧集目录与海报数据全部来自 TMDB API。本文将带你拆解 Lampa 是如何封装 TMDB 接口请求、组装查询参数,并通过"内存 + IndexedDB"的多级缓存策略,让目录翻页秒开、海报稳定加载的,适合想深入了解其数据层设计的新手与开发者。
认识 Lampa:为什么目录数据交给 TMDB
Lampa 本身不存储任何电影资料,也不提供视频托管,它只做两件事:从 TMDB 拉取目录数据,再从公共网络源解析播放地址。因此整个"电影目录"体验(海报墙、评分、简介、演职员、推荐)都取决于 TMDB 接口调用得有多高效。
Lampa 支持 LG WebOS、Samsung Tizen、Android、Windows、macOS 等多平台部署,可以通过 Dockerfile 一键构建镜像,或按 README.md 中的 MSX 说明上传到自有主机,msx/start.json 中配置好域名即可安装。
接口封装:TMDB 模块的 4 个核心方法
Lampa 将 TMDB 集成收敛在一个轻量模块里(见 app.min.js),对外只暴露 4 个方法:
| 方法 | 作用 |
|---|---|
api(url) |
拼接 api.themoviedb.org/3/ 前缀,生成数据接口地址 |
image(url) |
拼接 image.tmdb.org/ 前缀,生成海报/背景图地址 |
key() |
返回内置的 TMDB API Key,免去用户配置 |
broken() |
统计海报加载失败次数,触发自动代理 |
关键设计有 3 点:
- 零配置:API Key 直接内置在客户端(app.min.js),用户装完即用,不需要自己去 TMDB 官网申请密钥;
- 代理可插拔:当检测到
proxy_tmdb开关打开时,api()和image()会自动把请求前缀替换成用户填写的tmdb_proxy_api/tmdb_proxy_image代理地址(app.min.js); - 失败自愈:海报连续失败超过 50 张时,若开启了"自动启用代理",客户端会自动打开 TMDB 代理开关(app.min.js)。
请求组装:一个查询参数生成器的复用
所有 TMDB 请求(目录、搜索、详情、剧集)都经过同一个参数组装函数(app.min.js),它会自动追加:
api_key:内置密钥;language:由设置项tmdb_lang决定,还支持多语言兜底(先查本地语言,再查英文);page、query、with_genres、sort_by、with_keywords、with_watch_providers等分页与筛选参数。
以搜索为例,Lampa 会并行发起 电影、剧集、人物 三路搜索请求(app.min.js),用一个状态计数器 Status(3) 等三路都返回后再合并结果。目录翻页列表则带有"过滤后整页为空就自动取下一页"的补偿逻辑,保证用户看到的每一页都是满的(app.min.js)。
缓存策略揭秘:三级缓存让目录秒开
Lampa 的 TMDB 数据不是"每次刷新都重新请求",而是分三层缓存:
1. 请求级缓存(带 TTL)
每次 TMDB 请求都通过统一入口 get() 发出,可携带 { life: 分钟数 } 的缓存参数(app.min.js)。不同数据的保鲜期被精心分级:
| 数据类型 | 缓存时长 | 原因 |
|---|---|---|
| 影视详情页(含演职员、推荐、相似片) | 7 天 | 详情变化慢,app.min.js |
| 目录/翻页列表 | 2 天 | 榜单缓慢变动,app.min.js |
| 影视剧集某季信息 | 3 天 | 新季更新不频繁 |
| 影片"家庭发行日" | 1 天 | 发行日期几乎不变 |
2. 内存级缓存(去重并发)
"仅显示已发行"过滤需要逐个查询影片的发行日期。Lampa 用一张内存表 released_dates(影片 ID → 日期)记录结果,并把等待中的回调挂到 released_waiting 队列:同一部影片的并发请求只发一次网络请求,"查无结果"的影片 24 小时内不再重查(app.min.js)。这是典型的"请求去重 + 短期记忆"模式。
3. IndexedDB 持久化缓存
页面级数据(卡片、海报、背景图等)落到浏览器的 IndexedDB,统一由 Cache 实例管理,内含 cards、images、timetable、storage 等 9 个数据仓库(app.min.js)。配合 Storage.cache(name, limit, default) 接口(app.min.js),书签、观看进度等数据都能带条数上限地持久化,重启电视后依然秒开。
可用性保障:海报镜像轮询与自动封禁
海报域名 image.tmdb.org 在某些网络环境下不稳定,Lampa 内置了一套镜像轮询器(app.min.js):
- 维护
imagetmdb.com等多个镜像的实时状态; - 某个镜像 10 秒内出错 20 次即被临时封禁,自动切到下一个可用镜像;
- 当前选中的镜像写入
tmdb_img_mirror设置项,下次启动优先沿用; - 配合"自动启用代理"开关,海报大面积失败时整体切到用户或内置的 TMDB 代理(app.min.js)。
这套"镜像池 + 失败计数 + 自动封禁"机制,让海报加载的成功率远超直连单一域名。
动手实践:在设置中调整 TMDB 行为
Lampa 的 TMDB 相关设置集中在设置页的"目录数据"面板(界面模板见 app.min.js,中文文案见 lang/zh.js),常用项包括:
| 设置项 | 说明 |
|---|---|
| TMDB 语言 | 控制目录、简介的展示语言 |
| TMDB 海报分辨率 | 对应请求图片时的尺寸参数 |
| 仅显示已发行 | 隐藏还在影院上映、未首播的影片 |
| 代理 TMDB / 自动启用代理 | 数据与图片走代理,失败自动开启 |
| Api / Image 代理地址 | 分别填写数据接口和海报图的代理前缀 |
新手建议的 3 个调优步骤:
- 先把 TMDB 语言设为自己熟悉的语言(如中文地区可选对应语言代码);
- 电视网络访问
api.themoviedb.org不畅时,打开"代理 TMDB"并让"自动启用代理"保持开启; - 缓存数据过多占用存储时,在设置里使用"清除缓存"(文案见 lang/zh.js),基础设置会被保留。
小结:Lampa 数据层设计可借鉴的 3 点
- 单一出口封装:所有 TMDB 调用收口在一个模块里,代理、语言、密钥全部集中处理,业务代码不感知 URL 细节;
- 分级 TTL 缓存:按数据"易变程度"分配 1 天~7 天不等的缓存时长,详情页最长效、列表次之、日期类最短;
- 失败自愈:海报镜像池自动封禁坏节点、请求去重合并并发、网络错误时宁可展示也不空白。
这套"轻客户端 + 远端目录 + 多层缓存"的架构,正是 Lampa 在电视这种弱交互设备上依然流畅的关键。如果你想深入源码,核心入口都在 app.min.js,配合 index.html 的页面骨架阅读效率最高。



