这类毕业设计项目最值得先看的不是功能列表而是能不能在普通开发环境里快速跑起来以及代码结构是否清晰到能让导师和答辩评委一眼看懂。一个基于 FastAPI Vue3 的通讯录管理系统核心价值在于它完整覆盖了前后端分离、RESTful API、数据库操作和基础权限管理这些现代 Web 开发的典型环节非常适合计算机相关专业的学生用来展示自己的工程能力。很多人拿到源码后第一步就卡在环境配置和依赖安装上或者前端后端各自跑起来却连不上。我更建议把第一次运行拆成三步先确保后端 API 能独立响应再让前端能独立运行最后解决跨域让两者通信。下面我会按这个实际落地的顺序把环境、配置、关键代码和常见坑点都拆解一遍。1. 先理清技术栈和项目结构别急着运行拿到一个“FastAPI Vue3”的毕业设计源码第一步不是直接python main.py或npm run dev。先花几分钟看目录结构这能帮你快速定位核心文件和配置避免后续一堆“模块找不到”的错误。1.1 典型项目结构解析一个结构清晰的毕业设计项目通常会分成backend后端和frontend前端两个主目录。如果源码是打包在一起的你需要先手动分开。后端 (FastAPI) 目录结构通常如下backend/ ├── main.py # FastAPI 应用入口定义路由和启动 ├── requirements.txt # Python 依赖包列表 ├── models.py # 数据库模型定义如果用 SQLAlchemy ├── schemas.py # Pydantic 模型用于请求/响应数据验证 ├── crud.py # 数据库增删改查操作函数 ├── database.py # 数据库连接配置 ├── routers/ # 路由模块按功能拆分 │ ├── contacts.py # 通讯录相关API路由 │ └── users.py # 用户认证相关路由 └── static/ # 静态文件可选前端 (Vue3) 目录结构通常如下frontend/ ├── package.json # 项目依赖和脚本 ├── vite.config.js # Vite 构建配置重点看代理设置 ├── public/ ├── src/ │ ├── main.js # Vue 应用入口 │ ├── App.vue # 根组件 │ ├── router/index.js # 前端路由配置 │ ├── views/ # 页面组件如 ContactList.vue │ ├── components/ # 可复用组件如 ContactForm.vue │ ├── api/ # 封装后端 API 请求如 contact.js │ └── stores/ # 状态管理如用 Pinia关键检查点确认requirements.txt和package.json存在这是安装依赖的蓝图。找到数据库配置在backend/database.py或main.py里看连接的是 SQLite、MySQL 还是 PostgreSQL。毕业设计为了简便大概率用的是 SQLite。看前端代理配置打开frontend/vite.config.js找server.proxy配置。它决定了开发时前端请求如何转发到后端是解决跨域问题的关键。1.2 环境准备清单在运行代码前你需要准备好以下环境。不要一次性安装所有东西按顺序来。环境/工具作用检查命令/备注Python 3.8运行 FastAPI 后端python --versionNode.js 16运行 Vue3 前端和包管理node --versionpip安装 Python 包pip --version虚拟环境 (venv)隔离 Python 项目依赖推荐使用避免包冲突代码编辑器如 VS Code确保安装了 Python、Vue 相关插件数据库 (可选)如 SQLite内置、MySQL根据项目配置准备注意很多“环境跑不起来”的问题根源是 Python 或 Node.js 版本不对。FastAPI 通常需要 Python 3.7Vue3 的构建工具 Vite 需要 Node.js 14.18推荐 16。先用上面的命令确认版本。2. 从后端开始让 FastAPI 先独立跑起来后端是数据核心先确保 API 能独立工作再让前端去连接。这样出问题时你能快速定位是后端逻辑错误还是前端连接问题。2.1 安装 Python 依赖与启动进入backend目录按顺序操作# 1. 创建并激活 Python 虚拟环境Windows python -m venv venv venv\Scripts\activate # 1. 创建并激活 Python 虚拟环境macOS/Linux python3 -m venv venv source venv/bin/activate # 2. 安装依赖确保在虚拟环境下 pip install -r requirements.txtrequirements.txt里通常会有这些核心包fastapi uvicorn[standard] # ASGI 服务器用于运行 FastAPI sqlalchemy # ORM 工具 pydantic # 数据验证 python-jose[cryptography] # JWT 令牌如果包含登录 passlib[bcrypt] # 密码哈希如果源码没有提供requirements.txt你可以根据import语句手动安装这些包。启动后端服务# 通常启动命令在 main.py 中使用 uvicorn uvicorn main:app --reload --host 0.0.0.0 --port 8000main:appmain是文件名不含.pyapp是 FastAPI 应用实例名。--reload代码修改后自动重启开发时非常有用。--host 0.0.0.0允许其他设备如前端访问。--port 8000指定端口默认为 8000。成功标志终端显示Uvicorn running on http://0.0.0.0:8000并且没有红色错误日志。2.2 验证 API 与数据库服务启动后立即做两件事访问自动 API 文档打开浏览器访问http://localhost:8000/docs。这是 FastAPI 自动生成的交互式文档Swagger UI。你应该能看到/contacts、/users等接口列表。这是验证路由是否正常定义的最快方法。测试一个基础接口在docs页面找到GET /contacts或类似的接口点击 “Try it out”然后 “Execute”。观察响应。如果返回 200 和空数组[]成功说明数据库连接和路由正常只是没数据。如果返回 500 内部错误查看终端日志。最常见的原因是数据库文件路径不对或表不存在。数据库初始化问题排查很多毕业设计项目不会自动建表。你需要检查代码里是否有初始化数据库的脚本或函数。通常在database.py或main.py中会有这样的代码# 在 database.py 中 from sqlalchemy import create_engine from sqlalchemy.ext.declarative import declarative_base from sqlalchemy.orm import sessionmaker SQLALCHEMY_DATABASE_URL sqlite:///./contacts.db # 数据库文件路径 engine create_engine(SQLALCHEMY_DATABASE_URL, connect_args{check_same_thread: False}) SessionLocal sessionmaker(autocommitFalse, autoflushFalse, bindengine) Base declarative_base() # 在 main.py 或单独脚本中 from database import engine, Base from models import Contact, User # 导入所有模型 def create_tables(): Base.metadata.create_all(bindengine) if __name__ __main__: create_tables() # ... 然后启动 uvicorn如果项目没有自动建表逻辑你需要手动运行一次建表函数或者在首次启动前确保这段代码被执行。2.3 理解核心代码模型、路由与 CRUD要让这个毕业设计成为你自己的项目必须看懂几个核心文件models.py(数据表结构)from sqlalchemy import Column, Integer, String from database import Base class Contact(Base): __tablename__ contacts id Column(Integer, primary_keyTrue, indexTrue) name Column(String, indexTrue) phone Column(String, uniqueTrue, indexTrue) email Column(String, uniqueTrue, indexTrue) address Column(String)这定义了数据库里contacts表的结构。Column定义了字段类型和属性如是否唯一、建立索引。schemas.py(数据验证与序列化)from pydantic import BaseModel, EmailStr from typing import Optional class ContactBase(BaseModel): name: str phone: str email: EmailStr address: Optional[str] None class ContactCreate(ContactBase): pass # 创建联系人时的数据模型 class Contact(ContactBase): id: int class Config: orm_mode True # 允许从 ORM 对象如 Contact 模型实例读取数据Pydantic 模型确保了前端传过来的数据格式正确如email必须是邮箱格式并且在返回数据时orm_modeTrue允许 FastAPI 直接将数据库查询结果转换成 JSON。crud.py(数据库操作)from sqlalchemy.orm import Session from models import Contact from schemas import ContactCreate def get_contacts(db: Session, skip: int 0, limit: int 100): return db.query(Contact).offset(skip).limit(limit).all() def create_contact(db: Session, contact: ContactCreate): db_contact Contact(**contact.dict()) # 将 Pydantic 对象转为字典再创建模型实例 db.add(db_contact) db.commit() db.refresh(db_contact) return db_contact这里封装了具体的数据库查询和操作。db: Session是数据库会话由依赖项注入。routers/contacts.py(API 路由)from fastapi import APIRouter, Depends, HTTPException from sqlalchemy.orm import Session from typing import List from database import get_db from schemas import Contact, ContactCreate import crud router APIRouter(prefix/contacts, tags[contacts]) router.get(/, response_modelList[Contact]) def read_contacts(skip: int 0, limit: int 100, db: Session Depends(get_db)): contacts crud.get_contacts(db, skipskip, limitlimit) return contacts router.post(/, response_modelContact) def create_contact(contact: ContactCreate, db: Session Depends(get_db)): return crud.create_contact(dbdb, contactcontact)这是 API 的入口。APIRouter组织路由Depends(get_db)为每个请求提供独立的数据库会话response_model确保返回的数据符合Contact模式并自动转换为 JSON。看懂这四部分的协作关系模型定义表 - Pydantic 验证数据 - CRUD 操作数据库 - 路由暴露接口你就掌握了这个后端项目的骨架。3. 再跑前端配置 Vue3 开发环境与代理后端 API 在http://localhost:8000跑通后我们转向前端。前端的主要任务是配置开发服务器并正确代理 API 请求以解决浏览器跨域限制。3.1 安装依赖与启动开发服务器进入frontend目录# 安装项目依赖使用 npm 或 yarn npm install # 或 yarn install # 启动开发服务器 npm run dev # 或 yarn dev成功启动后终端会输出本地访问地址通常是http://localhost:5173Vite 默认端口。常见问题npm install失败/极慢可以尝试切换为国内镜像源如使用npm config set registry https://registry.npmmirror.com。端口冲突如果 5173 端口被占用Vite 会提示并尝试使用其他端口注意看终端输出。依赖版本冲突如果package-lock.json或yarn.lock存在尽量使用它们来保证安装一致性。删除node_modules和 lock 文件后重装是解决依赖问题的常见方法。3.2 配置 API 请求代理解决跨域这是前后端联调最关键的一步。在开发阶段前端运行在localhost:5173后端在localhost:8000浏览器出于安全考虑会阻止这种跨域请求。解决方案是在vite.config.js中配置代理让前端开发服务器将特定请求转发到后端。打开frontend/vite.config.js添加或修改server.proxy配置import { defineConfig } from vite import vue from vitejs/plugin-vue export default defineConfig({ plugins: [vue()], server: { proxy: { // 将 /api 开头的请求代理到后端服务器 /api: { target: http://localhost:8000, // 你的后端地址 changeOrigin: true, rewrite: (path) path.replace(/^\/api/, ) // 重写路径去掉 /api 前缀 } } } })配置解释target你的 FastAPI 后端地址。changeOrigin修改请求头中的Origin为目标地址对于某些后端是必须的。rewrite重写请求路径。这里的意思是前端请求/api/contacts代理会将其转换为http://localhost:8000/contacts。如果你的后端 API 本身就有/api前缀则不需要rewrite。在前端代码中发起请求配置好代理后前端代码中请求 API 就应该使用相对路径指向代理服务器而不是绝对的后端地址。// 在 src/api/contact.js 或类似文件中 import axios from axios; const apiClient axios.create({ baseURL: /api, // 注意这里使用 /api 前缀会被 vite 代理转发 headers: { Content-Type: application/json, }, }); export default { getContacts() { return apiClient.get(/contacts); // 实际请求/api/contacts - 代理 - http://localhost:8000/contacts }, createContact(contactData) { return apiClient.post(/contacts, contactData); }, }验证代理是否生效确保后端 (:8000) 和前端 (:5173) 服务都在运行。在前端页面如联系人列表页触发一个数据请求如页面加载。打开浏览器开发者工具F12进入Network网络标签页。查看发出的请求 URL它应该是http://localhost:5173/api/contacts并且状态码为 200响应数据正确。同时在后端服务的终端日志里你应该能看到对应的请求记录如GET /contacts。如果 Network 中请求失败如 404 或 500检查1) 代理配置路径是否正确2) 后端对应路由是否存在3) 后端服务是否真的在运行。3.3 理解 Vue3 组件与状态管理前端代码的核心是组件和状态管理。以通讯录列表页为例src/views/ContactList.vue(页面组件)template div h1通讯录/h1 button clickfetchContacts刷新/button ul li v-forcontact in contacts :keycontact.id {{ contact.name }} - {{ contact.phone }} /li /ul /div /template script setup import { ref, onMounted } from vue; import contactApi from /api/contact; // 导入封装好的 API 模块 const contacts ref([]); // 使用 ref 创建响应式数据 const fetchContacts async () { try { const response await contactApi.getContacts(); contacts.value response.data; // 将数据赋值给响应式变量 } catch (error) { console.error(获取联系人失败:, error); } }; // 页面加载时自动获取数据 onMounted(() { fetchContacts(); }); /scriptscript setupVue3 的组合式 API 语法更简洁。ref用于创建响应式的基本类型或对象引用。onMounted生命周期钩子在组件挂载后执行适合初始化数据。clickVue 的事件监听语法。状态管理 (Pinia)如果项目复杂可能会用到 PiniaVuex 的替代品来管理全局状态比如用户登录信息。src/stores/user.jsimport { defineStore } from pinia import { ref, computed } from vue export const useUserStore defineStore(user, () { const token ref(localStorage.getItem(token) || ) const isLoggedIn computed(() !!token.value) function setToken(newToken) { token.value newToken localStorage.setItem(token, newToken) } return { token, isLoggedIn, setToken } })在组件中使用script setup import { useUserStore } from /stores/user const userStore useUserStore() // 访问 userStore.token, userStore.isLoggedIn // 调用 userStore.setToken(xxx) /script4. 前后端联调与功能测试前后端各自独立运行且代理配置正确后就可以开始测试完整的增删改查功能了。4.1 基础功能测试流程按照“增 - 查 - 改 - 删”的顺序进行测试每一步都观察前端界面、浏览器 Network 请求和后端日志。新增联系人在前端表单填写姓名、电话、邮箱点击提交。前端检查表单数据是否正常收集请求是否成功发出Network 看 POST 请求。后端终端日志应显示POST /contacts200 或 201。检查数据库是否新增了记录。验证提交后列表是否自动刷新或出现新条目。查询联系人列表进入列表页或刷新页面。前端检查GET /api/contacts请求是否成功数据是否正确渲染。后端日志显示GET /contacts。验证列表是否完整显示所有联系人包括刚新增的。查看/编辑联系人详情点击某条联系人进入详情或编辑页。前端通常会发起一个GET /api/contacts/{id}请求来获取单条数据。后端日志对应GET /contacts/{id}。验证表单是否预填充了正确数据。更新联系人在编辑页修改信息后保存。前端检查PUT /api/contacts/{id}或PATCH请求请求体是否包含修改后的数据。后端日志对应PUT /contacts/{id}200。验证返回列表页该联系人的信息是否已更新。删除联系人点击某条记录的删除按钮。前端通常有确认对话框然后发起DELETE /api/contacts/{id}请求。后端日志对应DELETE /contacts/{id}200 或 204。验证列表页中该联系人是否消失。4.2 联调常见问题与排查即使前后端单独运行正常联调时也可能遇到问题。按以下顺序排查现象可能原因排查步骤前端页面空白或 JS 错误1. 依赖未正确安装2. Node.js 版本过低3. 组件引入路径错误1. 检查浏览器控制台 (Console) 错误信息。2. 删除node_modules和package-lock.json重装依赖。3. 确认/别名在vite.config.js中正确配置。网络请求报 4041. 代理配置错误2. 后端路由不存在3. 请求 URL 拼写错误1. 在浏览器 Network 中查看请求的完整 URL是否指向了localhost:5173/api/...。2. 对比后端main.py或路由文件中的实际路由路径。3. 检查vite.config.js中的target和rewrite规则。网络请求报 500后端服务器内部错误1.首要动作查看后端服务终端输出的错误日志这是最直接的线索。2. 常见原因数据库连接失败、SQL 语法错误、数据验证失败Pydantic 报错、代码逻辑异常。跨域错误 (CORS)代理未生效或配置错误请求直接发往后端1. 确认请求是从localhost:5173发出的而不是localhost:8000。2. 确认vite.config.js中的代理配置已保存且前端服务器已重启。3. 作为备选方案可以在 FastAPI 后端添加 CORS 中间件但开发阶段用代理是更佳实践。数据不显示或显示错误1. 前端组件数据绑定错误2. API 返回的数据结构不符合预期1. 在浏览器 Network 中查看 API 响应体确认数据是否正确。2. 在前端代码中检查console.log打印的响应数据。3. 检查 Vue 模板中v-for循环和数据显示的字段名是否与 API 返回的 JSON 键名匹配。表单提交无效1. 前端未发送请求2. 请求数据格式错误3. 后端验证失败1. 打开浏览器 Network提交时观察是否有请求发出。2. 检查请求的Content-Type是否为application/json。3. 查看请求体 (Payload)数据格式是否与后端 Pydantic 模型 (ContactCreate) 匹配。关键习惯永远先看日志。后端错误看服务终端前端错误看浏览器控制台 (Console) 和网络请求 (Network)。日志里的错误信息能直接定位 80% 的问题。5. 项目扩展与毕业设计答辩要点一个能运行的 Demo 只是开始。要让它在毕业设计中拿高分你需要展示出对项目的深入理解和扩展能力。5.1 功能扩展建议在基础增删改查上添加 1-2 个亮点功能能极大提升项目完整度。用户认证与授权 (JWT)做什么实现用户注册、登录、退出。不同用户只能管理自己的通讯录。后端新增User模型和auth路由。使用python-jose生成和验证 JWT 令牌。在contacts路由中添加依赖项检查请求头中的Authorization令牌并关联用户与联系人。前端添加登录/注册页面。使用 Pinia 或 localStorage 存储 token。在axios拦截器中为每个请求自动添加Authorization头。联系人搜索与筛选做什么在列表页顶部增加搜索框可按姓名、电话模糊搜索。后端修改GET /contacts接口接收q查询参数。在 CRUD 函数中使用 SQLAlchemy 的filter和ilike进行数据库查询。前端在搜索框绑定输入事件使用watch或防抖函数 (lodash.debounce) 触发 API 请求更新列表。数据导出 (CSV/Excel)做什么提供一个按钮将当前通讯录导出为文件。后端新增一个GET /contacts/export接口。使用csv或pandas库将查询结果生成 CSV 字符串通过Response返回并设置合适的响应头 (Content-Disposition: attachment)。前端调用导出接口利用a标签的download属性或Blob对象触发浏览器下载。后端分页做什么联系人数量多时列表分页显示。后端GET /contacts接口已包含skip和limit参数在 CRUD 中配合offset()和limit()实现。在响应中同时返回总条数方便前端计算总页数。前端使用分页组件如 Element Plus 的Pagination根据总条数和每页大小计算页码点击页码时传递skip参数。5.2 代码质量与部署考量代码结构清晰确保你的项目像第一部分描述的那样前后端分离模块职责分明。这是答辩时老师会重点看的。添加注释在关键函数、复杂逻辑处添加中文注释说明功能。在README.md中写清项目简介、技术栈、运行步骤。错误处理不要只是print错误。前端应有用户友好的错误提示如使用ElMessage后端 API 应返回结构化的错误信息而不是赤裸的 500 页面。环境变量配置将数据库连接字符串、JWT 密钥等敏感信息从代码中抽离放入.env文件使用python-dotenv读取。这体现了工程化意识。简单部署演示后端可以使用docker build打包一个简单的 Docker 镜像或者演示如何用uvicorn main:app --host 0.0.0.0 --port 8000在生产模式去掉--reload下运行。前端运行npm run build生成静态文件演示如何用 Nginx 或直接放在后端静态目录 (app.mount(/, StaticFiles(directoryfrontend/dist), namestatic))进行部署。5.3 答辩准备要点答辩时老师关注的不只是功能更是你的思路、理解和解决问题的能力。讲清楚技术选型为什么用 FastAPI 而不是 Django 或 Flask为什么用 Vue3 而不是 React可以谈 FastAPI 的异步、自动文档、高性能Vue3 的组合式 API、响应式系统更友好。演示核心流程现场演示从启动后端、前端到完成一个完整的“新增-查询-编辑-删除”流程。确保流程顺畅。解释关键代码准备 2-3 处核心代码讲解。比如“这是后端的 Pydantic 模型它确保了数据的有效性这是前端的组合式 API用ref和onMounted管理数据和生命周期。”展示扩展功能重点演示你额外添加的功能如搜索、导出并解释实现原理。回答问题准备回答诸如“跨域怎么解决的”开发用代理生产可配 Nginx 或 CORS、“数据库选型为什么用 SQLite”轻量适合毕业设计演示、“如果用户量很大哪里可能成为瓶颈”数据库查询、分页、JWT 验证开销等。诚实面对不足如果被问到没实现的功能或已知的 bug可以坦诚说明并给出后续优化思路如“目前是内存存储 token后续可以引入 Redis”这比强行辩解更好。这个项目最实用的价值是提供了一个可运行、可理解、可扩展的现代 Web 应用骨架。把它跑起来只是第一步真正吃透代码并按照自己的思路进行改造和增强才是完成一个高质量毕业设计的关键。先从单机环境把整套流程打通再考虑如何优化代码结构、增加功能、准备答辩说辞每一步都踩实了最终展示时自然会有底气。
这类毕业设计项目最值得先看的不是功能列表而是能不能在普通开发环境里快速跑起来以及代码结构是否清晰到能让导师和答辩评委一眼看懂。一个基于 FastAPI Vue3 的通讯录管理系统核心价值在于它完整覆盖了前后端分离、RESTful API、数据库操作和基础权限管理这些现代 Web 开发的典型环节非常适合计算机相关专业的学生用来展示自己的工程能力。很多人拿到源码后第一步就卡在环境配置和依赖安装上或者前端后端各自跑起来却连不上。我更建议把第一次运行拆成三步先确保后端 API 能独立响应再让前端能独立运行最后解决跨域让两者通信。下面我会按这个实际落地的顺序把环境、配置、关键代码和常见坑点都拆解一遍。1. 先理清技术栈和项目结构别急着运行拿到一个“FastAPI Vue3”的毕业设计源码第一步不是直接python main.py或npm run dev。先花几分钟看目录结构这能帮你快速定位核心文件和配置避免后续一堆“模块找不到”的错误。1.1 典型项目结构解析一个结构清晰的毕业设计项目通常会分成backend后端和frontend前端两个主目录。如果源码是打包在一起的你需要先手动分开。后端 (FastAPI) 目录结构通常如下backend/ ├── main.py # FastAPI 应用入口定义路由和启动 ├── requirements.txt # Python 依赖包列表 ├── models.py # 数据库模型定义如果用 SQLAlchemy ├── schemas.py # Pydantic 模型用于请求/响应数据验证 ├── crud.py # 数据库增删改查操作函数 ├── database.py # 数据库连接配置 ├── routers/ # 路由模块按功能拆分 │ ├── contacts.py # 通讯录相关API路由 │ └── users.py # 用户认证相关路由 └── static/ # 静态文件可选前端 (Vue3) 目录结构通常如下frontend/ ├── package.json # 项目依赖和脚本 ├── vite.config.js # Vite 构建配置重点看代理设置 ├── public/ ├── src/ │ ├── main.js # Vue 应用入口 │ ├── App.vue # 根组件 │ ├── router/index.js # 前端路由配置 │ ├── views/ # 页面组件如 ContactList.vue │ ├── components/ # 可复用组件如 ContactForm.vue │ ├── api/ # 封装后端 API 请求如 contact.js │ └── stores/ # 状态管理如用 Pinia关键检查点确认requirements.txt和package.json存在这是安装依赖的蓝图。找到数据库配置在backend/database.py或main.py里看连接的是 SQLite、MySQL 还是 PostgreSQL。毕业设计为了简便大概率用的是 SQLite。看前端代理配置打开frontend/vite.config.js找server.proxy配置。它决定了开发时前端请求如何转发到后端是解决跨域问题的关键。1.2 环境准备清单在运行代码前你需要准备好以下环境。不要一次性安装所有东西按顺序来。环境/工具作用检查命令/备注Python 3.8运行 FastAPI 后端python --versionNode.js 16运行 Vue3 前端和包管理node --versionpip安装 Python 包pip --version虚拟环境 (venv)隔离 Python 项目依赖推荐使用避免包冲突代码编辑器如 VS Code确保安装了 Python、Vue 相关插件数据库 (可选)如 SQLite内置、MySQL根据项目配置准备注意很多“环境跑不起来”的问题根源是 Python 或 Node.js 版本不对。FastAPI 通常需要 Python 3.7Vue3 的构建工具 Vite 需要 Node.js 14.18推荐 16。先用上面的命令确认版本。2. 从后端开始让 FastAPI 先独立跑起来后端是数据核心先确保 API 能独立工作再让前端去连接。这样出问题时你能快速定位是后端逻辑错误还是前端连接问题。2.1 安装 Python 依赖与启动进入backend目录按顺序操作# 1. 创建并激活 Python 虚拟环境Windows python -m venv venv venv\Scripts\activate # 1. 创建并激活 Python 虚拟环境macOS/Linux python3 -m venv venv source venv/bin/activate # 2. 安装依赖确保在虚拟环境下 pip install -r requirements.txtrequirements.txt里通常会有这些核心包fastapi uvicorn[standard] # ASGI 服务器用于运行 FastAPI sqlalchemy # ORM 工具 pydantic # 数据验证 python-jose[cryptography] # JWT 令牌如果包含登录 passlib[bcrypt] # 密码哈希如果源码没有提供requirements.txt你可以根据import语句手动安装这些包。启动后端服务# 通常启动命令在 main.py 中使用 uvicorn uvicorn main:app --reload --host 0.0.0.0 --port 8000main:appmain是文件名不含.pyapp是 FastAPI 应用实例名。--reload代码修改后自动重启开发时非常有用。--host 0.0.0.0允许其他设备如前端访问。--port 8000指定端口默认为 8000。成功标志终端显示Uvicorn running on http://0.0.0.0:8000并且没有红色错误日志。2.2 验证 API 与数据库服务启动后立即做两件事访问自动 API 文档打开浏览器访问http://localhost:8000/docs。这是 FastAPI 自动生成的交互式文档Swagger UI。你应该能看到/contacts、/users等接口列表。这是验证路由是否正常定义的最快方法。测试一个基础接口在docs页面找到GET /contacts或类似的接口点击 “Try it out”然后 “Execute”。观察响应。如果返回 200 和空数组[]成功说明数据库连接和路由正常只是没数据。如果返回 500 内部错误查看终端日志。最常见的原因是数据库文件路径不对或表不存在。数据库初始化问题排查很多毕业设计项目不会自动建表。你需要检查代码里是否有初始化数据库的脚本或函数。通常在database.py或main.py中会有这样的代码# 在 database.py 中 from sqlalchemy import create_engine from sqlalchemy.ext.declarative import declarative_base from sqlalchemy.orm import sessionmaker SQLALCHEMY_DATABASE_URL sqlite:///./contacts.db # 数据库文件路径 engine create_engine(SQLALCHEMY_DATABASE_URL, connect_args{check_same_thread: False}) SessionLocal sessionmaker(autocommitFalse, autoflushFalse, bindengine) Base declarative_base() # 在 main.py 或单独脚本中 from database import engine, Base from models import Contact, User # 导入所有模型 def create_tables(): Base.metadata.create_all(bindengine) if __name__ __main__: create_tables() # ... 然后启动 uvicorn如果项目没有自动建表逻辑你需要手动运行一次建表函数或者在首次启动前确保这段代码被执行。2.3 理解核心代码模型、路由与 CRUD要让这个毕业设计成为你自己的项目必须看懂几个核心文件models.py(数据表结构)from sqlalchemy import Column, Integer, String from database import Base class Contact(Base): __tablename__ contacts id Column(Integer, primary_keyTrue, indexTrue) name Column(String, indexTrue) phone Column(String, uniqueTrue, indexTrue) email Column(String, uniqueTrue, indexTrue) address Column(String)这定义了数据库里contacts表的结构。Column定义了字段类型和属性如是否唯一、建立索引。schemas.py(数据验证与序列化)from pydantic import BaseModel, EmailStr from typing import Optional class ContactBase(BaseModel): name: str phone: str email: EmailStr address: Optional[str] None class ContactCreate(ContactBase): pass # 创建联系人时的数据模型 class Contact(ContactBase): id: int class Config: orm_mode True # 允许从 ORM 对象如 Contact 模型实例读取数据Pydantic 模型确保了前端传过来的数据格式正确如email必须是邮箱格式并且在返回数据时orm_modeTrue允许 FastAPI 直接将数据库查询结果转换成 JSON。crud.py(数据库操作)from sqlalchemy.orm import Session from models import Contact from schemas import ContactCreate def get_contacts(db: Session, skip: int 0, limit: int 100): return db.query(Contact).offset(skip).limit(limit).all() def create_contact(db: Session, contact: ContactCreate): db_contact Contact(**contact.dict()) # 将 Pydantic 对象转为字典再创建模型实例 db.add(db_contact) db.commit() db.refresh(db_contact) return db_contact这里封装了具体的数据库查询和操作。db: Session是数据库会话由依赖项注入。routers/contacts.py(API 路由)from fastapi import APIRouter, Depends, HTTPException from sqlalchemy.orm import Session from typing import List from database import get_db from schemas import Contact, ContactCreate import crud router APIRouter(prefix/contacts, tags[contacts]) router.get(/, response_modelList[Contact]) def read_contacts(skip: int 0, limit: int 100, db: Session Depends(get_db)): contacts crud.get_contacts(db, skipskip, limitlimit) return contacts router.post(/, response_modelContact) def create_contact(contact: ContactCreate, db: Session Depends(get_db)): return crud.create_contact(dbdb, contactcontact)这是 API 的入口。APIRouter组织路由Depends(get_db)为每个请求提供独立的数据库会话response_model确保返回的数据符合Contact模式并自动转换为 JSON。看懂这四部分的协作关系模型定义表 - Pydantic 验证数据 - CRUD 操作数据库 - 路由暴露接口你就掌握了这个后端项目的骨架。3. 再跑前端配置 Vue3 开发环境与代理后端 API 在http://localhost:8000跑通后我们转向前端。前端的主要任务是配置开发服务器并正确代理 API 请求以解决浏览器跨域限制。3.1 安装依赖与启动开发服务器进入frontend目录# 安装项目依赖使用 npm 或 yarn npm install # 或 yarn install # 启动开发服务器 npm run dev # 或 yarn dev成功启动后终端会输出本地访问地址通常是http://localhost:5173Vite 默认端口。常见问题npm install失败/极慢可以尝试切换为国内镜像源如使用npm config set registry https://registry.npmmirror.com。端口冲突如果 5173 端口被占用Vite 会提示并尝试使用其他端口注意看终端输出。依赖版本冲突如果package-lock.json或yarn.lock存在尽量使用它们来保证安装一致性。删除node_modules和 lock 文件后重装是解决依赖问题的常见方法。3.2 配置 API 请求代理解决跨域这是前后端联调最关键的一步。在开发阶段前端运行在localhost:5173后端在localhost:8000浏览器出于安全考虑会阻止这种跨域请求。解决方案是在vite.config.js中配置代理让前端开发服务器将特定请求转发到后端。打开frontend/vite.config.js添加或修改server.proxy配置import { defineConfig } from vite import vue from vitejs/plugin-vue export default defineConfig({ plugins: [vue()], server: { proxy: { // 将 /api 开头的请求代理到后端服务器 /api: { target: http://localhost:8000, // 你的后端地址 changeOrigin: true, rewrite: (path) path.replace(/^\/api/, ) // 重写路径去掉 /api 前缀 } } } })配置解释target你的 FastAPI 后端地址。changeOrigin修改请求头中的Origin为目标地址对于某些后端是必须的。rewrite重写请求路径。这里的意思是前端请求/api/contacts代理会将其转换为http://localhost:8000/contacts。如果你的后端 API 本身就有/api前缀则不需要rewrite。在前端代码中发起请求配置好代理后前端代码中请求 API 就应该使用相对路径指向代理服务器而不是绝对的后端地址。// 在 src/api/contact.js 或类似文件中 import axios from axios; const apiClient axios.create({ baseURL: /api, // 注意这里使用 /api 前缀会被 vite 代理转发 headers: { Content-Type: application/json, }, }); export default { getContacts() { return apiClient.get(/contacts); // 实际请求/api/contacts - 代理 - http://localhost:8000/contacts }, createContact(contactData) { return apiClient.post(/contacts, contactData); }, }验证代理是否生效确保后端 (:8000) 和前端 (:5173) 服务都在运行。在前端页面如联系人列表页触发一个数据请求如页面加载。打开浏览器开发者工具F12进入Network网络标签页。查看发出的请求 URL它应该是http://localhost:5173/api/contacts并且状态码为 200响应数据正确。同时在后端服务的终端日志里你应该能看到对应的请求记录如GET /contacts。如果 Network 中请求失败如 404 或 500检查1) 代理配置路径是否正确2) 后端对应路由是否存在3) 后端服务是否真的在运行。3.3 理解 Vue3 组件与状态管理前端代码的核心是组件和状态管理。以通讯录列表页为例src/views/ContactList.vue(页面组件)template div h1通讯录/h1 button clickfetchContacts刷新/button ul li v-forcontact in contacts :keycontact.id {{ contact.name }} - {{ contact.phone }} /li /ul /div /template script setup import { ref, onMounted } from vue; import contactApi from /api/contact; // 导入封装好的 API 模块 const contacts ref([]); // 使用 ref 创建响应式数据 const fetchContacts async () { try { const response await contactApi.getContacts(); contacts.value response.data; // 将数据赋值给响应式变量 } catch (error) { console.error(获取联系人失败:, error); } }; // 页面加载时自动获取数据 onMounted(() { fetchContacts(); }); /scriptscript setupVue3 的组合式 API 语法更简洁。ref用于创建响应式的基本类型或对象引用。onMounted生命周期钩子在组件挂载后执行适合初始化数据。clickVue 的事件监听语法。状态管理 (Pinia)如果项目复杂可能会用到 PiniaVuex 的替代品来管理全局状态比如用户登录信息。src/stores/user.jsimport { defineStore } from pinia import { ref, computed } from vue export const useUserStore defineStore(user, () { const token ref(localStorage.getItem(token) || ) const isLoggedIn computed(() !!token.value) function setToken(newToken) { token.value newToken localStorage.setItem(token, newToken) } return { token, isLoggedIn, setToken } })在组件中使用script setup import { useUserStore } from /stores/user const userStore useUserStore() // 访问 userStore.token, userStore.isLoggedIn // 调用 userStore.setToken(xxx) /script4. 前后端联调与功能测试前后端各自独立运行且代理配置正确后就可以开始测试完整的增删改查功能了。4.1 基础功能测试流程按照“增 - 查 - 改 - 删”的顺序进行测试每一步都观察前端界面、浏览器 Network 请求和后端日志。新增联系人在前端表单填写姓名、电话、邮箱点击提交。前端检查表单数据是否正常收集请求是否成功发出Network 看 POST 请求。后端终端日志应显示POST /contacts200 或 201。检查数据库是否新增了记录。验证提交后列表是否自动刷新或出现新条目。查询联系人列表进入列表页或刷新页面。前端检查GET /api/contacts请求是否成功数据是否正确渲染。后端日志显示GET /contacts。验证列表是否完整显示所有联系人包括刚新增的。查看/编辑联系人详情点击某条联系人进入详情或编辑页。前端通常会发起一个GET /api/contacts/{id}请求来获取单条数据。后端日志对应GET /contacts/{id}。验证表单是否预填充了正确数据。更新联系人在编辑页修改信息后保存。前端检查PUT /api/contacts/{id}或PATCH请求请求体是否包含修改后的数据。后端日志对应PUT /contacts/{id}200。验证返回列表页该联系人的信息是否已更新。删除联系人点击某条记录的删除按钮。前端通常有确认对话框然后发起DELETE /api/contacts/{id}请求。后端日志对应DELETE /contacts/{id}200 或 204。验证列表页中该联系人是否消失。4.2 联调常见问题与排查即使前后端单独运行正常联调时也可能遇到问题。按以下顺序排查现象可能原因排查步骤前端页面空白或 JS 错误1. 依赖未正确安装2. Node.js 版本过低3. 组件引入路径错误1. 检查浏览器控制台 (Console) 错误信息。2. 删除node_modules和package-lock.json重装依赖。3. 确认/别名在vite.config.js中正确配置。网络请求报 4041. 代理配置错误2. 后端路由不存在3. 请求 URL 拼写错误1. 在浏览器 Network 中查看请求的完整 URL是否指向了localhost:5173/api/...。2. 对比后端main.py或路由文件中的实际路由路径。3. 检查vite.config.js中的target和rewrite规则。网络请求报 500后端服务器内部错误1.首要动作查看后端服务终端输出的错误日志这是最直接的线索。2. 常见原因数据库连接失败、SQL 语法错误、数据验证失败Pydantic 报错、代码逻辑异常。跨域错误 (CORS)代理未生效或配置错误请求直接发往后端1. 确认请求是从localhost:5173发出的而不是localhost:8000。2. 确认vite.config.js中的代理配置已保存且前端服务器已重启。3. 作为备选方案可以在 FastAPI 后端添加 CORS 中间件但开发阶段用代理是更佳实践。数据不显示或显示错误1. 前端组件数据绑定错误2. API 返回的数据结构不符合预期1. 在浏览器 Network 中查看 API 响应体确认数据是否正确。2. 在前端代码中检查console.log打印的响应数据。3. 检查 Vue 模板中v-for循环和数据显示的字段名是否与 API 返回的 JSON 键名匹配。表单提交无效1. 前端未发送请求2. 请求数据格式错误3. 后端验证失败1. 打开浏览器 Network提交时观察是否有请求发出。2. 检查请求的Content-Type是否为application/json。3. 查看请求体 (Payload)数据格式是否与后端 Pydantic 模型 (ContactCreate) 匹配。关键习惯永远先看日志。后端错误看服务终端前端错误看浏览器控制台 (Console) 和网络请求 (Network)。日志里的错误信息能直接定位 80% 的问题。5. 项目扩展与毕业设计答辩要点一个能运行的 Demo 只是开始。要让它在毕业设计中拿高分你需要展示出对项目的深入理解和扩展能力。5.1 功能扩展建议在基础增删改查上添加 1-2 个亮点功能能极大提升项目完整度。用户认证与授权 (JWT)做什么实现用户注册、登录、退出。不同用户只能管理自己的通讯录。后端新增User模型和auth路由。使用python-jose生成和验证 JWT 令牌。在contacts路由中添加依赖项检查请求头中的Authorization令牌并关联用户与联系人。前端添加登录/注册页面。使用 Pinia 或 localStorage 存储 token。在axios拦截器中为每个请求自动添加Authorization头。联系人搜索与筛选做什么在列表页顶部增加搜索框可按姓名、电话模糊搜索。后端修改GET /contacts接口接收q查询参数。在 CRUD 函数中使用 SQLAlchemy 的filter和ilike进行数据库查询。前端在搜索框绑定输入事件使用watch或防抖函数 (lodash.debounce) 触发 API 请求更新列表。数据导出 (CSV/Excel)做什么提供一个按钮将当前通讯录导出为文件。后端新增一个GET /contacts/export接口。使用csv或pandas库将查询结果生成 CSV 字符串通过Response返回并设置合适的响应头 (Content-Disposition: attachment)。前端调用导出接口利用a标签的download属性或Blob对象触发浏览器下载。后端分页做什么联系人数量多时列表分页显示。后端GET /contacts接口已包含skip和limit参数在 CRUD 中配合offset()和limit()实现。在响应中同时返回总条数方便前端计算总页数。前端使用分页组件如 Element Plus 的Pagination根据总条数和每页大小计算页码点击页码时传递skip参数。5.2 代码质量与部署考量代码结构清晰确保你的项目像第一部分描述的那样前后端分离模块职责分明。这是答辩时老师会重点看的。添加注释在关键函数、复杂逻辑处添加中文注释说明功能。在README.md中写清项目简介、技术栈、运行步骤。错误处理不要只是print错误。前端应有用户友好的错误提示如使用ElMessage后端 API 应返回结构化的错误信息而不是赤裸的 500 页面。环境变量配置将数据库连接字符串、JWT 密钥等敏感信息从代码中抽离放入.env文件使用python-dotenv读取。这体现了工程化意识。简单部署演示后端可以使用docker build打包一个简单的 Docker 镜像或者演示如何用uvicorn main:app --host 0.0.0.0 --port 8000在生产模式去掉--reload下运行。前端运行npm run build生成静态文件演示如何用 Nginx 或直接放在后端静态目录 (app.mount(/, StaticFiles(directoryfrontend/dist), namestatic))进行部署。5.3 答辩准备要点答辩时老师关注的不只是功能更是你的思路、理解和解决问题的能力。讲清楚技术选型为什么用 FastAPI 而不是 Django 或 Flask为什么用 Vue3 而不是 React可以谈 FastAPI 的异步、自动文档、高性能Vue3 的组合式 API、响应式系统更友好。演示核心流程现场演示从启动后端、前端到完成一个完整的“新增-查询-编辑-删除”流程。确保流程顺畅。解释关键代码准备 2-3 处核心代码讲解。比如“这是后端的 Pydantic 模型它确保了数据的有效性这是前端的组合式 API用ref和onMounted管理数据和生命周期。”展示扩展功能重点演示你额外添加的功能如搜索、导出并解释实现原理。回答问题准备回答诸如“跨域怎么解决的”开发用代理生产可配 Nginx 或 CORS、“数据库选型为什么用 SQLite”轻量适合毕业设计演示、“如果用户量很大哪里可能成为瓶颈”数据库查询、分页、JWT 验证开销等。诚实面对不足如果被问到没实现的功能或已知的 bug可以坦诚说明并给出后续优化思路如“目前是内存存储 token后续可以引入 Redis”这比强行辩解更好。这个项目最实用的价值是提供了一个可运行、可理解、可扩展的现代 Web 应用骨架。把它跑起来只是第一步真正吃透代码并按照自己的思路进行改造和增强才是完成一个高质量毕业设计的关键。先从单机环境把整套流程打通再考虑如何优化代码结构、增加功能、准备答辩说辞每一步都踩实了最终展示时自然会有底气。
