好的，我们直接切入主题，为你提供一份从零开始的Python后端开发环境部署与项目初始化配置的详细指南。 #### **第一阶段：基础环境与项目结构搭建** 首先，你需要建立一个规范的项目目录结构和隔离的开发环境。这可以确保你的项目依赖清晰，且不影响系统全局Python环境。 1. **创建项目根目录** 在你的工作区（如桌面或`Projects`文件夹）下，创建一个名为`HarmonyStudyRoom_Server`的文件夹。这是你后端的根目录。 ```bash mkdir HarmonyStudyRoom_Server cd HarmonyStudyRoom_Server ``` 2. **安装并配置 `uv` 包管理工具** 使用 `uv` 能极大提升Python项目的依赖管理和虚拟环境创建效率[ref_3]。在命令行中执行以下命令来安装它： **对于Windows (PowerShell)：** ```powershell powershell -c "irm https://astral.sh/uv/install.ps1 | iex" ``` **对于macOS/Linux：** ```bash curl -LsSf https://astral.sh/uv/install.sh | sh ``` 安装后，重新启动你的命令行终端以确保`uv`命令生效。运行 `uv --version` 验证安装成功[ref_3]。 3. **初始化Python项目** 使用 `uv` 来初始化项目。这会为你创建 `pyproject.toml` 配置文件，它是现代Python项目的核心管理文件[ref_3]。 ```bash uv init ``` 按提示操作后，你的目录下会生成 `pyproject.toml` 文件。你需要手动编辑它，加入项目的基本信息和依赖。用记事本或VSCode等编辑器打开它，内容参考如下： ```toml [project] name = "studyroom-backend" version = "0.1.0" description = "Harmony Shared Study Room Platform Backend" readme = "README.md" requires-python = ">=3.10" dependencies = [ "flask>=3.0.0", "flask-cors", "flask-sqlalchemy", "pymysql", "python-dotenv", ] [build-system] requires = ["hatchling"] build-backend = "hatchling.build" ``` 这里我们选用了轻量级的Flask作为Web框架，并引入了CORS支持、数据库ORM和MySQL驱动等基础依赖[ref_5][ref_6]。 4. **同步依赖并激活虚拟环境** 使用 `uv sync` 命令，`uv` 会根据 `pyproject.toml` 自动创建虚拟环境并安装所有依赖[ref_3]。 ```bash uv sync ``` 安装完成后，你可以激活虚拟环境： ```bash # 在Windows上： .venv\Scripts\activate # 在macOS/Linux上： source .venv/bin/activate ``` 激活后，命令行提示符通常会显示 `(.venv)` 前缀，表示你已进入隔离的项目环境。 #### **第二阶段：基础应用与数据库配置** 现在，我们来编写最基础的Flask应用并配置数据库连接。 1. **创建应用入口文件** 在项目根目录下创建 `app.py`，这是我们的主要应用文件[ref_5]。 ```python from flask import Flask, jsonify from flask_cors import CORS import os from dotenv import load_dotenv # 加载环境变量 load_dotenv() # 创建Flask应用实例 app = Flask(__name__) # 从环境变量读取配置，如数据库URL，提供默认值用于开发 app.config['SECRET_KEY'] = os.getenv('SECRET_KEY', 'your-secret-key-here') app.config['SQLALCHEMY_DATABASE_URI'] = os.getenv('DATABASE_URL', 'mysql+pymysql://root:password@localhost:3306/studyroom_db') app.config['SQLALCHEMY_TRACK_MODIFICATIONS'] = False # 启用跨域支持，方便前端（Vue3/HarmonyOS）调用 CORS(app) # 定义数据库模型（示例） from flask_sqlalchemy import SQLAlchemy db = SQLAlchemy(app) # 一个简单的模型示例：自习室 class StudyRoom(db.Model): __tablename__ = 'study_rooms' id = db.Column(db.Integer, primary_key=True) name = db.Column(db.String(100), nullable=False) address = db.Column(db.String(200)) total_seats = db.Column(db.Integer, default=50) # 一个最简单的测试路由 @app.route('/api/health', methods=['GET']) def health_check(): return jsonify({'status': 'ok', 'message': 'Study Room Backend is running!'}) # 主程序入口 if __name__ == '__main__': # 首次运行时可以取消注释下一行，在app上下文内创建所有数据表 # with app.app_context(): # db.create_all() app.run(debug=True, host='0.0.0.0', port=5000) ``` 2. **创建环境变量配置文件** 为了安全地管理数据库密码等敏感信息，我们使用 `.env` 文件。在根目录创建 `.env` 文件，内容如下： ```ini # .env 文件 SECRET_KEY=your-super-secret-production-key-change-this # 数据库连接字符串，请根据你的MySQL安装情况修改 DATABASE_URL=mysql+pymysql://root:yourpassword@localhost:3306/studyroom_db ``` **注意**：你需要先安装MySQL数据库并创建名为 `studyroom_db` 的数据库[ref_4]。如果尚未安装，可以考虑先使用更轻量的SQLite，将 `DATABASE_URL` 改为 `sqlite:///studyroom.db`。 3. **创建项目结构文件** 为了让项目更易于维护，我们将创建一些标准文件和目录。在根目录下执行： ```bash mkdir -p models routers utils static templates type nul > README.md (Windows) 或 touch README.md (macOS/Linux) type nul > requirements.txt (Windows) 或 touch requirements.txt (macOS/Linux) ``` * `models/`: 用于存放所有数据模型（如 `User`, `Seat`, `Order`）。 * `routers/`: 用于存放API路由文件，将不同模块（用户、自习室、订单）的路由分离。 * `utils/`: 存放工具函数。 * `static/` & `templates/`: Flask用于存放静态文件和模板，我们采用前后端分离，暂时用不到。 * `README.md`: 项目说明文档。 * `requirements.txt`: 你可以通过 `uv pip freeze > requirements.txt` 命令生成此文件，用于记录精确的依赖版本[ref_5]。 #### **第三阶段：关键模块化与API设计** 现在，我们以**自习室模块**为例，展示如何模块化设计。 1. **创建自习室数据模型** 在 `models/` 目录下创建 `studyroom_model.py`，定义更详细的自习室和座位模型： ```python # models/studyroom_model.py from app import db from datetime import datetime class StudyRoom(db.Model): __tablename__ = 'study_rooms' id = db.Column(db.Integer, primary_key=True) name = db.Column(db.String(100), nullable=False) description = db.Column(db.Text) address = db.Column(db.String(200)) latitude = db.Column(db.Float) # 纬度，用于地图或距离计算 longitude = db.Column(db.Float) # 经度 total_seats = db.Column(db.Integer, default=0) is_active = db.Column(db.Boolean, default=True) created_at = db.Column(db.DateTime, default=datetime.utcnow) # 定义与座位的关联关系 seats = db.relationship('Seat', backref='room', lazy='dynamic', cascade='all, delete-orphan') class Seat(db.Model): __tablename__ = 'seats' id = db.Column(db.Integer, primary_key=True) room_id = db.Column(db.Integer, db.ForeignKey('study_rooms.id'), nullable=False) seat_number = db.Column(db.String(10), nullable=False) # 如 “A01” status = db.Column(db.String(20), default='available') # 'available', 'booked', 'maintenance' x_pos = db.Column(db.Integer) # 在可视化平面图上的X坐标 y_pos = db.Column(db.Integer) # 在可视化平面图上的Y坐标 ``` 2. **创建自习室API路由** 在 `routers/` 目录下创建 `studyroom_router.py`，定义相关的CRUD API： ```python # routers/studyroom_router.py from flask import Blueprint, request, jsonify from models.studyroom_model import StudyRoom, Seat, db from sqlalchemy.exc import SQLAlchemyError # 创建蓝图，用于模块化路由管理 studyroom_bp = Blueprint('studyroom', __name__, url_prefix='/api/studyrooms') # 1. 获取所有自习室列表 @studyroom_bp.route('/', methods=['GET']) def get_studyrooms(): try: rooms = StudyRoom.query.filter_by(is_active=True).all() result = [{ 'id': room.id, 'name': room.name, 'address': room.address, 'totalSeats': room.total_seats, 'availableSeats': Seat.query.filter_by(room_id=room.id, status='available').count() } for room in rooms] return jsonify({'code': 200, 'message': 'success', 'data': result}) except SQLAlchemyError as e: return jsonify({'code': 500, 'message': f'Database error: {str(e)}', 'data': None}), 500 # 2. 获取某个自习室的详细信息和座位状态 @studyroom_bp.route('/<int:room_id>', methods=['GET']) def get_studyroom_detail(room_id): room = StudyRoom.query.get_or_404(room_id) seats = Seat.query.filter_by(room_id=room_id).all() seat_list = [{ 'id': s.id, 'seatNumber': s.seat_number, 'status': s.status, 'x': s.x_pos, 'y': s.y_pos } for s in seats] room_info = { 'id': room.id, 'name': room.name, 'description': room.description, 'address': room.address, 'seats': seat_list } return jsonify({'code': 200, 'message': 'success', 'data': room_info}) # 3. 管理员创建自习室 (示例，可扩展) @studyroom_bp.route('/', methods=['POST']) def create_studyroom(): data = request.get_json() if not data or not data.get('name'): return jsonify({'code': 400, 'message': 'Missing required field: name', 'data': None}), 400 new_room = StudyRoom( name=data['name'], address=data.get('address', ''), total_seats=data.get('total_seats', 0) ) db.session.add(new_room) try: db.session.commit() return jsonify({'code': 201, 'message': 'Study room created', 'data': {'id': new_room.id}}), 201 except SQLAlchemyError as e: db.session.rollback() return jsonify({'code': 500, 'message': f'Failed to create: {str(e)}', 'data': None}), 500 ``` 3. **重构主应用文件** 修改 `app.py`，导入并使用我们创建的蓝图，并初始化数据库。 ```python # app.py from flask import Flask, jsonify from flask_cors import CORS from flask_sqlalchemy import SQLAlchemy import os from dotenv import load_dotenv # 加载环境变量 load_dotenv() app = Flask(__name__) app.config.from_mapping( SECRET_KEY=os.getenv('SECRET_KEY'), SQLALCHEMY_DATABASE_URI=os.getenv('DATABASE_URL'), SQLALCHEMY_TRACK_MODIFICATIONS=False ) CORS(app) db = SQLAlchemy(app) # 导入并注册蓝图 from routers.studyroom_router import studyroom_bp app.register_blueprint(studyroom_bp) # 健康检查路由 @app.route('/api/health', methods=['GET']) def health_check(): return jsonify({'status': 'ok', 'message': 'Study Room Backend is running!'}) # 初始化数据库（谨慎使用，仅用于首次创建表） @app.cli.command('init-db') def init_db_command(): """清空现有数据并创建所有表（开发环境使用）""" with app.app_context(): db.drop_all() db.create_all() print('Initialized the database.') if __name__ == '__main__': # 开发环境运行 app.run(debug=True, host='0.0.0.0', port=5000) ``` #### **第四阶段：运行与测试** 1. **初始化数据库** 确保你的MySQL服务已启动并创建好数据库（或使用SQLite）。然后在项目根目录下执行： ```bash # 确保虚拟环境已激活 (.venv\Scripts\activate 或 source .venv/bin/activate) flask --app app init-db ``` 此命令会调用我们定义的`init-db`命令，创建数据表。 2. **启动后端服务器** ```bash python app.py ``` 如果一切正常，终端会输出 `* Running on http://0.0.0.0:5000`。这表明你的Python后端服务已经启动。 3. **测试API** 打开浏览器或使用Postman等API测试工具，访问以下地址： * `http://127.0.0.1:5000/api/health` - 应该返回 `{"status":"ok",...}`。 * `http://127.0.0.1:5000/api/studyrooms/` - 初次访问会返回空数组 `[]`，这是正常的，因为数据库里还没有数据。 #### **后续步骤** 至此，你的Python后端开发环境已成功部署，并完成了一个模块化的、可运行的Flask RESTful API骨架。接下来的工作可以按照之前规划的阶段进行： * **完善其他模型与API**：参照 `studyroom_router.py`，在 `models/` 和 `routers/` 下创建 `user_model.py`、`user_router.py`、`order_model.py`、`order_router.py`，实现用户系统和预约系统[ref_5]。 * **前后端联调**：运行此后端，让Vue3管理端和HarmonyOS用户端通过 `http://127.0.0.1:5000/api/...` 地址调用这些API接口[ref_6]。 * **部署**：当开发完成后，可以参考相关资料，使用Docker容器化你的应用，或部署到云服务器[ref_1][ref_4]。