
文章目录第一章 项目概述与需求分析1.1 项目背景1.1.1 什么是"数据雷达系统"1.1.2 项目起源与应用场景1.1.3 目标用户群体1.1.4 项目定位与技术特色1.2 核心功能需求1.2.1 功能一:获取所有订阅博主的近期文章列表1.2.2 功能二:基于博主ID查询指定博主的近期文章列表1.2.3 功能三:获取已订阅博主列表1.2.4 辅助功能健康检查接口前端展示页面新文章检测脚本1.3 技术选型分析1.3.1 后端框架选择:FastAPI1.3.2 HTTP客户端选择:httpx1.3.3 RSS解析库选择:feedparser1.3.4 数据校验库选择:Pydantic1.3.5 数据库选择:SQLite + aiosqlite1.3.6 ASGI服务器选择:uvicorn1.4 系统架构设计1.4.1 整体架构图1.4.2 分层架构说明1.4.3 模块依赖关系1.5 数据流图解1.5.1 获取全部文章的数据流1.5.2 按博主查询的数据流1.5.3 数据实体关系图(ER图)第二章 开发环境准备2.1 操作系统选择2.1.1 支持的操作系统2.1.2 Windows用户特别说明2.1.3 macOS用户特别说明2.2 Python安装与配置2.2.1 版本要求2.2.2 Ubuntu/Debian安装Python2.2.3 CentOS/RHEL安装Python2.2.4 macOS安装Python2.2.5 Windows安装Python2.2.6 Python环境变量配置(如需要)2.3 IDE开发工具选择2.3.1 推荐IDE对比2.3.2 VS Code配置指南(推荐)2.3.3 PyCharm配置指南2.4 Git版本控制工具2.4.1 为什么需要Git2.4.2 安装Git2.4.3 Git初始配置2.4.4 GitHub账户准备2.5 虚拟环境管理2.5.1 什么是虚拟环境2.5.2 venv(Python内置,推荐)2.5.3 常用虚拟环境命令2.5.4 Poetry/Pipenv(进阶选择)2.6 环境变量配置2.6.1 什么是环境变量2.6.2 为什么不用硬编码2.6.3 .env文件的使用约定2.6.4 本项目的环境变量2.6.5 不同系统的环境变量设置方式2.7 上游服务部署说明2.7.1 we-mp-rss服务简介2.7.2 we-mp-rss部署方式2.7.3 验证we-mp-rss是否正常运行2.7.4 配置本项目的WERSS_BASE_URL第三章 项目初始化与目录结构搭建3.1 创建项目根目录3.1.1 选择合适的位置3.1.2 创建目录3.2 初始化Git仓库3.2.1 初始化命令3.2.2 创建初始提交License添加到暂存区创建初始提交3.3 创建虚拟环境并激活3.3.1 创建虚拟环境3.3.2 激活虚拟环境3.3.3 验证Python路径3.4 创建requirements.txt依赖文件3.4.1 为什么需要requirements.txt3.4.2 创建requirements.txt3.4.3 版本锁定的重要性3.5 安装项目依赖包3.5.1 执行安装命令3.5.2 观察安装过程3.5.3 验证安装结果3.5.4 导出当前依赖(用于版本锁定)3.6 创建.gitignore文件3.6.1 什么是.gitignore3.6.2 创建.gitignore3.6.3 逐段解释3.6.4 验证.gitignore生效3.7 创建.env.example环境变量模板3.7.1 目的与作用3.7.2 创建.env.example3.7.3 创建实际的.env文件3.8 完整目录结构说明3.8.1 最终目录树3.8.2 各部分职责总结3.8.3 第一次提交当前进度第四章 配置模块开发(config.py)4.1 配置模块的作用与重要性4.1.1 为什么需要专门的配置模块4.1.2 配置管理的最佳实践4.2 pydantic-settings库介绍4.2.1 什么是pydantic-settings4.2.2 核心概念:BaseSettings4.2.3 配置读取优先级4.3 完整代码实现与逐行详解4.4 配置项详细说明4.4.1 werss_base_url(we-mp-rss服务地址)4.4.2 radar_port(服务端口)4.4.3 default_limit(默认分页大小)4.4.4 max_limit(最大分页限制)4.5 环境变量加载机制4.5.1 加载流程图4.5.2 验证配置是否正确加载4.6 配置最佳实践4.6.1 十二因子应用法则(12-Factor App)4.6.2 多环境配置策略4.6.3 敏感信息保护清单第五章 数据模型定义(models.py)5.1 Pydantic库简介5.1.1 什么是Pydantic5.1.2 Pydantic V2 vs V15.1.3 基本用法示例5.2 为什么需要数据模型5.2.1 没有数据模型的问题5.2.2 使用数据模型的优势5.3 ArticleItem模型详解5.3.1 模型定义5.3.2 字段详解5.3.3 id字段的格式说明5.4 ArticleListResponse模型详解5.4.1 模型定义5.4.2 字段详解5.4.3 JSON示例5.5 BloggerInfo模型详解5.5.1 模型定义5.5.2 字段详解5.6 完整代码实现与逐行注释5.7 模型验证机制5.7.1 自动验证演示5.7.2 常用验证装饰器第六章 数据库模块开发(database.py)6.1 SQLite数据库简介6.1.1 什么是SQLite6.1.2 SQLite的适用场景6.2 为什么选择SQLite6.2.1 替代方案对比6.2.2 本项目选择SQLite的理由6.3 aiosqlite异步库介绍6.3.1 为什么需要异步数据库6.3.2 aiosqlite基本用法6.3.3 aiosqlite vs sqlite3 API对比6.4 数据库表结构设计6.4.1 ER图回顾6.4.2 字段设计理由6.4.3 索引设计6.5 init_db函数详解6.5.1 函数签名与目的6.5.2 实现细节6.5.3 关键点解释6.6 upsert_article函数详解6.6.1 函数签名6.6.2 Upsert的概念6.6.3 完整实现分析6.6.4 参数化查询的安全性6.7 upsert_articles批量操作函数详解6.7.1 函数签名6.7.2 实现逻辑6.7.3 为什么不用批量INSERT6.8 get_stored_articles查询函数详解6.8.1 函数签名6.8.2 实现逻辑6.8.3 row_factory的作用6.9 完整代码实现与逐行注释6.10 数据库优化建议6.10.1 当前实现的性能特征6.10.2 潜在优化方向第七章 API客户端模块开发(client.py)7.1 httpx异步HTTP客户端库介绍7.1.1 httpx简介7.1.2 基本用法7.1.3 在本项目中的应用7.2 feedparser RSS解析库介绍7.2.1 RSS/Atom格式简介7.2.2 feedparser基本用法7.2.3 feedparser的字段映射7.3 we-mp-rss上游服务接口说明7.3.1 接口概览7.3.2 全部文章Feed接口7.3.3 单博主Feed接口7.3.4 博主列表接口7.4 WerssClient类的设计思路7.4.1 类的职责7.4.2 类的结构7.4.3 设计模式7.5 _extract_mp_id辅助函数详解7.5.1 函数实现7.5.2 正则表达式解析7.6 get_all_articles_via_feed方法详解7.6.1 方法签名7.6.2 实现逻辑流程图7.6.3 完整实现7.7 get_articles_by_mp_via_feed方法详解7.7.1 方法签名7.7.2 与全量接口的区别7.7.3 完整实现7.8 get_subscribed_mps_via_rss方法详解7.8.1 方法签名7.8.2 完整实现7.9 feedparser的id覆盖问题及解决方案7.9.1 问题根源7.9.2 解决方案:正则提取7.9.3 为什么不用XML解析器7.10 完整代码实现与逐行注释第八章 业务逻辑层开发(service.py)8.1 服务层架构模式8.1.1 服务层的职责8.1.2 本项目服务层的具体职责8.1.3 为什么需要服务层8.2 RadarService类的设计8.2.1 类的职责划分8.2.2 设计原则8.3 _extract_mp_num_from_article_id辅助函数8.3.1 函数实现8.3.2 正则表达式解析8.3.3 为什么需要这个函数8.4 get_all_recent_articles方法详解8.4.1 方法签名8.4.2 完整实现8.4.3 流程图解8.5 get_articles_by_blogger方法详解8.5.1 方法签名8.5.2 完整实现8.5.3 与功能一的对比8.6 list_bloggers方法详解8.6.1 方法实现8.6.2 为什么这么简单8.7 _build_mp_name_map映射构建方法8.7.1 方法实现8.7.2 映射关系图解8.8 完整代码实现与逐行注释第九章 FastAPI主应用开发(main.py)9.1 FastAPI框架简介9.1.1 什么是FastAPI9.1.2 FastAPI与其他框架对比9.2 应用生命周期管理9.2.1 什么是 lifespan9.2.2 本项目的lifespan实现9.2.3 app.state的作用9.3 路由定义与请求处理9.3.1 路由装饰器9.3.2 路径参数9.3.3 查询参数9.4 健康检查端点9.4.1 实现代码9.4.2 为什么需要健康检查9.5 文章列表API端点9.5.1 实现代码9.5.2 请求/响应示例9.6 按博主查询API端点9.6.1 实现代码9.6.2 请求示例9.7 博主列表API端点9.7.1 实现代码9.8 静态文件服务与前端页面9.8.1 静态文件挂载9.8.2 前端页面路由9.9 uvicorn服务器启动配置9.9.1 __main__入口9.9.2 各参数说明9.9.3 生产环境启动方式9.10 完整代码实现与逐行注释第十章 定时任务脚本开发(check_new_articles.py)10.1 定时任务的应用场景10.1.1 为什么需要定时任务10.1.2 本脚本的功能10.2 asyncio异步编程基础10.2.1 什么是asyncio10.2.2 基本用法10.2.3 本脚本中的asyncio使用10.3 脚本执行流程分析10.3.1 完整流程图10.3.2 输出示例10.4 完整代码实现与逐行注释10.5 crontab定时任务配置10.5.1 crontab简介10.5.2 crontab格式10.5.3 配置示例10.5.4 常用crontab命令第十一章 前端页面开发(static/index.html)11.1 前端技术栈概述11.1.1 技术选型11.1.2 页面功能清单11.2 HTML结构设计11.2.1 整体结构11.2.2 语义化标签使用11.3 CSS样式系统详解11.3.1 CSS变量系统(Design Tokens)11.3.2 布局系统11.3.3 卡片样式11.3.4 响应式断点11.4 JavaScript交互逻辑详解11.4.1 状态管理11.4.2 API调用封装11.4.3 初始化流程11.5 API调用封装11.5.1 Fetch API vs Axios11.5.2 请求配置11.6 渲染逻辑详解11.6.1 博主列表渲染11.6.2 文章列表渲染11.6.3 单张卡片渲染11.7 图片懒加载实现11.7.1 什么是懒加载11.7.2 IntersectionObserver实现11.8 响应式布局适配11.8.1 断点设计11.8.2 移动端优化11.9 完整HTML/CSS/JS代码第十二章 测试与调试指南12.1 单元测试编写12.1.1 测试框架选择12.1.2 配置文件12.1.3 示例测试用例12.1.4 运行测试12.2 接口测试方法12.2.1 使用curl测试12.2.2 使用FastAPI自带的Swagger UI12.2.3 使用Thunder Client(VS Code扩展)12.3 常见错误排查12.3.1 连接拒绝错误12.3.2 超时错误12.3.3 模块导入错误12.3.4 数据库锁定错误12.4 日志配置与调试技巧12.4.1 添加日志配置12.4.2 使用debugpy调试(VS Code)第十三章 部署上线指南13.1 Docker容器化部署13.1.1 创建Dockerfile13.1.2 创建.dockerignore13.1.3 构建和运行13.1.4 Docker Compose编排13.2 服务器部署方案13.2.1 服务器要求13.2.2 部署步骤13.3 Nginx反向代理配置13.3.1 为什么需要Nginx13.3.2 配置文件13.3.3 启用配置13.3.4 HTTPS配置(Let's Encrypt)13.4 systemd服务管理13.4.1 创建服务文件13.4.2 服务管理命令13.5 监控与告警配置13.5.1 基础监控脚本13.5.2 配置监控定时任务13.5.3 推荐监控方案第十四章 进阶扩展方向14.1 缓存机制引入14.1.1 为什么需要缓存14.1.2 Redis缓存方案14.2 消息队列集成14.2.1 使用场景14.2.2 Celery + Redis方案14.3 用户认证系统14.3.1 为什么需要认证14.3.2 JWT认证实现14.4 数据可视化增强14.4.1 统计图表14.4.2 使用ECharts实现14.5 微信公众号API直连14.5.1 当前架构的局限14.5.2 直连方案依赖版本清单第一章 项目概述与需求分析1.1 项目背景1.1.1 什么是"数据雷达系统"数据雷达系统(Data Radar System)是一个基于微信公众号RSS订阅的文章聚合与监控平台。它的核心价值在于帮助用户实时追踪多个微信公众号的最新文章动态,类似于一个"信息雷达",能够自动扫描、收集、整理和展示所关注公众号的最新内容。1.1.2 项目起源与应用场景在当今信息爆炸的时代,微信公众号已经成为中文互联网最重要的内容分发渠道之一。许多技术从业者、自媒体运营者、研究人员需要同时关注数十甚至上百个公众号,手动逐一查看每个公众号的更新既耗时又容易遗漏。本项目应运而生,主要解决以下痛点:痛点描述本项目解决方案信息分散需要打开多个公众号逐一查看统一聚合展示所有订阅号最新文章更新不及时无法第一时间获知新文章发布自动检测新文章并标记NEW标识内容筛选困难无法快速定位感兴趣的内容支持按博主过滤、时