维基百科中文版API踩坑：手写实现稳定抓取方案

最近升级了内部数据同步服务，刚跑完测试，生产环境直接报了一堆 404 和字段缺失。检查日志发现，维基百科中文版的 MediaWiki API 在 1.40 版本后对部分批量查询接口做了不兼容变更，导致原有代码全崩。

这种“版本升级后 API 全变了”的情况，在对接开放数据源时太常见了。官方文档更新滞后，社区反馈又碎片化，这时候死磕官方 SDK 或第三方库往往解决不了根本问题。我的经验是：抛弃黑盒，手写实现核心请求逻辑。

今天这篇教程，不聊虚的。我们直接面对市政公用工程中常见的“跨部门数据共享”痛点，结合运维开发视角，手把手带你手写实现一个稳定的维基百科中文版数据抓取器。别被“维基百科”这个名字吓到，这其实是一个绝佳的练习对象：它免费、开放、结构复杂，且经常变动，非常适合用来打磨你的 API 交互能力。

概念速懂：为什么选维基百科做练手

很多读者可能会问，写个爬虫有什么难的？为什么非要盯着维基百科中文版？

在实际的市政公用工程信息化项目中，我们经常需要对接政府公示数据、历史档案库或外部知识库。这些系统的特点和维基百科很像：

1. 数据量巨大：单次请求无法获取全量，必须分页。
2. 结构动态：字段名可能随版本迭代调整。
3. 限流严格：IP 被封禁是常态，必须做并发控制。

维基百科中文版（zh.wikipedia.org）基于 MediaWiki 平台，其 API 遵循 RESTful 风格。对于运维开发来说，理解它的底层逻辑，比死记硬背某个 Python 库的函数更有价值。

这里有一个关键概念：Action API vs REST API。

• Action API (/w/api.php)：老接口，功能全，但返回的是 JSON 包裹的复杂结构，解析麻烦。
• REST API (/api/rest_v1/)：新接口，更轻量，但覆盖范围有限。

本文我们主要使用 Action API，因为它的稳定性在长期项目中经过验证，且支持更复杂的过滤参数。这也是为什么很多老牌系统还在用它的根本原因。

环境准备：最小化依赖

为了体现“手写实现”的价值，我们尽量少用现成的高层封装库。你需要准备：

1. Python 3.8+：推荐版本，语法特性支持更好。
2. requests 库：唯一的第三方依赖，用于 HTTP 通信。
   • 安装命令：pip install requests
3. 一个文本编辑器：VS Code 或 PyCharm 均可。

重要提示：在开始写代码前，请务必阅读维基百科的开发者文档（MediaWiki API 官方指南）。特别是关于 User-Agent 的请求头要求。维基百科明确要求用户设置合法的 User-Agent，否则会被 403 拒绝。这是很多新手踩坑的第一道门槛。

核心语法：拆解请求与响应

在动手写完整代码前，我们先拆解一次典型的 API 交互。

假设我们要获取“北京市”这个条目的信息。 URL 构造如下： https://zh.wikipedia.org/w/api.php?action=query&titles=北京市&format=json&prop=extracts

参数解析：

• action=query：指定操作类型为查询。
• titles=北京市：查询的目标页面。
• format=json：强制返回 JSON 格式，方便解析。
• prop=extracts：指定返回页面的纯文本摘要。

关键点：维基百科的响应结构是嵌套的。

{"batchcomplete": "","query": {"normalized": [],"pages": {"12345": {"pageid": 12345,"title": "北京市","extract": "北京市，简称“京”，是中华人民共和国的..."}}}
}

注意 pages 是一个字典，Key 是 pageid，而不是固定的索引。很多开发者在这里犯错，试图用 pages[0] 取值，结果直接 KeyError。

完整代码示例：手写稳定抓取器

下面这段代码是我在实际项目中使用的简化版模板。它包含了重试机制、User-Agent 设置和基础的错误处理。

import requests
import time
import logging# 配置日志，方便运维排查
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)class WikipediaClient:def __init__(self):# 必须设置 User-Agent，否则会被维基百科屏蔽# 格式参考：https://meta.wikimedia.org/wiki/User-Agent_policyself.base_url = "https://zh.wikipedia.org/w/api.php"self.headers = {"User-Agent": "MyEngineeringBot/1.0 (contact@example.com) Python-requests"}self.session = requests.Session()self.session.headers.update(self.headers)def fetch_page_extract(self, title, retries=3):"""获取指定页面的纯文本摘要"""params = {"action": "query","titles": title,"format": "json","prop": "extracts","exintro": 1,  # 只取首段，减少数据量"redirects": 1 # 自动重定向}for attempt in range(retries):try:response = self.session.get(self.base_url, params=params, timeout=10)response.raise_for_status()  # 非200状态码抛异常data = response.json()# 检查是否成功if "error" in data:logger.error(f"API Error: {data['error']}")return None# 遍历 pages 字典，因为 Key 是动态的pages = data.get("query", {}).get("pages", {})for page_id, page_data in pages.items():# 检查是否是被重定向的页面if page_data.get("missing") == "":logger.warning(f"Page {title} not found.")return Nonereturn page_data.get("extract")return Noneexcept requests.exceptions.RequestException as e:logger.warning(f"Request failed (Attempt {attempt + 1}): {e}")if attempt < retries - 1:time.sleep(2 ** attempt)  # 指数退避策略continuereturn None# 测试运行
if __name__ == "__main__":client = WikipediaClient()result = client.fetch_page_extract("北京市")if result:print(result[:200])  # 打印前200个字符预览else:print("获取失败")

代码逐行解读：

1. requests.Session()：复用到维基百科的连接，比每次新建 requests.get 性能高，且能自动保持 Cookie（虽然维基百科大多无状态，但这是好习惯）。
2. raise_for_status()：很多教程忽略这一步。如果服务器返回 500，response.json() 会解析失败或返回错误结构。显式抛出异常能让我们更早发现问题。
3. 指数退避（Exponential Backoff）：time.sleep(2 ** attempt)。如果第一次失败，等1秒；第二次失败，等2秒；第三次失败，等4秒。这能有效避免在服务器压力大时持续轰炸，也是遵守网络礼仪的表现。
4. 遍历 pages 字典：再次强调，不要假设 pages 的长度或 Key。这是处理 MediaWiki API 的核心技巧。

常见报错与避坑指南

在实际生产环境中，你大概率会遇到以下三类问题：

1. HTTP 403 Forbidden

现象：所有请求都被拒绝。 原因：User-Agent 缺失或格式不规范。 解决：严格按照维基百科的 User-Agent 策略修改。必须包含联系方式和软件名称。不要使用默认的 python-requests/x.x.x。

2. KeyError: 'pages' 或 'query'

现象：代码运行到解析 JSON 时报错。 原因：

• 网络抖动导致返回了 HTML 错误页面。
• 请求参数错误，API 返回了 Error 对象而非 Query 对象。 解决：在访问 data['query'] 之前，务必先检查 data 中是否存在 error 字段。使用 .get() 方法代替 [] 取值更安全。

3. 频率限制（429 Too Many Requests）

现象：批量抓取时突然中断。 原因：并发过高或短时间内请求过多。 解决：

• 控制并发数：建议使用 concurrent.futures.ThreadPoolExecutor，将并发线程控制在 5-10 以内。
• 增加间隔：在循环中加入 time.sleep(0.5)。
• 注意：维基百科对 IP 的限流非常严格，尤其是数据中心 IP。如果是生产环境，建议轮换 IP 或申请正式的 Bot 权限。

小结与互动

通过上述步骤，我们手写实现了一个基于维基百科中文版 API 的数据抓取器。这个过程不仅解决了“版本升级后 API 全变了”带来的脆弱性，更重要的是，让你彻底理解了 HTTP 交互、JSON 解析和错误处理的底层逻辑。

对于市政公用工程从业者而言，这种能力可以迁移到对接住建局数据接口、环保监测数据平台等场景。核心思想不变：理解协议，掌控请求，妥善处理异常。

你公司项目里是怎么处理的？欢迎评论。

比如，你们在对接外部数据源时，是倾向于封装统一的 SDK，还是像这样每次手写？或者有没有遇到过更奇葩的 API 变更？在评论区聊聊，咱们一起避坑。