gudupao-backend-frontend-demo 0.0.18

Add your description here

FastAPI + Vue 3 全栈应用模板

这是一个现代化、生产就绪的全栈应用模板，采用 Python FastAPI 作为后端，Vue 3 作为前端。专为无缝开发体验和单端口部署而设计。

✨ 特性

• 一体化部署: 后端和前端在同一个端口 (8000) 上提供服务，无需额外部署前端服务器。
• SPA 支持: 通过 FastAPI 的 Catch-all 路由完美支持 Vue Router 的 History 模式 (基于 spa-manifest.json 智能路由)。
• 现代化工具链:
  • 后端: 使用 uv 进行超快速的 Python 包管理。
  • 前端: 使用 Vite + pnpm + unplugin-vue-router (基于文件的自动路由)。
• API 自动化:
  • 集成 @hey-api/openapi-ts，后端 API 变更时自动生成类型安全的前端客户端。
  • 开发模式下包含实时 Watcher，自动同步 OpenAPI 规范到前端。
• 高性能服务器: 支持 Granian (Rust 编写的 ASGI 服务器) 作为生产环境服务器选项。
• 跨平台支持: 内置的任务运行器可在 Windows, macOS 和 Linux 上流畅运行。
• 极致开发体验: 仅需一条命令即可同时启动前后端开发服务器，并支持热重载。
• 简便的前端管理: 提供 f 命令代理，无需手动切换目录即可执行前端命令。
• 代码规范: 内置 Ruff (Python) 和 ESLint (Vue/TS) 配置，配合 pre-commit 自动保证代码质量。

📋 环境要求

• Python (3.12+)
• Node.js (20+)
• uv (Python 包管理器)
• pnpm (Node 包管理器)

🚀 快速开始

1. 安装依赖

   # 安装后端依赖 (一般情况下会在执行 uv run 时自动安装)
   uv sync
   
   # 安装前端依赖 (一般情况下在启动 dev 时会自动安装)
   uv run f pnpm install
   

2. 启动开发服务器

   uv run dev
   

   • 后端地址: http://localhost:8000
   • 前端地址: http://localhost:5173 (API 请求会自动代理到后端)

🛠️ 命令参考

我们通过 pyproject.toml 注册了以下快捷命令：

命令	描述
uv run dev	并发启动后端和前端的开发服务器，并自动监视/同步 API 客户端。
uv run build	同步 API 客户端，并将 Vue 前端构建到 frontend_dist/ 目录。
uv run start	启动生产环境后端服务器 (支持 --granian 标志)。
uv run preview	先执行 build 然后执行 start，用于预览生产环境构建效果。
uv run f [cmd]	在 frontend/ 目录下运行命令。例如: uv run f pnpm install
uv run manage update-api	手动从后端生成 OpenAPI 规范并更新前端 API 客户端。
uv run manage setup	手动安装/修复 Git Hooks (通常会自动执行，无需手动运行)。

(注: 旧的 uv run manage [command] 方式依然受支持)

📂 项目结构

.
├── gudupao_backend_frontend_demo/ # Python 包源码
│   ├── app/                  # Python 后端代码
│   │   ├── core/             # 核心逻辑 (如 SPA 路由处理)
│   │   ├── routers/          # API 路由定义
│   │   ├── main.py           # FastAPI 入口点 & 静态文件托管逻辑
│   │   └── ...
│   ├── scripts/              # 项目管理脚本
│   │   └── manage.py         # 任务运行器逻辑 (dev, build, start 等)
│   └── ...
├── frontend/                 # Vue 3 前端源码
│   ├── src/pages/            # 基于文件的路由目录 (自动生成路由)
│   ├── src/client/           # [自动生成] API 客户端代码 (@hey-api)
│   ├── scripts/              # 前端脚本 (如 generate-manifest.ts)
│   ├── vite.config.ts        # Vite 配置 (包含 Proxy 和构建输出配置)
│   └── ...
├── frontend_dist/            # 构建产物 (由 build 命令生成)
├── pyproject.toml            # Python 依赖 & 脚本入口配置
└── uv.lock

🚢 部署指南

⚡ 极速部署 (uvx)

如果你已安装 uv，可以直接运行以下命令来启动最新版本的服务：

uvx gudupao-backend-frontend-demo@latest start

📦 标准部署 (源码构建)

本项目设计为可以像标准 Python 应用一样进行部署。

1. 构建前端 (在 CI/CD 或本地环境执行):

   uv run build
   

2. 准备服务器:
   • 将 gudupao_backend_frontend_demo/ 目录, frontend_dist/ 目录, 和 pyproject.toml 复制到服务器。
   • 确保服务器已安装 Python 和 uv。
3. 运行服务:

   uv sync
   uv run start
   

   • 注意: 生产环境服务器不需要安装 Node.js (因为我们只托管构建好的静态文件)。

🐳 Docker 部署

本项目包含 Dockerfile，支持构建轻量级的生产镜像。镜像已发布至 ghcr.io/gudupaocreativity/demo。

# 拉取并运行
docker run -p 8000:8000 ghcr.io/gudupaocreativity/demo:latest

# 或者本地构建
docker build -t ghcr.io/gudupaocreativity/demo .

支持通过环境变量配置：

• USE_GRANIAN=true: 使用 Granian 服务器。
• WORKERS=4: 设置工作进程数。