gao/python-template
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
master
python-template/TEMPLATE_GUIDE.md
T
bruno d9873219d6 init template
2025-11-27 21:17:46 +08:00

9.4 KiB
Raw Permalink Blame History

项目模板使用指南

概述

这是一个生产级的 FastAPI + Vue 3 全栈应用模板，包含完整的用户认证、文件上传、数据库操作和现代化前端界面。

模板特性

后端 (FastAPI)

  • ✅ RESTful API 设计
  • ✅ JWT 身份认证
  • ✅ SQLAlchemy ORM (支持 PostgreSQL/SQLite)
  • ✅ 文件上传处理
  • ✅ PDF 处理能力
  • ✅ AI 模型集成 (Claude, Gemini)
  • ✅ 自动 API 文档 (Swagger/OpenAPI)
  • ✅ CORS 配置
  • ✅ 环境变量管理

前端 (Vue 3)

  • ✅ Composition API
  • ✅ Element Plus UI 组件库
  • ✅ Pinia 状态管理
  • ✅ Vue Router 路由
  • ✅ Vite 构建工具
  • ✅ 响应式设计
  • ✅ 统一配置管理
  • ✅ API 服务封装

快速开始

方法一: 使用自动化脚本 (推荐)

# 1. 运行创建脚本
./create-from-template.sh

# 2. 根据提示输入项目信息
Project name: my-awesome-app
Display name: My Awesome App
Database name: myapp_db
API port: 8888
Frontend port: 3000

# 3. 脚本会自动:
#    - 创建新项目目录
#    - 复制所有文件
#    - 替换配置项
#    - 清理临时文件
#    - 初始化 git 仓库

方法二: 手动创建

1. 复制项目

# 复制整个项目到新目录
cp -r /path/to/pager /path/to/your-new-project
cd /path/to/your-new-project

# 清理不需要的文件
rm -rf .git backend/__pycache__ backend/wordmaster.db backend/uploads/* frontend/node_modules frontend/dist

2. 配置后端

cd backend

# 复制环境变量配置
cp .env.example .env

# 编辑 .env 文件，修改以下配置:
# - DATABASE_URL: 数据库连接字符串
# - SECRET_KEY: JWT 密钥 (必须修改!)
# - OPENROUTER_API_KEY: AI API 密钥 (如需要)
# - AI_MODEL: AI 模型选择

# 安装依赖
pip install -r requirements.txt

# 初始化数据库
python main.py

3. 配置前端

cd frontend

# 编辑 package.json
# 修改 "name": "your-project-frontend"

# 安装依赖
npm install

# 配置开发环境变量 (可选)
# 编辑 .env.development
# VITE_API_BASE_URL=http://localhost:8888/api

4. 修改项目名称和品牌

需要修改的文件:

后端:

  • backend/main.py: 数据库名称、应用描述
  • backend/.env: 数据库连接字符串

前端:

  • frontend/package.json: 项目名称
  • frontend/index.html: 页面标题
  • frontend/src/config/index.js: API 端口配置

5. 启动项目

# 后端 (在 backend 目录)
python main.py
# 或
uvicorn main:app --host 0.0.0.0 --port 8888 --reload

# 前端 (在 frontend 目录)
npm run dev

项目结构详解

your-project/
├── backend/                    # FastAPI 后端
│   ├── main.py                # 主应用文件 (所有 API 端点)
│   ├── requirements.txt       # Python 依赖
│   ├── .env.example          # 环境变量示例
│   ├── migrate_db.py         # 数据库迁移脚本
│   ├── pdf_splitter_*.py     # PDF 处理模块
│   ├── claude_exam_parser.py # AI 解析器
│   ├── utils/                # 工具函数
│   └── uploads/              # 文件上传目录
│
├── frontend/                  # Vue 3 前端
│   ├── src/
│   │   ├── main.js           # 应用入口
│   │   ├── App.vue           # 根组件
│   │   ├── router/           # 路由配置
│   │   ├── stores/           # Pinia 状态管理
│   │   ├── views/            # 页面组件
│   │   ├── components/       # 可复用组件
│   │   ├── config/           # 配置管理
│   │   └── services/         # API 服务
│   ├── package.json          # 前端依赖
│   └── vite.config.js        # Vite 配置
│
├── start.sh                   # 开发启动脚本
├── stop.sh                    # 停止脚本
├── status.sh                  # 状态检查脚本
├── template.config.json       # 模板配置
└── TEMPLATE_GUIDE.md         # 本文档

核心功能模块

1. 用户认证系统

后端实现 (backend/main.py):

# 注册
@app.post("/api/auth/register")

# 登录
@app.post("/api/auth/login")

# 获取当前用户
def get_current_user(credentials: HTTPAuthorizationCredentials)

前端实现 (frontend/src/stores/auth.js):

// 登录
async login(username, password)

// 注册
async register(username, password)

// 登出
logout()

// 自动加载用户信息
loadUser()

2. 数据库模型

基础模型结构 (backend/main.py):

class User(Base):
    __tablename__ = "users"
    id = Column(Integer, primary_key=True)
    username = Column(String, unique=True)
    password_hash = Column(String)
    created_at = Column(DateTime)

# 添加你自己的模型
class YourModel(Base):
    __tablename__ = "your_table"
    # 定义字段...

3. 文件上传

后端示例:

@app.post("/api/upload")
async def upload_file(
    file: UploadFile = File(...),
    current_user: User = Depends(get_current_user)
):
    # 保存到 uploads/{user_id}/
    file_path = f"uploads/{current_user.id}/{file.filename}"
    # 处理文件...
    return {"file_path": file_path}

前端示例 (使用 Element Plus):

<el-upload
  :action="uploadUrl"
  :headers="headers"
  :on-success="handleSuccess"
>
  <el-button>上传文件</el-button>
</el-upload>

4. 状态管理 (Pinia)

创建新的 store (frontend/src/stores/yourStore.js):

import { defineStore } from 'pinia'
import { ref } from 'vue'

export const useYourStore = defineStore('your-store', () => {
  const data = ref([])

  async function fetchData() {
    // API 调用...
  }

  return { data, fetchData }
})

5. 路由配置

添加新路由 (frontend/src/router/index.js):

{
  path: '/your-page',
  name: 'YourPage',
  component: () => import('../views/YourPage.vue'),
  meta: { requiresAuth: true }  // 需要登录
}

自定义和扩展

添加新的 API 端点

在 backend/main.py 中:

@app.get("/api/your-endpoint")
async def your_endpoint(
    current_user: User = Depends(get_current_user),
    db: Session = Depends(get_db)
):
    # 你的逻辑
    return {"data": "your data"}

添加新的前端页面

  1. 创建组件: frontend/src/views/YourPage.vue
<template>
  <div class="your-page">
    <h1>{{ title }}</h1>
  </div>
</template>

<script setup>
import { ref } from 'vue'

const title = ref('Your Page Title')
</script>
  1. 在路由中注册 (见上面路由配置)

修改数据库模型

  1. 编辑 backend/main.py 中的模型定义
  2. 运行迁移:
cd backend
python migrate_db.py

部署指南

环境变量配置

生产环境必须修改:

# backend/.env
SECRET_KEY=your-very-long-random-secret-key-min-32-chars
DATABASE_URL=postgresql://user:password@host:port/dbname

Docker 部署

创建 Dockerfile (后端):

FROM python:3.9-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8888"]

创建 Dockerfile (前端):

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build
CMD ["npm", "run", "preview"]

Nginx 配置

server {
    listen 80;
    server_name your-domain.com;

    location / {
        root /var/www/frontend/dist;
        try_files $uri $uri/ /index.html;
    }

    location /api {
        proxy_pass http://localhost:8888;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

最佳实践

1. 安全性

  • ✅ 修改默认 SECRET_KEY
  • ✅ 使用 HTTPS (生产环境)
  • ✅ 限制 CORS 源
  • ✅ 定期更新依赖
  • ✅ 不要提交 .env 文件

2. 性能优化

  • ✅ 启用数据库索引
  • ✅ 使用连接池
  • ✅ 前端代码分割
  • ✅ 静态资源 CDN
  • ✅ API 响应缓存

3. 开发规范

  • ✅ 遵循 RESTful API 设计
  • ✅ 使用 TypeScript (可选)
  • ✅ 编写单元测试
  • ✅ 代码审查
  • ✅ Git 提交规范

常见问题

Q: 如何切换数据库?

从 SQLite 到 PostgreSQL:

# 修改 DATABASE_URL
DATABASE_URL = "postgresql://user:password@localhost:5432/dbname"

# 重新创建表
python main.py

Q: 如何添加新的 AI 模型?

编辑 backend/.env:

AI_MODEL=google/gemini-3-pro-preview
# 或
AI_MODEL=openai/gpt-4o

Q: 前端如何跨域请求?

开发环境在 vite.config.js 配置代理:

export default defineConfig({
  server: {
    proxy: {
      '/api': {
        target: 'http://localhost:8888',
        changeOrigin: true
      }
    }
  }
})

Q: 如何部署到云服务器?

  1. 购买云服务器 (阿里云/腾讯云/AWS)
  2. 配置安全组开放端口
  3. 使用 Docker 或 PM2 部署
  4. 配置域名和 HTTPS

模板更新

如果模板有更新，你可以:

  1. 选择性合并:
git remote add template /path/to/template
git fetch template
git cherry-pick <commit-hash>
  1. 手动更新: 比较新旧文件，手动复制需要的功能

技术支持

许可证

MIT License - 自由使用和修改

祝你的项目开发顺利! 🚀

Reference in New Issue View Git Blame Copy Permalink