电影榜单与影迷社区 · TMDB 对接与缓存降级设计

这个项目解决什么问题

对接第三方 API 的项目很多，但大多有个通病：Key 一失效，整个系统就瘫了。本项目正面回答了这个问题——TMDB 详情数据带过期时间缓存进数据库，回源失败还能用旧缓存撑住；连 Key 都没配置时，自动切换到内置 20 部示例电影的离线演示模式，界面诚实提示、功能照常演示。缓存、降级、兜底，这三件工程上的"成人礼"，这个项目都做了。

核心亮点

• SQLite 缓存层设计：TMDB 详情缓存进数据库并带 24 小时过期时间，回源失败时仍可使用旧缓存。课程汇报时可以完整讲一遍"缓存 TTL 与雪崩兜底"——而且全程零 Redis 依赖，SQLite 就够。
• 影评质量分：长度、被赞数、评论数加权计算，影评列表可按质量分排序，水贴自然沉底。一个简单公式，让社区内容生态肉眼可见地变好。
• 社交关系建模：关注动态流 + 想看/看过收藏夹 + 点赞互动。关注/收藏这类"多对多"关系怎么设计、动态流怎么查，都是能单独展开讲的数据库设计题。
• 个性化推荐：同好高分电影的交集 + 相似电影，三级降级策略保证任何情况下推荐区都不开天窗。
• 无 Key 也能跑：未配置 TMDB API Key 时自动切换离线演示模式（下面的截图正是该模式）；配置 Key 后无缝接入真实数据。免费申请即可，README 附申请地址。
• Markdown 影评 + XSS 过滤：支持 Markdown 排版的同时用 bleach 白名单过滤，内容安全这块没有偷懒。

效果预览

FilmCircle 首页——热映榜电影卡片带评分与日期，顶部诚实提示当前处于"离线演示模式"：

电影详情页——TMDB 评分 8.4 与本站评分 9.0 并排对比，影评列表带质量分徽章：

你将学到

• 第三方 API 对接的完整姿势：鉴权、限流、超时、降级
• 缓存思想：TTL 过期、缓存穿透的兜底策略（不需要 Redis 也能讲明白）
• 社交关系的数据建模：关注、点赞、收藏的表设计与查询
• 内容安全：Markdown 渲染与 XSS 白名单过滤
• 优雅降级的产品思维：功能依赖外部服务时，如何保证"永远有东西可看"

适合谁

想在毕设里体现"工程成熟度"而不只是"功能堆砌"的学生——缓存与降级这两个话题，课程汇报时天然容易出彩。难度 ★★★★，涉及外部服务对接和社交关系建模，适合有一定 Flask 基础的学习者。

交付内容：完整可运行源码、README.md（逐步运行方法与实现说明）、requirements.txt。

许可：个人使用，可用于自己的学习、课程实验与研究报告，请勿转售或公开传播。

环境与步骤

pip install -r requirements.txt

pip install -r requirements.txt
python app.py

注意事项

• 榜单数据走 TMDB 公开接口，需自行申请免费 API Key；包内有缓存可离线演示。

Q：一定要有 TMDB API Key 吗？

A：不必须。README 提供“无 Key 演示模式”，用包内缓存数据即可跑通全部界面；要拉实时榜单与详情，就去 themoviedb.org/signup 申请免费 Key 填进 .env。

Q：缓存为什么用 SQLite 而不是 Redis？

A：项目刻意做零 Redis 依赖：电影详情缓存进 SQLite 并带 24 小时 TTL，回源失败时仍返回旧缓存兜底，这条降级链路在 README 里有完整说明，也方便断网演示。

Q：社区部分包含哪些功能？

A：关注、点赞、影评。影评带质量分（长度、被赞数、评论数加权），列表可按质量分排序，水贴自然沉底。

Q：端口是多少？

A：Flask 默认 http://127.0.0.1:5000 ，首页是榜单，点进详情看影评与相关电影。