如何确定哪些接口适合使用第一层缓存？

第一层（浏览器 HTTP Cache max-age=300s）接口筛选判定标准（适配 Not Quite RARBG）

第一层 = 浏览器端缓存（Cache-Control: public, max-age=300），只给完全静态、无用户私有数据、5 分钟延迟完全可接受的接口使用；凡是带用户标识、实时状态、写入操作的接口一律禁用第一层缓存。 下面给出判定公式、筛选维度、接口划分清单、排查校验方法、边界处理方案。

一、四条硬性准入规则（必须同时全部满足，才能开第一层 5 分钟缓存）

规则 1：接口为纯 GET 只读接口

1. 只允许GET / HEAD 请求；POST、PUT、DELETE、PATCH 这类提交、上报、修改类接口绝对不能开浏览器缓存。
2. 原理：浏览器会自动缓存 POST 请求极少，且提交行为（种子上报、订阅、反馈）不能被本地缓存复用。

规则 2：接口返回数据是公共全局数据，不含任何用户私有信息

✅ 允许：榜单、全平台资源列表、公开影片资料、公开种子列表、分类数据、公共排行榜 ❌ 禁止：我的收藏、下载记录、浏览历史、个人订阅、用户权限配置、个性化推荐（带 uid 区分内容）

核心风险：浏览器缓存文件存在本地，不同用户复用同一缓存响应，会造成 A 用户拿到 B 用户私有数据。

规则 3：数据业务容忍 300s（5 分钟）数据延迟

资源类业务特性：种子新增、榜单排名变动是平缓增量变化，用户检索、下载资源时，5 分钟旧数据几乎无感知。 下述场景天然兼容延迟：

• 首页 TOP 榜单、影视分类目录、检索结果列表、影片基础元数据（封面、年份、简介） 不能容忍延迟的接口（种子实时在线人数、磁力实时活性检测）放弃第一层缓存，仅服务端缓存即可。

规则 4：相同请求参数，所有用户拿到的返回结果完全一致

同一个url + query参数（关键词/页码/筛选条件），不管是谁访问，响应内容一模一样。 举例：/api/search?key=movie&page=1，所有用户访问返回同一批种子 → 符合； 接口携带token、uid、deviceId等身份参数 → 同一链接不同用户数据不同 → 不符合第一层缓存条件。

二、细化 5 个筛选判断维度（逐条核对）

1. 数据变更频率维度

表格

数据更新频率	是否适合第一层缓存	说明
低速更新（分钟 / 小时级别刷新）	✅ 推荐开启 5min 浏览器缓存	榜单、分类、影片资料库、检索列表
中速更新（几十秒变动）	❌ 关闭第一层，只留服务端缓存	种子 peer 连接数、实时热度值
实时动态数据（秒级刷新）	❌ 全层级都缩短 TTL，禁用浏览器缓存	种子存活检测、实时下载测速

2. 接口访问量级（热点优先配置第一层）

高 QPS 热点接口优先部署第一层缓存，直接在用户浏览器拦截请求，大幅降低后端服务器压力： 适合开第一层：首页、排行榜、热门分类、高频搜索词结果 低频冷门检索、小众影片详情：可开也可不开，收益很低，按需配置即可

3. 响应体积与带宽消耗

返回大体积 JSON（上千条种子列表、长列表数据），开启浏览器缓存收益极高，重复访问不再走外网传输数据，节省服务器出口带宽。

4. 是否依赖登录态

1. 无需登录即可访问的公开接口 → 放心开启第一层缓存
2. 必须携带 token 鉴权、登录后才可查看的接口：
   • 若鉴权只是门禁，返回数据依旧是公共数据：设置Cache-Control: private, max-age=300
   • 鉴权后返回个性化数据：彻底关闭浏览器缓存

5. 接口容错性

即使缓存数据过期 5 分钟，不会引发功能异常、报错、无效下载、页面错乱 → 合格； 如果接口数据过期会直接导致磁力链接失效、页面报错 → 不建议浏览器缓存。

三、NQRBG 接口精准划分清单（直接落地使用）

🔴 【完全适配，强制开启第一层 5min 缓存】

plaintext

GET /api/category 全部分类资源列表 GET /api/rank/hot 热门榜单、首页推荐榜单 GET /api/search 关键词检索（公开资源） GET /api/movie/detail 影片基础信息+附属种子列表 GET /api/list/latest 最新入库资源列表 GET /api/filter/* 条件筛选资源接口

响应头配置标准写法：

http

Cache-Control: public, max-age=300 ETag: 基于响应JSON内容生成md5哈希

搭配 ETag 协商缓存：缓存没过期直接返回 200 (from disk cache)；资源更新后服务端返回新数据。

🟡 【谨慎开启，private 模式有限使用第一层缓存】

接口需要 Token 鉴权，但返回内容依旧是公共数据（登录才能浏览资源详情）

plaintext

GET /api/subscribe/publiclist

配置改为私有缓存，不会在浏览器缓存之间互相共享：

http

Cache-Control: private, max-age=300

⚫ 【严禁开启第一层浏览器缓存】

1. 写入 / 提交接口POST /api/report/torrent种子报错上报、POST 反馈提交
2. 用户私有数据接口GET /api/user/collect我的收藏、下载历史、浏览记录
3. 强实时数据GET /api/torrent/health种子实时存活节点、在线人数检测
4. 后台管理接口 管理员刷新数据、手动同步源站接口，需要实时最新数据

四、快速自检流程（拿到任意接口，3 秒判断）

1. 请求方式是不是纯 GET？→ 否 → 不开第一层缓存
2. 返回数据是否和用户身份无关？→ 有关 → 不开
3. 5 分钟旧数据会不会影响用户正常使用？→ 会 → 不开
4. 同一 URL + 参数，所有人返回数据一致？→ 不一致 → 不开 全部满足 → 配置max-age=300浏览器缓存

五、配套兜底优化（开启第一层缓存必加）

1. ETag/Last-Modified 协商缓存兜底就算缓存未过期，服务端比对 ETag 发现数据已更新，返回新内容；数据无变化返回304 Not Modified，零数据传输。
2. 紧急刷新机制 后台提供强制刷新参数?no_cache=1，带上该参数服务端返回Cache-Control: no-cache，绕过浏览器缓存获取实时数据。
3. 静态资源（页面 css、js、图片）和接口数据缓存区分开 接口业务数据固定 5min，前端静态资源使用长缓存 + 文件哈希戳，不要混为一谈。

六、第一层缓存的收益边界

• 热点页面重复刷新、重复搜索：请求直接被浏览器消化，不会抵达后端服务
• 外网流量、服务器入站 QPS 下降最明显，配合第二层服务端内存 + Redis 缓存形成双层流量拦截
• 缺点：数据最多延迟 5 分钟，刚好匹配种子站点的业务特性，无负面体验
•