企业官网建设流程全解析

网课题库接口这个东西，做过在线答题、刷题小程序、培训考试系统的人应该都不陌生。真正让人头疼的从来不是前端那几个页面，而是背后那几十万道题：题干、选项、答案、解析、章节归属、难度标签，还有各种题型混排。于是很多人一看到「免费开源、永久免费调用、已附带密钥、直接使用」这类标题，第一反应就是赶紧把接口接进来跑通。我一开始也是这个思路，后来踩了几次坑才明白，接口能不能调通只是最表层的门槛，真正的功夫在于：怎么判断这个接口的数据结构合不合理、密钥和限流该怎么用、客户端怎么封装才不至于到处散落请求代码、以及最关键的——当对方接口哪天变了、慢了、挂了，你的系统怎么不死。

这篇内容就是围绕 ZERO 这套网课题库接口展开的一次完整拆解。我会从它解决什么问题讲起，把接口设计、鉴权限流、跑通流程、自建迁移、故障排查这几块摊开来讲，代码能抄就抄，参数怎么算也写清楚。适合三类人看：正在做答题类产品、手头缺题库数据源的开发者；想拿这套接口做课程作业或者个人练手项目的同学；以及已经接了接口、但被超时和脏数据折磨过、想搞清楚底层逻辑的人。哪怕你完全没接触过 HTTP 接口，跟着第 4 章的步骤走一遍，也能跑出结果。

1. 先搞清楚这套题库接口到底解决什么问题

1.1 网课题库的真实痛点：不是没题，是没结构

很多人以为题库的难点在「题目数量」，其实不是。网上能找到的题目素材多得是，Excel 表格、Word 文档、PDF 习题册，随便一搜一大把。难点在于这些东西全是非结构化或者半结构化的：一道选择题可能占三行，选项用 A、B、C、D 标，也可能用 ①②③④，答案解析有的跟在题目后面，有的统一放在文末。你把这些原始素材变成能用的数据，中间要经过清洗、切分、字段对齐、题型归类、答案校验，这一套流程做下来，一个人干两周可能只处理完几千道题。

所以一套题库接口的价值，本质上不是「给你题」，而是把脏活累活提前干完了，直接给你结构化的 JSON。你拿到的每一条记录都长一个样：题干是字符串、选项是数组、正确答案是数组或者字符串、解析是纯文本、还有章节和难度标签。这才是接口真正的卖点。理解这一点很关键，因为它决定了你评估一个接口的第一标准应该是字段设计稳不稳、语义清不清楚，而不是「题目多不多」。

我见过不少项目，接到接口后直接把返回的 JSON 原样塞进前端，前端再根据字段名硬编码渲染逻辑。这种写法在接口稳定的时候没问题，一旦对方调整了字段命名或者题型枚举值，整个页面就白了。所以从第一行代码开始，就要有一个「接口返回是外部数据，必须经过一层适配」的意识。这一层适配不只是字段映射，还包括类型转换、空值兜底、异常题型降级。后面第 4 章我会给一个可复用的适配层写法。

另外还有一类常见误区，是把接口当成「实时数据库」用。每次用户点开一题就请求一次，翻页请求一次，搜索请求一次。这种用法在本地开发环境看不出问题，一上线用户量上来，请求数直接爆炸，超时、限流、被封密钥全来了。接口的正确用法是批量拉取 + 本地缓存，把接口当成数据同步通道，而不是查询引擎。这个思路的转变，能省掉后面九成的性能问题。

1.2 「永久免费、无限制」这类说法，工程上该怎么理解

先把话说透：工程世界里不存在真正意义上的「无限制」。任何对外提供的接口，背后都有服务器、带宽、数据库连接数这些硬成本。所谓「无限制」，通常指的是服务方当前不主动对普通调用方做配额限制，而不是「你压多少它都能扛」。这两者的区别，在你自己做技术方案时是天壤之别。

我在实际接入时的做法是，默认给自己加上限制，而不是等对方来限。具体来说有这么几层考虑：单次批量拉取的条数控制在 50 到 100 条之间，太大了响应体会变长、解析变慢，太小了请求次数多；本地做一层持久化缓存，同一个知识点下的题目拉过一次就不再重复拉；对同一个接口地址做并发控制，同一时刻最多两到三个请求在飞，避免瞬间打满。

还有一个容易被忽略的点：免费接口的时间可用性没有承诺。付费服务通常有 SLA 保障，免费开源项目往往是个人或小团队维护，服务器到期、域名变更、项目停止维护，这些情况都真实发生过。我个人的经验是，只要你把题库用在了有真实用户的产品上，就必须假设「这个接口明天可能不可用」，并为此准备数据自持的方案。第 6 章会详细讲迁移路径，这里先埋个引子。

再补一个判断标准，帮你评估这类项目值不值得投入：看它有没有版本化的接口路径和明确的字段文档。有/v1/这种版本前缀，说明作者考虑过兼容性；有字段说明表格，说明数据结构是经过设计的；能给出错误码列表，说明作者想过别人怎么排查问题。这三点齐了，接入成本会低很多。

1.3 适合接入的三种典型场景

说清楚适用边界，能省掉很多走弯路的时间。第一种是学习型项目，比如个人做的刷题网页、课程设计里的在线考试模块。这类场景用户量小、对数据实时性要求低，一次性把题库拉下来存本地 JSON 或者 SQLite，之后完全不依赖网络，是最省事的做法，也最能体现接口的价值。

第二种是内容型产品的冷启动，比如一个刚上线的学习类应用，需要先有内容撑住页面。这时候接口的作用是「填充初始数据」，等产品跑起来、有了自己的内容沉淀，再逐步替换成自有题库。这种用法要注意的是可持续性：你不能让产品长期依赖一个不受控的外部数据源，得有替换计划。

第三种是后台管理系统的辅助功能，比如给教研人员提供一个「搜题」工具，输入关键词查相关题目，用来参考出题。这种场景调用频率低、人工触发,对接口压力的影响可以忽略，是使用起来最没有心理负担的方式。

反过来，有两种情况我建议不要接：一是商业化程度高、用户量大、对稳定性有硬要求的产品，这类产品必须自建数据；二是需要按用户实时生成个性化题目的场景，因为这类需求要求你对题库有完全的查询和组合能力，外部接口给不了。判断标准其实很简单——问自己一句：如果这个接口下个月关停，我的产品还能不能跑？答案是否的话，就要重新考虑架构了。

2. 接口设计拆解：从 URL 到返回字段的取舍

2.1 资源划分与路由设计背后的逻辑

一个题库接口的路由怎么设计，直接反映了作者对业务的理解深度。做得粗糙的，通常是/getQuestion?id=123这种一把梭的风格，所有功能塞进一个入口，靠参数区分。做得讲究一点的，会按资源划分，比如「题目」「章节」「试卷」「知识点」各占一个路径段。后者的好处是语义清晰、便于做缓存策略、也方便后续扩展。

拿 ZERO 这套接口举例，典型的资源划分大概是这么几类：题目列表按条件查询、单题详情、章节树、以及可能存在的题目搜索。这种划分方式遵循的是 REST 的基本思路——用路径表达「你要什么资源」，用查询参数表达「怎么筛」。理解了这个原则，你看任何接口文档都会快很多。

提示：看到GET /api/v1/questions?chapter=3&type=single&page=1&size=20这样的地址，先拆成三段看。/api/v1是版本和前缀，/questions是资源名，问号后面全是过滤条件。养成这个拆解习惯，接口文档看一眼就能上手。

版本前缀这个细节值得单独说一句。v1这种写法不是摆设，它意味着作者保留了「未来改动时不破坏老调用方」的可能性。如果你在接入时发现对方没有版本前缀，那你就要做好心理准备：任何一次更新都可能让你的代码失效。这种情况下，我通常会在自己的适配层里把接口地址做成配置项，而不是硬编码在业务代码里，改起来只需要改配置。

还有一个小细节能看出接口质量：分页参数用 offset 还是 cursor。用page和size的，数据量大了之后性能会下降，并且翻页时如果有新数据插入会出现重复或遗漏；用cursor或者since_id的，稳定性好很多，适合做增量同步。如果你要做全量题库同步，优先看看对方有没有提供基于时间戳或自增 ID 的增量接口，没有的话只能自己维护一份已拉取的 ID 集合来做去重。

2.2 题目数据模型的字段约定与坑

题库接口最核心的部分就是单条题目的数据结构。一个设计得好的题目对象，字段应该覆盖这几个维度：唯一标识、题型、题干、选项、答案、解析、归属（章节/知识点）、难度、元信息（来源、更新时间）。缺了哪一块，后面都要自己补。

我列一个我实际用过的结构作为参考，字段命名以对方文档为准，这里重点看结构关系：

这张表里，我认为最容易出事的是answer和type两个字段。答案的形态不统一，是接入题库接口时最常见的 bug 来源。单选题返回字符串"A"，多选题返回数组["A","C"]，你如果统一按数组处理，单选题就会变成["A","C"]这种按字符切分的结果——不要笑，这个错误我见过不止一次，因为字符串在某些语言里是可以被遍历的。

题型枚举也是重灾区。同一个意思，可能是single、Single、1、单选题、radio。接入的第一步，我建议先写一个枚举归一化函数，把对方所有可能的值映射到你自己的类型体系里，映射表外的值统一走「未知题型」分支并记录日志。这样即使对方新增了题型，你的系统也不会崩，只是渲染成降级样式。

2.3 分页、增量同步与数据版本

题库数据有个特点：量大但变化少。一道题录入之后，可能几个月都不会改。这个特点决定了同步策略应该以「拉一次、长期用」为主，而不是每次实时查。所以分页和增量就显得特别重要。

最朴素的全量拉取方式是循环翻页，每次page+1直到返回空列表。实现上要注意两点：一是要有终止条件，不能只靠「返回空」判断，有些接口在越界时会返回全部数据或者报错，最好同时判断「本次返回条数小于 size」；二是要有失败重试，中途某一页失败了，不能整个流程重来，要记录已完成的页码或者已拉取的最后一个 ID，支持断点续传。

import time import requests BASE = "https://example-tiku-api.invalid/api/v1" HEADERS = {"Authorization": "Bearer <YOUR_KEY>"} def fetch_all(page_size=50, max_pages=2000): all_items, page = [], 1 while page <= max_pages: url = f"{BASE}/questions" params = {"page": page, "size": page_size} for attempt in range(3): try: resp = requests.get(url, params=params, headers=HEADERS, timeout=15) resp.raise_for_status() payload = resp.json() break except Exception as exc: print(f"page {page} attempt {attempt} failed: {exc}") time.sleep(1.5 * (attempt + 1)) else: raise RuntimeError(f"page {page} 连续失败，记录断点后退出") items = payload.get("data") or [] if not items: break all_items.extend(items) if len(items) < page_size: break page += 1 time.sleep(0.2) # 主动降速，别把对方打满 return all_items

这段代码里有三个刻意的设计，值得单独解释。主动 sleep 0.2 秒，是因为免费接口没有配额承诺，你打得越凶，对方越可能加限制，得不偿失；重试次数限定三次并且指数退避，避免某次网络抖动就把整个同步流程挂死；失败时抛异常而不是静默返回，因为题库同步最怕的是「拉了一半以为拉完了」，静默失败会导致数据残缺且难以发现。

增量同步的判断依据，通常是updated_at字段。做法是记下本次同步的最大时间戳，下次请求时带上since=那个时间戳，只拉取之后变动的数据。如果对方不支持这个参数，那就只能定期做一次全量对比，用 ID 集合做差集找出新增项。这种方式成本高但可靠，适合数据量不大、变动也不频繁的场景。

另外强烈建议在本地存一份同步水位记录，至少包含：上次同步时间、已拉取总数、最后一条记录 ID、失败页列表。这些信息在排查「为什么题库少了一截」这类问题时，能救命。我一般会把它存在数据库的一张简单表里，一行记录就够，比写日志文件好查得多。

3. 鉴权与限流：密钥不是摆设

3.1 密钥的三种常见形态与安全存放

标题里说「已附带密钥，直接使用」，这句话对新手是很友好的，但也埋着一个隐患：很多人会把密钥直接写死在代码里，然后连代码一起传到公开仓库。这类事情发生频率高得惊人，我自己也在早期项目里干过一次，后果是密钥被人拿去刷，服务方直接把整个 key 停用，项目停摆了两天。

题库接口的鉴权，常见形态有三种。第一种是请求头里放固定密钥，形如Authorization: Bearer xxx或者X-API-Key: xxx，最简单，安全性依赖传输层加密。第二种是URL 参数带 key，形如?key=xxx，这种最不推荐，因为 URL 会被完整记录在服务器日志、浏览器历史、代理日志里，泄露风险高。第三种是密钥加签名，请求时用 key 和 secret 对参数做哈希，服务端校验签名，安全性最好，实现成本也最高。

ZERO 这类公开分享的接口，多半是第一种。拿到密钥之后，正确做法是：本地用一个环境变量或者配置文件存放，代码里只读变量。.env 文件加入 .gitignore，部署时通过平台的环境变量注入。这个习惯看起来微不足道，但它是所有「密钥泄露」事故的第一道防线。

# .env（不要提交到版本库） TIKU_API_BASE=https://example-tiku-api.invalid/api/v1 TIKU_API_KEY=your_key_here

// config.js export const tikuConfig = { baseUrl: process.env.TIKU_API_BASE, apiKey: process.env.TIKU_API_KEY, timeout: 15000, retries: 3, };

注意：如果你的项目是纯前端网页，也就是代码要跑在浏览器里，那么任何密钥都不算秘密——用户打开开发者工具就能看到。这种场景下只有两条路：一是接受密钥公开的事实，服务方大概率会限制来源域名；二是加一层自己的后端做代理，密钥只存在服务端。别幻想「混淆代码」能保护密钥，那只是增加一点点阅读难度而已。

还有一个实务细节：密钥要做轮换预案。假设某天密钥被停用，你的系统怎么恢复？如果密钥是硬编码在十几个文件里，那就要改十几个地方。所以从第一天起，就把「获取密钥」这个动作收敛到一个函数里，所有请求都从那里取，将来换 key 只需要改一处。

3.2 令牌桶限流与配额参数怎么算

即使对方没有明确限流，自己也应该做客户端限流。原因很实在：一是保护对方，二是保护自己不被封，三是让自己的请求节奏可控、便于排查问题。最常用的模型是令牌桶：桶有固定容量，令牌按固定速率补充，请求消耗令牌，桶空了就等待。它的好处是允许一定程度的突发（桶里攒着的令牌可以一次性用掉），同时长期速率被控制在设定值。

参数怎么定？我一般按「目标 QPS」和「可接受突发量」两个维度来算。举个例子，如果我计划每秒最多发 5 个请求，同时允许最多 10 个请求的瞬时突发，那么桶容量设为 10，补充速率为每秒 5 个令牌。计算公式很简单：补充速率 = 目标平均 QPS，桶容量 = 目标 QPS × 可容忍的突发秒数。突发秒数设成 2 秒左右比较合理，太大了会在瞬间打出大量请求。

如果你用 Nginx 做反向代理，可以在那一层直接限流，省得在业务代码里写：

# 按 IP 限流：每秒 10 个请求，突发 20 limit_req_zone $binary_remote_addr zone=tiku_api:10m rate=10r/s; server { location /api/v1/ { limit_req zone=tiku_api burst=20 nodelay; limit_req_status 429; proxy_pass https://upstream-tiku.example; } }

burst=20 nodelay的意思是允许 20 个请求的突发排队，并且不额外延迟处理。这个配置在个人项目里够用了。如果是多实例部署，客户端令牌桶应该用 Redis 做共享，否则每个实例各自限流，总量会翻倍。

另外提醒一点：限流的维度要想清楚。按 IP 限流在云函数、容器环境下常常失效，因为出口 IP 可能是共享的；按密钥限流更准确，但需要业务侧配合。我自己的项目里通常是「应用层按业务功能限流 + 网关层按 IP 兜底」双保险。

3.3 错误码体系与重试策略的取舍

接口报错不可怕，可怕的是报错了你不知道该不该重试。所以接入任何接口，第一步都应该是把错误码整理成一张表，标注清楚「可重试」「不可重试」「需要人工介入」三类。

常见的分类逻辑是这样的：4xx 系列基本不要重试，因为参数错了、密钥错了、权限不够，重试一百次结果都一样，只会浪费资源；429 要特殊处理，它表示被限流了，需要退避后重试，退避时间通常参考响应头里的Retry-After；5xx 可以重试，但要用指数退避，并且限制次数；网络超时也要重试，但要区分「请求没发出去」和「请求发出去了但没收到响应」，后者重试可能造成重复写入，对只读接口无所谓，对写接口就要加幂等键。

RETRYABLE_STATUS = {429, 500, 502, 503, 504} def request_with_backoff(session, method, url, **kwargs): for attempt in range(4): try: resp = session.request(method, url, timeout=kwargs.pop("timeout", 15), **kwargs) if resp.status_code in RETRYABLE_STATUS: wait = float(resp.headers.get("Retry-After", 2 ** attempt)) time.sleep(min(wait, 30)) continue resp.raise_for_status() return resp.json() except requests.Timeout: time.sleep(min(2 ** attempt, 30)) except requests.RequestException as exc: if attempt == 3: raise time.sleep(min(2 ** attempt, 30)) raise RuntimeError("重试耗尽")

这段代码的关键在于min(wait, 30)这个上限。指数退避如果不设上限，第 6 次重试就要等 64 秒，用户那边早就超时了。设个 30 秒封顶，配合总超时控制，是比较稳妥的工程实践。还有个小技巧：把重试次数和最终失败都记进监控指标，如果某个接口的重试率突然上升，往往说明对方出问题了，这时候主动降级比死扛更明智。

4. 动手跑通：从调用到自建的完整流程

4.1 拿到密钥后的第一次调用

先别急着写业务代码，用最原始的方式确认「接口是活的、密钥是有效的、返回结构和我预期一致」。最省事的工具就是 curl，一条命令搞定。

curl -s -H "Authorization: Bearer $TIKU_API_KEY" \ "https://example-tiku-api.invalid/api/v1/questions?page=1&size=5" \ | python -m json.tool | head -n 60

这条命令做了三件事：发请求、用python -m json.tool格式化输出、只看前 60 行。为什么要格式化？因为压缩成一行的 JSON 人眼根本没法看。为什么只看前 60 行？因为题库返回体往往很长，全打出来会把终端刷爆。

第一次调用要重点确认四件事：HTTP 状态码是不是 200、返回体顶层是不是有data之类的包裹字段、分页信息在哪个字段、单条题目的字段名和文档是否一致。这四点确认完，你对这个接口的认知就建立起来了。

如果用 Python，等价写法是这样的：

import os, requests resp = requests.get( f"{os.environ['TIKU_API_BASE']}/questions", params={"page": 1, "size": 5}, headers={"Authorization": f"Bearer {os.environ['TIKU_API_KEY']}"}, timeout=15, ) print(resp.status_code) print(resp.text[:800])

打印resp.text[:800]而不是直接resp.json()，是为了在返回体不是 JSON 的时候（比如网关返回了一段 HTML 错误页）也能看到内容，而不是抛一个让人摸不着头脑的解析异常。这个习惯帮我定位过好几次「接口地址写错跳到登录页」的问题。

4.2 客户端接入封装：一个可复用的请求层

业务代码里到处写requests.get是大忌。正确的做法是封一层薄薄的客户端，把 baseURL、鉴权头、超时、重试、日志、字段适配全部收进去。这样业务侧只关心「我要什么题」，不关心「怎么发请求」。

class TikuClient { constructor({ baseUrl, apiKey, timeout = 15000 }) { this.baseUrl = baseUrl.replace(/\/$/, ""); this.apiKey = apiKey; this.timeout = timeout; } async request(path, params = {}) { const url = new URL(this.baseUrl + path); Object.entries(params).forEach(([k, v]) => { if (v !== undefined && v !== null) url.searchParams.set(k, v); }); const controller = new AbortController(); const timer = setTimeout(() => controller.abort(), this.timeout); try { const resp = await fetch(url, { headers: { Authorization: `Bearer ${this.apiKey}` }, signal: controller.signal, }); if (!resp.ok) { throw new Error(`TikuAPI ${resp.status} ${await resp.text()}`); } return await resp.json(); } finally { clearTimeout(timer); } } async listQuestions({ page = 1, size = 50, chapterId, type } = {}) { const raw = await this.request("/questions", { page, size, chapter_id: chapterId, type, }); return (raw.data || []).map(normalizeQuestion); } } function normalizeQuestion(q) { const typeMap = { single: "single", Single: "single", radio: "single", "单选题": "single", multiple: "multiple", checkbox: "multiple", "多选题": "multiple", judge: "judge", "判断题": "judge", }; const answer = q.answer == null ? [] : Array.isArray(q.answer) ? q.answer : [String(q.answer)]; return { id: String(q.id), type: typeMap[q.type] || "unknown", stem: String(q.stem || "").trim(), options: Array.isArray(q.options) ? q.options : [], answer, analysis: q.analysis || "", chapterId: q.chapter?.id ?? null, difficulty: Number(q.difficulty) || 0, updatedAt: q.updated_at || null, }; }

这个封装里，真正有价值的不是请求部分，而是normalizeQuestion。它把外部数据的三种不确定性挡在了业务层之外：题型枚举的多样性、答案形态的不统一、可能为 null 的字段。经过这一层，业务代码拿到的永远是稳定结构，将来接口改字段，只需要改这一个函数。

我还建议在request里加一个请求 ID 和耗时日志。生产环境排查问题时，你最想知道的是「这次报错对应哪次请求、花了多久、参数是什么」。日志里带上这些，比事后凭感觉猜要高效得多。

4.3 自建题库服务的落地步骤

如果你打算长期用题库，或者担心外部接口的稳定性，那就要走自建这条路。别被「自建」两个字吓到，最小可用版本其实不复杂：一张表、一个导入脚本、一个查询接口，一天就能搭起来。

第一步，建表。字段设计直接参照你适配层里的结构，注意给可能被查询的字段加索引。

CREATE TABLE questions ( id BIGINT PRIMARY KEY AUTO_INCREMENT, ext_id VARCHAR(64) NOT NULL, -- 外部接口的原始 ID fingerprint CHAR(32) NOT NULL, -- 题干哈希，用于去重 type VARCHAR(16) NOT NULL DEFAULT 'unknown', stem TEXT NOT NULL, options JSON NULL, answer JSON NOT NULL, analysis MEDIUMTEXT NULL, chapter_id BIGINT NULL, difficulty TINYINT NOT NULL DEFAULT 0, source VARCHAR(32) NOT NULL DEFAULT 'zero', updated_at DATETIME NULL, created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP, UNIQUE KEY uk_ext (source, ext_id), UNIQUE KEY uk_fp (fingerprint), KEY idx_chapter (chapter_id), KEY idx_type (type) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

两个唯一索引是关键。uk_ext保证同一条外部数据不会重复插入，用INSERT ... ON DUPLICATE KEY UPDATE就能实现增量更新；uk_fp用题干指纹做二次去重，因为不同来源的同一道题，ID 肯定不一样，但题干往往一字不差。

第二步，算指纹。直接用题干原文做 MD5 会被空格和标点坑，比如「下列哪个选项是正确的？」和「下列哪个选项是正确的?」，只差一个全角半角，MD5 完全不同。所以要先做归一化：去掉所有空白字符、统一全角半角、去掉标点。更讲究一点可以用 SimHash 做近似去重，能识别「换了几个字的同一道题」，但实现成本高不少，初期用 MD5 加归一化就够了。

import hashlib, re, unicodedata def normalize_text(text: str) -> str: text = unicodedata.normalize("NFKC", text or "") text = re.sub(r"\s+", "", text) text = re.sub(r"[，。！？；：、（）【】《》“”‘’.,!?;:()\[\]<>\"']", "", text) return text.lower() def fingerprint(stem: str) -> str: return hashlib.md5(normalize_text(stem).encode("utf-8")).hexdigest()

第三步，导入并处理冲突。导入时我一般会先写进一张临时表，跑一遍去重和字段校验，确认没问题再合并进主表。这样做的原因是：直接往主表灌数据，一旦发现批量导入有格式问题，回滚很麻烦。临时表相当于一个缓冲区，出问题直接清零重来。

第四步，加查询接口。用 SQLite 或者 MySQL 都行，包一个简单的查询服务出来，返回结构和外部接口保持一致。这样将来在「调外部」和「查本地」之间切换，业务代码完全不用改，只改配置里的 baseURL 就行。这个设计我觉得挺值，它把「数据来源」变成了一个可以替换的组件。

4.4 缓存设计：把重复查询的成本压到接近零

题库查询有个天然优势：读多写少、结果稳定。同一个章节的题目，一小时内可能被查几百次，但内容完全一样。这种场景下，缓存的收益极高。

缓存分三层来做比较合理。第一层是浏览器/客户端缓存，给接口响应加Cache-Control头，让客户端自己扛一部分；第二层是服务端内存缓存，用进程内的 LRU 缓存存热点章节，命中率通常能到八成以上；第三层是持久化存储，也就是自建库，作为最终的兜底数据源。

// 极简 LRU：够用就好，别上重型依赖 class SimpleLRU { constructor(limit = 200) { this.limit = limit; this.map = new Map(); } get(key) { if (!this.map.has(key)) return undefined; const val = this.map.get(key); this.map.delete(key); this.map.set(key, val); return val; } set(key, val) { if (this.map.has(key)) this.map.delete(key); this.map.set(key, val); if (this.map.size > this.limit) { this.map.delete(this.map.keys().next().value); } } }

Map在 JavaScript 里是有序的，利用「删除再插入会移到末尾」这个特性，可以很轻松实现 LRU。这个实现只有二十来行，但在我好几个项目里都够用，没必要为了缓存专门引一个库。

缓存的失效策略也要想清楚。题库数据变动不频繁，用基于时间的过期就足够了，比如设 10 分钟。但我建议在缓存 key 里带上数据的更新时间或者版本号，这样一旦检测到接口有更新，可以直接让整批缓存失效，而不是干等过期。这个细节在数据修正场景下很有用——比如某道题答案错了被更正，你总不能让用户十分钟后才看到对的答案。

5. 常见问题与排查实录

5.1 高频报错速查表

接口用得多了，会发现报错其实就那几种，整理成表能省下大量翻文档的时间。

这张表里，我踩得最惨的是「返回体是 HTML」这一条。当时接口地址少写了一个s，请求打到了另一个域名，对方返回了一个 200 状态的错误页，我的代码因为只判断状态码，直接把 HTML 当 JSON 解析，报了一个完全无关的语法错误，定位花了半个小时。从那之后，我的请求封装里都会先判断Content-Type，不是application/json就直接报错并打印原文。

5.2 数据质量问题的排查顺序

接口能通不代表数据能用。题库数据常见的问题有：题干里混着 HTML 标签、选项数量和答案不匹配、解析里带着广告或者无关内容、同一道题以不同 ID 出现多次。这些问题不会报错，但会直接影响用户体验。

排查要讲顺序，我的习惯是先看样本，再看分布，最后做规则。先随机抽 200 条数据人工看一遍，心里有个数；然后跑统计脚本，看题型分布、选项数量分布、答案字段的空值率、题干长度分布，异常值往往一眼就能看出来；最后针对发现的模式写清洗规则。

from collections import Counter def audit(items): stats = { "total": len(items), "by_type": Counter(q.get("type") for q in items), "no_answer": sum(1 for q in items if not q.get("answer")), "no_analysis": sum(1 for q in items if not q.get("analysis")), "weird_stem": sum(1 for q in items if "<" in (q.get("stem") or "")), "option_count": Counter(len(q.get("options") or []) for q in items), } return stats

这几个指标里，weird_stem和option_count最有诊断价值。题干里出现<说明混了 HTML，需要做标签剥离；选项数量如果是 0 或者 1 占比很高，说明接口对判断题的处理不一致，你要单独适配。不夸张地说，一份统计报告能顶半天的人工翻查。

提示：清洗规则一定要可回滚。把清洗后的数据写进新表，保留原表，别原地修改。等你发现某条清洗规则误伤了正常数据，还能拿原始数据重新跑一遍。

5.3 稳定性观察与降级方案

长期使用外部接口，必须建立一套「观察 + 降级」的机制。观察的部分，至少记录三个指标：请求成功率、平均响应时间、重试率。这三个指标不需要上专业监控系统，写进一张表或者打印到日志里，每天扫一眼就够了。成功率跌破 95%、响应时间明显变长、重试率上升，这些都是对方出问题的先兆。

降级的思路很朴素：接口不可用的时候，用本地数据顶上。如果你已经做了第 4 章的自建库，这个降级几乎是免费的——请求外部失败就查本地，查不到就返回空列表，前端展示「暂无题目」而不是一直转圈。如果没有自建库，至少也要把已经拉取过的数据缓存下来，不要在接口挂了的时候整个产品变白屏。

我还会给接口配一个熔断开关。当连续失败次数超过阈值（比如 10 次），直接把外部调用关掉，走本地数据，同时后台定时探测恢复情况。这个机制最重要的作用不是技术上的，而是心理上的——你不用半夜爬起来盯着接口，系统自己会处理。

6. 合规与长期可用性：别把项目建在别人的接口上

6.1 数据来源与使用的现实边界

这一点我想说得直白一些，因为它关系到项目能不能长期活下去。题库内容本身是有版权属性的。题目是有人编写的，解析是有人撰写的，整理归类也投入了劳动。公开分享的接口，你用来做个人学习、跑个 Demo、验证一个想法，一般没什么问题；但如果你把它当成商业产品的数据底座，把别人的内容直接当成自己的内容对外提供，这里面的风险是实打实的。

我的做法是三条线。第一条，个人项目和个人学习用途优先，这是最没有争议的场景。第二条，公开可见的产品里，题库数据要么来自自己录入、要么来自明确授权、要么来自可商用的公开资源，外部接口的数据只作为开发阶段的占位内容，上线前替换掉。第三条，保留数据来源标记，我给每张表都留了source字段，不只是为了去重，也是为了将来如果需要对某批数据做清理，能一次性筛出来。

另外还有一层考虑：用户数据的隔离。题库是公共的，但用户的答题记录、错题本、收藏是私有的。这两类数据千万不要混在一张表里，也不要把用户数据回传给外部接口。这一点在架构设计阶段就要定好边界。

6.2 从「调用」到「自持」的迁移路径

如果你的项目确实需要长期用题库数据，我建议按这个路径演进，而不是一步到位推倒重来。

阶段一，纯调用。快速验证产品想法，接口直接调，本地做一层缓存。这个阶段的目标是「最快跑通」，不要过度设计。

阶段二，双层数据源。加上自建库，外部接口作为补充数据源，本地库作为主数据源。查询时先查本地，本地没有再去外部拉，拉到后落库。这个阶段的好处是，数据会随着使用自然沉淀，你用得越多，本地库越完整，对外部的依赖越少。

阶段三，本地为主。当本地库覆盖了主要章节，就可以把外部调用降级为「离线同步任务」，每天跑一次增量，线上查询全部走本地。这个阶段你的产品已经不再受外部接口可用性的影响，响应速度也会大幅提升——本地查询通常是毫秒级，外部接口是百毫秒级。

阶段四，完全自持。逐步用自己的内容替换外部数据，形成真正属于自己的题库。到这一步，接口就变成了一个历史数据来源，随时可以下线。

这条路径的核心思想是：外部接口是加速器，不是地基。用它来省时间，但别让它成为系统里唯一的支柱。我在实际项目里走过这条路径，从第一阶段到第三阶段大概用了几周，主要时间花在数据清洗和去重上，而不是写代码。技术难度不高，难的是想清楚每一步的目标和退出条件。

最后分享一个我个人的习惯：接入任何外部接口，我都会在项目文档里写一行「依赖清单」，记录这个接口的用途、数据量级、如果它挂了会有什么影响、替代方案是什么。这行字在项目顺利的时候看起来多余，但在某天接口突然不可用时，它能让你在五分钟内做出决策，而不是慌乱地到处翻代码找哪里在用这个接口。