文章目录
- 第一章 项目概述与需求分析
- 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 后端框架选择：FastAPI
- 1.3.2 HTTP客户端选择：httpx
- 1.3.3 RSS解析库选择：feedparser
- 1.3.4 数据校验库选择：Pydantic
- 1.3.5 数据库选择：SQLite + aiosqlite
- 1.3.6 ASGI服务器选择：uvicorn
- 1.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安装Python
- 2.2.3 CentOS/RHEL安装Python
- 2.2.4 macOS安装Python
- 2.2.5 Windows安装Python
- 2.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 为什么需要Git
- 2.4.2 安装Git
- 2.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.txt
- 3.4.2 创建requirements.txt
- 3.4.3 版本锁定的重要性
- 3.5 安装项目依赖包
- 3.5.1 执行安装命令
- 3.5.2 观察安装过程
- 3.5.3 验证安装结果
- 3.5.4 导出当前依赖（用于版本锁定）
- 3.6 创建.gitignore文件
- 3.6.1 什么是.gitignore
- 3.6.2 创建.gitignore
- 3.6.3 逐段解释
- 3.6.4 验证.gitignore生效
- 3.7 创建.env.example环境变量模板
- 3.7.1 目的与作用
- 3.7.2 创建.env.example
- 3.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-settings
- 4.2.2 核心概念：BaseSettings
- 4.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 什么是Pydantic
- 5.1.2 Pydantic V2 vs V1
- 5.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 什么是SQLite
- 6.1.2 SQLite的适用场景
- 6.2 为什么选择SQLite
- 6.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 为什么不用批量INSERT
- 6.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 什么是FastAPI
- 9.1.2 FastAPI与其他框架对比
- 9.2 应用生命周期管理
- 9.2.1 什么是 lifespan
- 9.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 什么是asyncio
- 10.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 Axios
- 11.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 UI
- 12.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 创建Dockerfile
- 13.1.2 创建.dockerignore
- 13.1.3 构建和运行
- 13.1.4 Docker Compose编排
- 13.2 服务器部署方案
- 13.2.1 服务器要求
- 13.2.2 部署步骤
- 13.3 Nginx反向代理配置
- 13.3.1 为什么需要Nginx
- 13.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标识 |
| 内容筛选困难 | 无法快速定位感兴趣的内容 | 支持按博主过滤、时 |