Skip to content

KanoCifer/Flask-Example

BranchesTags

Repository files navigation

ReadingList

Python FastAPI Vue SQLAlchemy TypeScript Tailwind CSS PostgreSQL MongoDB Redis Pinia

基于 FastAPI + Vue 3 的全栈阅读清单管理与个人博客系统。

功能特性

功能模块 描述
用户系统 注册、登录、个人资料、JWT/Cookie 认证
书籍管理 书籍 CRUD、书架展示、阅读进度追踪
微信读书 从微信读书导入书籍
博客系统 文章发布、分类、标签、评论
留言板 访客留言、管理
RSS 阅读器 RSS 订阅解析、文章聚合
AI 助手 文章总结（Redis 缓存）
后台监控 系统运行数据监控

技术栈

  • 后端: FastAPI + SQLAlchemy 2.0 + Alembic + PostgreSQL + MongoDB (Beanie) + Redis
  • 前端: Vue 3.5 + TypeScript + Vite + Tailwind CSS v4 + Pinia + shadcn-vue + motion-v
  • AI: Agno (Langchain 替代方案)
  • 安全: JWT 认证、CSRF 保护、输入验证

快速开始

# 1. 后端环境
cd backend
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt  # 或 pip install -e .

# 2. 配置环境变量
cp .env.example .env  # 编辑 .env 配置数据库等

# 3. 数据库迁移
alembic upgrade head

# 4. 启动开发服务器
python dev.py           # 后端 :5555
cd ../frontend && pnpm install && pnpm run dev  # 前端 :5173

访问 http://localhost:5173

常用命令

后端

cd backend
python dev.py                           # 启动 (:5555)
ruff format . && ruff check .           # 格式化 + 检查
ruff check . --fix                      # 自动修复
alembic revision --autogenerate -m "x"  # 生成迁移
alembic upgrade head                    # 执行迁移

# 测试
python -m pytest                                  # 运行所有测试
python -m pytest test/test_main.py -v             # 单个测试文件
python -m pytest test/core/test_config.py::test_config_loading -v # 单个测试函数
python -m pytest -k "config" -v                   # 按关键字过滤
python -m pytest --tb=short                        # 简短 traceback

前端

cd frontend
pnpm run dev                            # 启动 (:5173)
pnpm run format                         # Prettier 格式化
pnpm run lint                           # Oxlint + ESLint 检查
pnpm run type-check                     # TypeScript 类型检查
pnpm run build                          # 完整构建 (type-check + compile)
pnpm run build-only                     # 仅构建 (跳过 type-check)

# 测试
pnpm run test:unit                      # Vitest 单元测试
pnpm run test:unit -- src/path/to/file.test.ts # 单个测试文件
pnpm run test:unit -- -t "should render title" # 按测试名过滤
pnpm run test:unit -- src/path/to/file.test.ts -t "should render title" # 文件 + 测试名
pnpm run test:unit -- src/path/to/file.test.ts:42 # 文件 + 行号
npx playwright test                     # E2E 测试
npx playwright test --headed            # 可视化模式
npx playwright test --debug             # 调试模式

项目结构

backend/app/
├── api/v1/              # API 端点 (auth, books, blog, messages, weread, rss, admin, ai, todos, monitor)
├── models/              # 数据库模型 (SQLAlchemy 2.0 + MongoDB Beanie)
├── schemas/             # Pydantic schemas (按领域拆分)
├── repositories/        # 数据访问层
├── services/            # 业务逻辑层
├── core/                # 配置、日志、AI Agent
├── utils/               # 工具函数
├── tasks/               # Taskiq 异步任务
└── main.py              # FastAPI 入口

frontend/src/
├── views/               # 页面组件 (auth, blog, rss, books, general)
├── components/          # 可复用组件 (ui/, bento/, basic/, icons/, editor/)
├── stores/              # Pinia 状态管理
├── auth/                # 认证逻辑
├── service/             # API 调用和业务逻辑
├── router/              # Vue Router
├── types/               # TypeScript 类型定义
├── lib/                 # 第三方库封装
├── utils/               # 工具函数
├── layouts/             # 布局组件
└── assets/              # 静态资源

tests/                   # Pytest (后端) + Playwright (E2E)
scripts/                 # 工具脚本

架构设计

总体架构（前后端分离）

  • Frontend (Vue 3 + TypeScript)：负责页面渲染、交互状态管理、路由与鉴权守卫。
  • Backend (FastAPI)：负责 REST API、业务编排、认证授权、任务调度。
  • Data Layer：PostgreSQL（核心业务数据）+ MongoDB（文档型数据）+ Redis（缓存/会话/异步队列）。
flowchart LR
    U[User Browser] --> F[Frontend\nVue3 + TS + Vite]
    F -->|HTTP / Cookie / CSRF| B[Backend API\nFastAPI]
    B --> PG[(PostgreSQL)]
    B --> MG[(MongoDB)]
    B --> RD[(Redis)]
    B --> TQ[Taskiq Worker]
Loading

后端分层设计

  • API 层 (api/v1)：参数校验、鉴权、响应封装，不承载复杂业务。
  • Service 层 (services)：核心业务逻辑，组合仓储与外部依赖。
  • Repository 层 (repositories)：数据访问抽象，隔离 SQL/ORM 查询细节。
  • Schema 层 (schemas)：请求/响应模型定义，保证输入输出契约稳定。
  • Core/Tasks 层 (core, tasks)：配置、日志、异常处理、异步任务与定时任务。

前端模块设计

  • Views (views/)：页面级容器，按业务领域组织。
  • Components (components/)：可复用 UI 组件，减少重复实现。
  • Stores (stores/)：Pinia 全局状态（用户、主题、通知、业务状态）。
  • Auth + Service (auth/, service/)：认证副作用、token 续期、API 调用封装。
  • Router (router/)：路由注册、权限拦截、页面元信息管理。

关键设计原则

  1. 分层解耦：高内聚，低耦合。UI、业务、数据访问分离，降低耦合便于演进。
  2. 类型优先：前端 TypeScript + 后端 Pydantic，减少接口漂移。
  3. 安全默认：JWT/Cookie + CSRF 防护 + 输入校验。
  4. 异步扩展：Taskiq + Redis/RabbitMQ 支撑耗时任务与后台处理。
  5. 可维护性：统一 lint/format/type-check/test 流程，保持代码一致性。

API 端点 (:5555)

路由 描述
/api/v1/auth 认证 (登录/注册/Passkey/OAuth)
/api/v1/books 书籍管理 (CRUD、阅读进度)
/api/v1/users 用户资料 (设置、头像)
/api/v1/blog 博客系统 (文章/评论/分类)
/api/v1/messages 留言板
/api/v1/weread 微信读书导入
/api/v1/rss RSS 订阅器
/api/v1/admin 管理员 (内容审核)
/api/v1/ai AI 助手 (文章摘要)
/api/v1/todos 待办事项
/api/v1/monitor 系统监控

配置

SECRET_KEY=your-secret-key-here
DATABASE_URL=postgresql+psycopg2://user:pass@localhost/readinglist
MONGO_URI=mongodb://localhost:27017/readinglist
REDIS_URL=redis://localhost:6379/0

代码风格

  • 后端: Ruff (79字符, 4空格, 双引号), Python 3.14+ 类型注解
  • 前端: Prettier + ESLint + Oxlint, Tailwind CSS, <script setup>
  • 详细规范: 见 CLAUDE.md

提交规范

  1. 后端提交前: cd backend && ruff format . && ruff check .
  2. 前端提交前: cd frontend && pnpm format && pnpm lint && pnpm type-check
  3. 提交信息: Conventional Commits (feat:, fix:, docs:, style:, refactor:, perf:, test:, chore:)
  4. 分支命名: feature/xxx, fix/xxx, refactor/xxx

部署

  • 在线演示: Kuroome's Blog
  • 本地端口: 后端 :5555 / 前端 :5173

License

MIT

About

My Blog

kanocifer.chat

Topics

vue3 fastapi

Resources

Readme

License

MIT license
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Contributors

Languages