通用可配置爬虫框架

你好，欢迎了解这个项目！我创建这个框架的初衷，是为了解决在进行数据分析时需要为每个网站或API单独编写爬虫脚本的繁琐问题。我希望构建一个足够通用、配置与代码完全分离的工具，让我们在面对新的数据源时，能够专注于解析数据本身，而不是重复编写网络请求、数据存储和任务调度的逻辑。

这个框架的核心设计理念是**“配置驱动”**。所有的抓取任务，无论是目标网址、请求参数，还是执行计划，都定义在外部的配置文件中。这意味着，当我们需要添加一个新任务时，绝大多数情况下我们都无需改动框架的核心代码，只需修改或添加配置文件，并编写一个独立的解析器即可。这使得整个项目变得非常易于维护和扩展。

功能与设计

框架内置了一个定时调度器，通过 run_scheduler.py 启动后，它会成为一个常驻服务，根据你在 configs/tasks.json 中定义的触发器（triggers）来按周期（例如每天、每小时）自动执行任务。对于那些没有指定触发器的任务，调度器会在启动时立即执行一次。

为了应对不同网站和API返回的千差万别的数据结构，框架采用了动态解析器机制。每个任务在配置中都会指定一个 parser，它对应着 src/crawler_framework/parsers/ 目录下的一个Python文件。当任务执行时，框架会自动加载并调用相应的解析器来处理获取到的原始数据。这种设计保证了每个数据源的处理逻辑都是独立的、互不干扰的。

抓取到的数据可以被灵活地存储。你可以根据任务配置，选择将处理好的数据保存为格式清晰的 JSON 文件，或是存入 SQLite 数据库。存入数据库的方式尤其适合需要进行长期追踪和时序分析的数据。

如何使用

开始使用前，请确保你的环境中已安装 Python 3.10+ 和 Git。首先，将项目克隆到本地，并进入项目目录：

git clone https://github.com/Choimoe/web_crawler_framework.git
cd web_crawler_framework

然后，使用 pip 安装所有必需的依赖库：

pip install -r requirements.txt

项目的配置分为两部分：位于根目录的 config.toml 文件负责定义框架的全局设置（如调度器轮询间隔），而 configs/tasks.json 文件则专门用于定义所有的具体抓取任务和触发器。

要启动框架并让它进入自动调度模式，只需运行 run_scheduler.py。程序会加载所有任务，并根据计划持续在后台运行，你可以随时通过 Ctrl+C 来停止它。

在开发新任务或调试现有任务时，你无需等待调度器触发。我们提供了一个非常方便的手动测试工具 run_task_tester.py。通过它，你可以立即执行任何一个在配置文件中定义的任务，从而快速验证你的解析器或请求参数是否正确。例如，要测试炉石传说的数据抓取任务，可以运行：

python run_task_tester.py "炉石传说酒馆战棋多分段饰品数据"

如果你不确定任务的全名，直接运行 python run_task_tester.py 会列出所有可用的任务。

当数据被存入数据库后，你可以使用 db_inspector.py 工具来快速检查结果。它会清晰地列出数据库中所有表的结构（列名）和前几行数据样本，让你对抓取成果一目了然。

python src/crawler_framework/utils/db_inspector.py hearthstone_stats.db

扩展新任务

为框架添加一个全新的抓取任务是一个非常流程化的过程。首先，你需要打开 configs/tasks.json 文件，在 tasks 列表中添加一个新的JSON对象来完整地描述你的任务，包括目标URL、请求方法、输出方式，并为它指定一个独一无二的 parser 名称。如果需要定时执行，你还可以在 triggers 列表中定义一个触发器，并把它的名字链接到你的任务上。

接下来，根据你指定的 parser 名称，在 src/crawler_framework/parsers/ 目录下创建一个对应的 .py 文件。这个文件是实现数据解析的核心，你需要在其中定义一个 parse 函数。这个函数会接收到原始的网络响应内容和完整的任务配置信息，你的目标就是在这里将原始数据清洗、转换成一个由字典组成的列表（[{}, {}, ...] ），然后返回它。

最后，别忘了使用 run_task_tester.py 来立即运行你的新任务，确保一切工作正常。

当前已实现任务与文档

为了更好地展示框架的能力，目前项目内已配置了两个真实的数据抓取任务。关于这些任务所依赖的API的详细信息（如端点、参数等），都已整理成文档存放在项目的 docs/ 目录下。

任务名称	数据源	核心目标	实现方式	文档
MaimaiDX 谱面数据统计	diving-fish.com	定期抓取所有乐曲谱面的拟合难度、平均达成率等核心数据，并存入数据库以进行长期的时序分析。	使用一个简单的解析器处理API返回的JSON数据。	maimai_api.md
炉石传说酒馆战棋多分段饰品数据	HSReplay.net HearthstoneJSON.com	聚合两个API的数据，获取在高分段玩家中各个饰品的表现，并关联其中文名称和描述。	使用一个复杂的“编排型”解析器，在一次执行中多次请求API，并在内存中合并数据。	hearthstone_apis.md

贡献

欢迎对本项目进行贡献！你可以通过提交 Bug 报告、功能建议，或是通过 Pull Request 来改进代码和完善文档。