LifeLens

旅游数据爬取与分析系统 —— 从携程、去哪儿等平台采集景点信息、详情与用户评论，为旅行决策提供数据支撑。

免责声明

请以学习与研究为目的使用本项目。禁止将本项目用于商业用途、大规模或高频采集、绕过平台访问控制，以及任何违反法律法规或平台规则的行为。使用者应自行确认采集行为的合规性，并承担因使用本项目产生的一切责任。项目作者不对任何直接或间接损失、数据使用后果或法律纠纷负责。

详细条款见使用须知与 License。

功能概览

已实现

全链路采集：携程与去哪儿景点列表、详情、评论一站式爬取
ID 自动解析：根据景点名或城市名自动定位 poi_id / district_id，无需手动查询
流水线编排：list → detail → comments 一键串联，单个入口支持 sight / city / poi_id / district_id 四种目标
断点续跑：中断后重新执行自动跳过已完成景点；评论按页 checkpoint，失败页面单独记录
请求防护：随机延迟（默认 1-3 秒）、HTTP 非 200 状态码线性退避重试 3 次
集中配置：API 端点、请求头、超时、分页参数统一管理于 config.py
离线测试：核心单测 mock 网络请求，不依赖真实 API 可用性
统一基础设施：BaseSpider 重试、SpiderLogger 分级日志、storage_layout 统一目录布局与 StorageBackend JSON/CSV 存储

待实现

分析层：情感分析、词云、地理热图（占位模块与依赖已就位）
数据模型接入：Sight / Comment 数据模型替换裸 dict（模型已定义，尚未替换各模块返回值）
代理轮换：RequestOptimizer.get_random_proxy() 已实现，但尚未接入各爬虫的实际请求调用
美团平台：平台目录已预留，尚未接入

环境要求

Python >= 3.9
核心依赖仅 requests 与 beautifulsoup4；测试依赖 pytest，分析层依赖见下方 extras

快速开始

安装

git clone https://github.com/Hsuant/LifeLens.git
cd LifeLens
pip install -e ".[dev]"           # 基础功能 + 测试依赖

可选 extras：

extra	用途
`analysis`	pandas / numpy / scikit-learn / matplotlib / seaborn / jieba
`geo`	geopandas（地理热图）
`deep`	torch / transformers（深度模型）

命令行用法

两个平台使用统一的参数名：名称参数为 --sight、--city，ID 参数为 --poi-id、--district-id。

# 按景点名称
python -m lifelens.platforms.ctrip.pipeline --sight "黄鹤楼"

# 按城市名称
python -m lifelens.platforms.ctrip.pipeline --city "杭州" --list-pages 3

# 按景点 POI ID
python -m lifelens.platforms.ctrip.pipeline --poi-id 10568753

# 按地区 ID
python -m lifelens.platforms.ctrip.pipeline --district-id 9 --list-pages 3

# 去哪儿同样使用 --sight、--city、--poi-id
python -m lifelens.platforms.qunar.pipeline --city "北京" --max-sights 10

参数说明（--sight / --city / --poi-id / --district-id 四选一）：

参数	说明	默认值
`--sight`	景点名称，自动解析 POI ID	`""`
`--city`	城市名称，自动解析地区 ID	`""`
`--poi-id`	景点 POI ID	`None`
`--district-id`	携程地区 ID	—
`--list-pages`	景点列表爬取页数	`None`（不限制，自动爬取所有页）
`--max-comment-pages`	每个景点评论最大爬取页数	`None`（不限制，爬取所有页）
`--output-dir`	输出根目录	`data`

注：Qunar 评论接口暂不支持地区 ID 查询，因此 --district-id 仅适用于 Ctrip；Qunar 请使用 --city。

编程式用法

from lifelens.platforms.ctrip.pipeline import CtripPipeline

pipeline = CtripPipeline(output_dir="data")

# 统一主入口：名称用 sight / city，ID 用 poi_id / district_id
result = pipeline.run(poi_id="10568753")
result = pipeline.run(district_id=9, list_pages=5, max_comment_pages=50)
result = pipeline.run(city="杭州", list_pages=5, max_comment_pages=50)
result = pipeline.run(sight="黄鹤楼", max_comment_pages=50)
print(result)

返回值结构：

// 地区模式
{"total": 20, "completed": 18, "failed": 2, "skipped": 0, "elapsed_seconds": 152.3}

// 名称解析模式：在上述字段外额外附带
{"city": "杭州", "resolved_type": "district", "resolved_info": {...}}

// 景点模式
{"total": 1, "completed": 1, "failed": 0, "skipped": 0,
 "poi_id": "10568753", "poi_name": "千岛湖",
 "details_success": true, "comments_success": true, "elapsed_seconds": 8.4}

// 失败
{"success": false, "error": "未获取到景点列表"}

入口方法对比：

方法	适用场景	关键参数
`run()`	统一入口，按景点、城市或 ID 选择任务	`sight` / `city` / `poi_id` / `district_id` 四选一
`_run_district()`	内部地区流水线	`district_id`, `city`, `list_pages`, `max_comment_pages`
`_run_sight()`	内部单景点流水线	`poi_id`, `sight`, `max_comment_pages`

单模块使用

from lifelens.platforms.ctrip.sight_list import CtripAttractionScraper
from lifelens.platforms.ctrip.sight_detail import AttractionDetailFetcher
from lifelens.platforms.ctrip.sight_comments import CtripCommentSpider
from lifelens.platforms.ctrip.sight_locator import SightLocator
from lifelens.core.storage import json_storage

# 自动解析 ID（无需手动查询）
locator = SightLocator()

# 按景点名获取 POI ID 及所属地区
info = locator.locate_sight("黄鹤楼")
# {"type": "sight", "poi_id": "77593", "sight_name": "黄鹤楼",
#  "district_id": 145, "district_name": "武汉", "city_id": ..., "city_name": "..."}

# 按地区名获取地区 ID
info = locator.locate_district("杭州")
# {"type": "district", "district_id": 14, "district_name": "杭州", ...}

# 自动判断关键词类型（流水线内部使用的入口）
info = locator.locate("西湖")

# 获取景点列表
scraper = CtripAttractionScraper()
sights = scraper.get_attractions_with_pagination(district_id=9, pages=2)
json_storage.save(sights, "data/sights.json")

# 获取景点详情（get_detail 返回原始解析结果，get_formatted_detail 返回精简视图）
fetcher = AttractionDetailFetcher()
detail = fetcher.get_detail("10568753")
print(detail["poi_name"], detail["ticket_price"], detail["description"])

# 爬取评论（单景点 / 多景点）
spider = CtripCommentSpider(output_dir="data/comments")
spider.crawl_comments("10568753", "千岛湖", max_pages=10)
spider.crawl_multiple_pois([("10568753", "千岛湖"), ("77593", "黄鹤楼")], max_pages=10)

配置

所有携程 API 参数集中定义在 src/lifelens/config.py 的 CtripConfig dataclass 中，全局目录参数见 GlobalConfig：

配置项	说明	默认值
`sight_search_url`	关键词搜索 API	`.../soa2/26872/search`
`sight_list_url`	景点列表 API	`.../soa2/13342/json/getSightRecreationList`
`sight_detail_url`	景点详情 API	`.../soa2/18254/json/getPoiMoreDetail`
`comment_url`	评论 API	`.../soa2/13444/json/getCommentCollapseList`
`headers`	请求头（UA / Content-Type / Referer 等）	见 config.py
`head`	搜索 / 列表 / 详情 / 评论共用 head 结构	`cid=09031065211914680477`
`comment_cid`	评论 API 专用 cid	`09031069112760102754`
`timeout`	请求超时（秒）	`10`
`delay_range`	随机延迟范围（秒）	`(1, 3)`
`list_page_size`	景点列表每页条数	`20`
`comment_page_size`	评论每页条数	`10`

全局配置	说明	默认值
`GlobalConfig.log_dir`	日志目录	`logs`
`GlobalConfig.data_dir`	数据目录	`data`
`GlobalConfig.default_timeout`	默认超时	`10`
`GlobalConfig.default_delay_range`	默认延迟范围	`(1, 3)`

注意：.env.example 目前是配置模板，代码尚未读取环境变量（未接入 python-dotenv）。需要调整 cid、超时、延迟范围时，请直接编辑 config.py。

数据输出

统一目录结构为：

data/<platform>/<province>/<city>/<sight>_<poi-id>/

省、市优先取平台字段；缺失时从详情地址解析。无法确定的行政区使用 Unknown，不会猜测。

地区任务（_run_district()）：

data/
└── ctrip/
    └── 浙江省/
        └── 杭州市/
            ├── sights.json
            ├── summary.json
            ├── pipeline_progress.json
            └── 千岛湖_10568753/
                ├── detail.json
                ├── comments.csv
                ├── comments_progress.json
                ├── failed_pages.json
                └── summary.json

景点任务（_run_sight()）：

data/
└── qunar/
    └── 北京市/
        └── 北京市/
            └── 故宫博物院_989946426/
                ├── detail.json
                ├── comments.csv
                ├── comments_progress.json
                ├── failed_pages.json
                └── summary.json

评论 CSV 采用 utf-8-sig 编码（Excel 可直接打开），字段依次为：

序号、景区ID、景区名称、评论ID、用户昵称、总体评分、评论内容、发布时间、有用数、回复数、出行类型、用户所在地、游玩时长、图片数量、图片链接列表、景色评分、趣味评分、性价比评分、推荐项目

断点续跑机制

pipeline_progress.json：仅当某景点详情与评论都成功时才写入。只成功一项的景点不会被标记完成，下次运行会重新尝试该景点。
comments_progress.json：位于景点目录，按 {poi_id: {last_page, total_pages, status}} 记录评论断点。
failed_pages.json：位于景点目录，记录 {poi_id, page, error, timestamp}，便于定位与补采。
需要强制重新采集时，删除对应进度文件即可。

日志按平台、组件和日期组织：

logs/
├── ctrip/
│   ├── pipeline_2026-10-24.log
│   └── comment_spider_2026-10-24.log
└── qunar/
    ├── pipeline_2026-10-24.log
    └── comment_spider_2026-10-24.log

测试

# 当前开发环境
D:\Environments\Anaconda\envs\AI\python.exe -m pytest -q

# 或任意可用的 Python >= 3.9
python -m pytest -q

pyproject.toml 已配置 pythonpath = ["src"]，无需手动设置 PYTHONPATH。当前离线测试按 core/、platforms/ 与 integration/ 组织，manual/ 仅存放需要手动执行的联网或调试脚本。

测试文件	覆盖内容
`core/test_base_spider.py`	`BaseSpider` 共享重试封装、`CtripBaseSpider` JSON POST、继承契约
`core/test_logger.py`	分级日志格式、URL 脱敏、日志文件分组、请求/延迟统计
`core/test_storage_layout.py`	行政区解析、安全路径、平台/省市/景点目录布局
`integration/test_pipeline_cli.py`	`run()` 四种目标分发、城市/景点解析与统一 CLI 参数
`integration/test_keyboard_interrupt.py`	评论爬虫与流水线 `Ctrl+C` 中断保留断点/已完成进度
`platforms/ctrip/test_sight_locator.py`	关键词 → 景点 / 地区 ID 解析、类型自动判断、解析边界条件
`platforms/ctrip/test_sight_list.py`	POI 解析、请求体构建、分页取数
`platforms/ctrip/test_comment_storage.py`	CSV 表头、字段顺序、跨页追加、断点进度
`platforms/ctrip/test_comment_pagination.py`	总页数向上取整计算
`platforms/qunar/test_sight_workflow.py`	去哪儿详情、列表、定位、评论与流水线工作流
`platforms/qunar/test_comments.py`	去哪儿 `window.context` 评论解析与兜底逻辑
`platforms/qunar/test_online.py`	去哪儿联网冒烟测试（离线自动跳过）

手动脚本	用途
`manual/ctrip_online_smoke.py`	携程联网冒烟测试
`manual/ctrip_comments_api_debug.py`	携程评论 API 响应结构探测
`manual/ctrip_sight_detail_debug.py`	携程景点详情 API 响应结构探测
`manual/logger_smoke.py`	手动检查日志各级别输出

除 platforms/qunar/test_online.py 外，其余自动收集的测试均为离线测试（mock 网络），不依赖真实 API。manual/ 下的文件名不匹配 test_*.py，pytest 不会自动收集，需要时手动运行。

项目结构

LifeLens/
├── pyproject.toml                # 依赖管理 + 项目元数据 + pytest 配置
├── .env.example                  # 配置模板（代码暂未读取）
├── src/lifelens/
│   ├── __main__.py               # 顶层 CLI 入口（子命令占位）
│   ├── config.py                 # 集中配置 (URL / headers / 超时 / 分页)
│   ├── core/                     # 基础设施层 (平台无关)
│   │   ├── base_spider.py        #   BaseSpider 抽象基类 + 重试封装
│   │   ├── logger.py             #   SpiderLogger 分级日志 + 任务汇总
│   │   ├── request_optimizer.py  #   随机延迟 + 代理 + 退避参数
│   │   ├── storage_layout.py     #   跨平台数据目录布局 + 行政区解析
│   │   ├── storage.py            #   StorageBackend (JSON / CSV)
│   │   └── pipeline.py           #   BasePipeline + PipelineStats 结果统计
│   ├── platforms/
│   │   ├── ctrip/                # 携程平台
│   │   │   ├── sight_locator.py  #   关键词 → POI ID / 地区 ID (自动解析)
│   │   │   ├── sight_list.py     #   地区 → 景点列表 (分页)
│   │   │   ├── sight_detail.py   #   景点详情 (电话/门票/描述/交通)
│   │   │   ├── sight_comments.py #   评论爬取 (断点续爬 + CSV)
│   │   │   ├── base.py           #   CtripBaseSpider 公共请求/重试基类
│   │   │   └── pipeline.py       #   CtripPipeline 全流程编排 (含 CLI)
│   │   ├── qunar/                # 去哪儿平台
│   │   │   ├── sight_locator.py  #   景点 / 城市 → ID 解析
│   │   │   ├── sight_list.py     #   城市榜单 → 景点列表
│   │   │   ├── sight_detail.py   #   详情页 + 内嵌简介页解析
│   │   │   ├── sight_comments.py #   评论爬取 (window.context + CSV)
│   │   │   ├── base.py           #   QunarBaseSpider 公共 GET / 解析基类
│   │   │   └── pipeline.py       #   QunarPipeline 全流程编排 (含 CLI)
│   │   └── meituan/              # 美团平台 (待实现)
│   ├── models/
│   │   └── sight.py              # Sight / SightDetail / Comment 数据模型
│   └── analysis/                 # 分析层 (待实现)
│       ├── sentiment.py          #   情感分析
│       ├── wordcloud.py          #   词云生成
│       └── heatmap.py            #   地理热图
├── tests/                        # 测试套件
│   ├── core/                     #   核心基础设施测试
│   ├── platforms/                #   平台测试（ctrip / qunar）
│   ├── integration/              #   跨模块与流水线测试
│   └── manual/                   #   手动联网与调试脚本
├── data/                         # 输出目录 (gitignored)
└── logs/                         # 日志目录 (gitignored)

技术栈

层级	技术
网络请求	`requests`（会话 + 随机延迟 + 3 次退避重试）
HTML 解析	`beautifulsoup4`
数据模型	`dataclasses`
存储	标准库 `json` / `csv`（`utf-8-sig`）
测试框架	`pytest`
分析层 (计划)	`pandas` · `scikit-learn` · `jieba` · `matplotlib` · `seaborn` · `geopandas`

路线图

使用须知

使用本项目即表示你已阅读并同意以下条款。如不同意，请停止使用并删除本项目及相关数据。

1. 项目定位

本项目仅用于个人学习、技术研究与数据分析练习，不提供任何形式的数据采集服务，也不构成对任何平台数据的授权。

2. 合规使用

使用前请自行确认目标平台的服务条款、robots 协议、用户协议以及所在地法律法规；
不得采集、存储或传播涉及国家安全、商业秘密、个人隐私或其他受法律保护的信息；
不得绕过登录验证、验证码、访问控制、反爬机制或其他技术保护措施；
不得将本项目用于大规模、高频次或影响目标平台正常运行的采集活动；
如需采集个人信息，应取得合法授权，并遵循最小必要原则。

3. 使用限制

禁止将本项目及其衍生代码用于任何商业用途，包括但不限于销售、付费服务、数据转售或商业数据产品；
禁止将采集结果用于骚扰、画像、精准营销、欺诈或其他侵害他人权益的行为；
禁止删除、隐藏或篡改本项目中的版权声明与许可信息。

4. 数据与隐私

采集数据归原始权利人或相关平台所有，本项目不授予你对第三方数据的任何权利；
评论、用户昵称、IP 归属地等字段可能涉及个人信息，请谨慎存储、脱敏处理，并在使用后及时删除；
请勿将采集数据上传至公开仓库、云盘或其他可被未授权访问的位置。

5. 请求频率与平台影响

默认随机延迟为 1-3 秒，请根据实际情况适当调大，避免对目标平台造成压力；
出现限流、封禁或异常响应时应立即停止采集；
本项目不提供绕过限流、验证码或封禁的能力。

6. 账号与凭证

请勿将 Cookie、Token、账号密码等敏感凭证提交至版本库；
建议将凭证保存在本地未跟踪文件中，并定期轮换；
因凭证泄露造成的损失由使用者自行承担。

7. 风险与责任

本项目按“现状”提供，不保证功能完整性、稳定性或适用性；
因使用或无法使用本项目导致的任何直接或间接损失、数据丢失、账号封禁或法律纠纷，作者不承担责任；
使用者应自行评估并承担全部使用风险。

8. 条款变更

作者保留随时修改本使用须知的权利，修改后的条款自发布之日起生效。

License

本项目采用 CC BY-NC 4.0（知识共享署名-非商业性使用 4.0 国际）许可协议，完整条款见 LICENSE。

在遵守以下条件的前提下，你可以复制、修改、分发和以非商业目的使用本项目：

署名：必须注明原作者及本项目链接，并说明是否作出修改；
非商业性使用：不得将本项目用于商业目的，包括销售、付费服务、数据转售或其他直接或间接获利行为；
无附加限制：不得通过法律条款或技术手段限制他人行使许可证允许的权利。

如需学术授权、商业授权或其他用途，请联系 hsuantx@163.com。

注意：本项目许可证仅覆盖本项目代码与文档，不覆盖通过本项目采集的第三方数据。第三方数据的版权、使用权与合规责任由原始权利人或使用者自行承担。

Navigation Menu

Repository navigation

About

Repository files navigation

LifeLens

功能概览

环境要求

快速开始

安装

命令行用法

编程式用法

单模块使用

配置

数据输出

断点续跑机制

测试

项目结构

技术栈

路线图

使用须知

1. 项目定位

2. 合规使用

3. 使用限制

4. 数据与隐私

5. 请求频率与平台影响

6. 账号与凭证

7. 风险与责任

8. 条款变更

License

About

Releases

Packages

Used by

Contributors

Languages

Name		Name	Last commit message	Last commit date
src/lifelens		src/lifelens
tests		tests
.env.example		.env.example
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
pyproject.toml		pyproject.toml

Latest commit

History

Folders and files

Repository files navigation

LifeLens

功能概览

环境要求

快速开始

安装

命令行用法

编程式用法

单模块使用

配置

数据输出

断点续跑机制

测试

项目结构

技术栈

路线图

使用须知

1. 项目定位

2. 合规使用

3. 使用限制

4. 数据与隐私

5. 请求频率与平台影响

6. 账号与凭证

7. 风险与责任

8. 条款变更

License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages