前后端开发规范 (React + Flask + MongoDB)

概述

为统一团队技术栈，提升开发效率、代码质量和项目可维护性，特制定本开发规范。所有新项目及现有项目的重构，如无特殊情况，均应遵循此规范。

前端: React (Vite + TypeScript)
后端: Flask (Python)
数据库: MongoDB
包管理器 (前端) : pnpm
包管理器 (后端) : pip

环境准备

在开始项目之前，请确保您的开发环境中已安装以下软件。

安装 Python 和 Pip

Windows:
- 访问 Python 官网下载页面。
- 下载最新的 Python 3.x 版本的安装程序。
- 重要 : 在安装时，务必勾选 "Add Python to PATH" 选项。
- 安装完成后，在命令提示符 (CMD) 或 PowerShell 中运行 python --version 和 pip --version 验证安装。
macOS/Linux : 通常系统会自带 Python 3。您可以通过 python3 --version 检查。如果未安装或版本过低（推荐 3.11+），可以通过 Homebrew (macOS) 或系统的包管理器 (Linux) 安装。
bash 复制代码
```
# macOS (using Homebrew)
brew install python

# Ubuntu/Debian
sudo apt update
sudo apt install python3 python3-pip python3-venv
```

安装 Node.js 和 pnpm

pnpm 依赖于 Node.js 环境。

安装 Node.js:
1. 访问 Node.js 官网，下载并安装 LTS (长期支持) 版本。安装程序会自动将 node 和 npm 添加到系统 PATH。
2. 安装完成后，在终端中运行 node -v 和 npm -v 验证。
安装 pnpm:
1. 我们使用 npm 来全局安装 pnpm。这是最推荐的方式。
2. 打开终端或命令提示符，运行以下命令：
  bash 复制代码
```
npm install -g pnpm
```
3. 安装完成后，运行 pnpm -v 验证安装。

安装 MongoDB

本地开发 : 推荐安装 MongoDB Community Server。根据您的操作系统按照官方指引进行安装。
云服务/Docker : 为方便起见，也可以使用 MongoDB Atlas (云数据库) 或通过 Docker 运行 MongoDB 容器。

项目初始化

所有项目必须遵循以下目录结构和初始化流程。

复制代码

my-project/
├── backend/        # Flask 后端
│   ├── .venv/      # Python 虚拟环境
│   ├── app.py      # Flask 应用主文件
│   ├── .env        # 环境变量
│   └── requirements.txt
└── frontend/       # React 前端
    ├── src/
    └── pnpm-lock.yaml

创建项目根目录

bash 复制代码

mkdir my-project
cd my-project

初始化前端项目 (Frontend)

bash 复制代码

mkdir frontend
cd frontend

使用 pnpm 和 Vite 创建基于 TypeScript 的 React 项目。

bash 复制代码

# `.` 表示在当前目录 (frontend) 创建项目
pnpm create vite . --template react-ts

注意: 在交互式提问中，请确认选择默认选项（不启用实验性功能，并安装必要依赖）。

如果上一步忘记选择安装依赖，可以手动执行：

bash 复制代码

pnpm install

初始化后端项目 (Backend)

返回项目根目录，创建并进入 backend 目录。

bash 复制代码

cd ../backend

创建 Python 虚拟环境。这能确保项目依赖与全局环境隔离。

bash 复制代码

python -m venv .venv

激活虚拟环境。
- Windows (CMD/PowerShell) :
  bash 复制代码
```
.venv\Scripts\activate
```
- macOS/Linux (bash/zsh) :
  bash 复制代码
```
source .venv/bin/activate
```

激活后，你的终端提示符前应出现 (.venv) 字样。

安装必要的 Python 包。

bash 复制代码

# 安装 Flask 核心, PyMongo 用于连接 MongoDB, Flask-Cors 处理跨域, python-dotenv 用于管理环境变量
pip install Flask pymongo Flask-Cors python-dotenv

创建 requirements.txt 文件，用于记录项目依赖。

bash 复制代码

pip freeze > requirements.txt

开发工作流

在开发过程中，前后端服务将独立运行，通过 API 进行通信。

前端开发

进入 frontend 目录。
启动 Vite 开发服务器。

bash 复制代码

cd my-project/frontend
pnpm dev

服务将默认运行在 http://localhost:5173。Vite 提供快速的热模块替换 (HMR)，修改代码后浏览器将自动更新。

后端开发

进入 backend 目录并激活虚拟环境。

bash 复制代码

cd my-project/backend
.venv\Scripts\activate  # Windows
# source .venv/bin/activate  # macOS/Linux

创建一个基础的 app.py 文件，内容如下：

python 复制代码

# backend/app.py
import os
from flask import Flask, jsonify, send_from_directory
from flask_cors import CORS
from pymongo import MongoClient
from dotenv import load_dotenv

# 加载 .env 文件中的环境变量
load_dotenv()

app = Flask(__name__)

# --- 数据库配置 ---
# 从环境变量中获取 MongoDB 连接字符串
MONGO_URI = os.getenv('MONGO_URI')
# 在应用模块级别创建 MongoClient 实例。
# Flask 在单进程模式下会复用这个实例，实现了连接池的效果，避免了为每个请求都建立新连接。
client = MongoClient(MONGO_URI)
db = client.get_database()

# --- CORS 配置 ---
# 从环境变量读取以逗号分隔的来源列表字符串
origins_str = os.getenv('FRONTEND_URLS')
# 如果环境变量存在，则按逗号分割成列表；否则提供一个默认的开发来源
if origins_str:
    origins_list = origins_str.split(',')
else:
    origins_list = ['http://localhost:5173']
print(f"CORS enabled for origins: {origins_list}") # 方便调试时查看
CORS(app, resources={r"/api/*": {"origins": origins_list}})

# --- API 路由示例 ---
@app.route('/api/data')
def get_data():
    # 这是一个示例：从名为 'items' 的 collection 中获取数据
    try:
        items_collection = db.items
        # find() 返回一个 cursor，需要转换为 list
        items = list(items_collection.find({}, {'_id': 0})) # {} 表示查询所有, {'_id': 0} 表示不返回_id字段
        return jsonify({"data": items})
    except Exception as e:
        return jsonify({"error": str(e)}), 500

# --- 服务静态文件 (用于生产环境) ---
# 在开发中，此部分通常不被使用，因为前端由 Vite dev server 提供服务
# 在生产中，Flask 将服务于前端构建出的静态文件
@app.route('/', defaults={'path': ''})
@app.route('/<path:path>')
def serve(path):
    if path != "" and os.path.exists(os.path.join('../frontend/dist', path)):
        return send_from_directory('../frontend/dist', path)
    else:
        return send_from_directory('../frontend/dist', 'index.html')

为了管理敏感信息（如数据库连接字符串），在 backend 目录下创建一个 .env 文件。

env 复制代码

# backend/.env
MONGO_URI="mongodb://localhost:27017/myProjectDB"
FRONTEND_URLS="http://localhost:5173,http://127.0.0.1:5173"

设置 Flask 应用入口并启动开发服务器。

bash 复制代码

# 设置环境变量，告诉 Flask `app.py` 是我们的应用
set FLASK_APP=app.py    # Windows
# export FLASK_APP=app.py  # macOS/Linux

# 开启开发模式，提供热重载和调试器
set FLASK_ENV=development   # Windows
# export FLASK_ENV=development # macOS/Linux

# 启动服务器 (默认运行在 http://localhost:5000)
flask run

# --debug 标志会自动开启调试模式和热重载，无需设置 FLASK_ENV=development
flask --app app run --debug

前端规范

目录结构: 在 frontend/src/ 目录下，建议采用以下结构：
- components/: 存放可复用的UI组件。
- pages/: 存放页面级组件。
- hooks/: 存放自定义 Hooks。
- services/ 或 api/: 封装 API 请求逻辑 (推荐使用 axios)。
- store/: 状态管理逻辑 (如 Zustand, Redux Toolkit)。
- utils/: 工具函数。
- assets/: 静态资源，如图片、字体。
组件: 必须使用函数式组件和 Hooks。
状态管理 : 简单状态使用 useState, useContext。复杂或全局状态推荐使用 Zustand。
API 请求: 使用 axios 并创建一个中心化的实例，统一处理请求头、基地址 (baseURL) 和错误。

后端规范

项目结构 : 对于中大型项目，推荐使用 Blueprints 来组织路由，使代码模块化。
环境变量: 严禁将敏感信息（如数据库密码、密钥）硬编码在代码中。所有配置项都应通过 .env 文件和 os.getenv() 读取。
API 设计:
- 遵循 RESTful 设计原则。
- 所有 API 路由前缀统一为 /api。
- 请求和响应主体使用 JSON 格式。
- 使用标准的 HTTP 状态码（200, 201, 400, 404, 500 等）。
- 成功的响应格式：{ "data": [...] }。
- 失败的响应格式：{ "error": "description of error" }。
数据库交互:
- 使用 PyMongo 与 MongoDB 交互。
- 数据库连接应在应用启动时初始化一次，并复用该连接。
- 将数据库操作封装在独立的模块或服务层中，不要在路由函数中直接编写复杂的数据库查询。
依赖管理:
- 任何新增的依赖包，都必须通过 pip install <package_name> 安装后，立即更新 requirements.txt 文件：
  bash 复制代码
```
pip freeze > requirements.txt
```

构建与部署

部署流程是将前后端整合，并以生产模式运行。

步骤 1: 构建前端应用

进入 frontend 目录。
执行构建命令。

bash 复制代码

cd my-project/frontend
pnpm run build

此命令会在 frontend/dist 目录下生成优化后的静态文件（HTML, CSS, JS）。

步骤 2: 运行后端服务 (生产模式)

在生产环境中，不应使用 flask run。应使用生产级的 WSGI 服务器，如 Gunicorn (适用于 Linux/macOS) 或 Waitress (跨平台)。

安装 Gunicorn:

bash 复制代码

# 确保后端虚拟环境已激活
pip install gunicorn
pip freeze > requirements.txt # 更新依赖

启动应用:
1. 进入 backend 目录。
2. 使用 Gunicorn 启动 Flask 应用。app:app 指的是 app.py 文件中的 app 实例。
  bash 复制代码
```
# 确保虚拟环境已激活
cd my-project/backend

# -w 4 表示启动 4 个工作进程
gunicorn --workers 4 --bind 0.0.0.0:5000 app:app
```
3. 此时，Flask 不仅会提供 /api 路由，还会根据 app.py 中的配置，将所有其他请求指向 frontend/dist 目录，从而服务于构建好的 React 应用。用户访问服务器的根地址即可看到前端页面。

提示词

这是一个精简版的、适合用作提示词（Prompt）的前后端开发规范

markdown 复制代码

### **前后端开发规范 Prompt (React + Flask + MongoDB)**

#### **1. 核心技术栈 (Core Stack)**
- **前端**: React (Vite + TypeScript)
- **后端**: Flask (Python 3.11+)
- **数据库**: MongoDB
- **包管理器**: pnpm (前端), pip (后端)

#### **2. 项目结构 (Project Structure)**
my-project/
├── backend/        # Flask 后端
│   ├── .venv/      # Python 虚拟环境
│   ├── app.py      # Flask 应用主文件
│   ├── .env        # 环境变量
│   └── requirements.txt
└── frontend/       # React 前端
    ├── src/
    └── pnpm-lock.yaml

#### **3. 前端规范 (Frontend Spec)**
- **目录结构 (`src/`)**:
  - `components/`: 可复用 UI 组件。
  - `pages/`: 页面级组件。
  - `hooks/`: 自定义 Hooks。
  - `services/` 或 `api/`: API 请求逻辑封装。
  - `store/`: 全局状态管理 (Zustand)。
  - `utils/`: 工具函数。
- **组件**: 必须使用函数式组件和 Hooks。
- **状态管理**: 简单状态使用 `useState` / `useContext`；全局或复杂状态使用 `Zustand`。
- **API 请求**: 使用 `axios`，创建统一实例，配置 `baseURL`、请求头和错误处理。

#### **4. 后端规范 (Backend Spec)**
- **结构**: 中大型项目使用 `Blueprints` 组织路由。
- **配置**: 严禁硬编码敏感信息。所有配置项（如 `MONGO_URI` / `FRONTEND_URLS`）通过 `.env` 文件和环境变量加载。
- **数据库**:
  - 使用 `PyMongo`。
  - 应用启动时创建单例数据库连接并复用。
  - 数据库操作封装在独立的服务层，避免在路由函数中直接编写复杂查询。
- **依赖管理**:
  - 必须使用 Python 虚拟环境 (`.venv`)。
  - 新增依赖后，必须立即更新 `requirements.txt` (`pip freeze > requirements.txt`)。

#### **5. API 设计规范 (API Design Spec)**
- **原则**: 遵循 RESTful 设计风格。
- **路由**: 所有 API 路由必须以 `/api` 为前缀。
- **数据格式**: 请求和响应主体统一使用 `JSON` 格式。
- **HTTP 状态码**: 严格遵循标准 HTTP 状态码 (如 200, 201, 400, 404, 500)。
- **响应结构**:
  - **成功**: `{ "data": <payload> }`
  - **失败**: `{ "error": "Error description" }`

#### **6. 构建与部署 (Build & Deployment)**
- **前端构建**: 构建后的静态文件输出到 `frontend/dist` 目录。
- **生产环境**:
  - 后端必须使用生产级 WSGI 服务器 (如 `Gunicorn`) 运行，禁止使用 `flask run`。
  - 后端服务同时负责提供 API (`/api/*`) 和托管前端静态资源 (从 `frontend/dist` 目录)。