Python FastAPI与Vue 3前后端分离开发：从零构建Todo应用实战

1. 项目概述为什么选择PythonVue做前后端分离前后端分离的架构模式现在几乎成了现代Web开发的标配。但很多刚入门的开发者一听到“分离”就觉得复杂下意识地认为需要庞大的团队和复杂的工具链。其实不然一个轻量级的、能跑起来的分离项目核心思想非常朴素前端负责展示和交互后端负责提供数据接口两者通过HTTP协议“对话”。我选择用PythonFlask/FastAPI和Vue.js来搭建这个项目原因很直接。Python的后端框架尤其是Flask以“微”著称上手门槛极低几行代码就能拉起一个API服务非常适合快速验证想法和构建中小型应用的后端。而Vue.js作为前端框架其渐进式的特性和清晰的模板语法让前端开发变得直观数据绑定和组件化开发能极大提升开发效率。这套组合对于个人开发者、初创团队或者想快速掌握全栈技能的朋友来说是一个黄金搭档。它既能让你深刻理解前后端分离的通信本质又不会在初期被复杂的配置和概念劝退。这个项目的目标就是带你从零开始手把手搭建一个具备完整“请求-响应”流程的简易系统。我们会实现一个经典案例一个待办事项Todo List应用。前端Vue页面展示任务列表并提供添加、删除任务的交互后端Python API则负责接收前端的请求在内存或简单的文件/数据库中管理这些任务数据。通过这个麻雀虽小五脏俱全的例子你将清晰地看到JSON数据如何在网络间流动跨域问题如何解决以及前后端开发者如何基于接口文档进行协作。2. 技术栈选型与项目初始化2.1 后端技术栈Flask vs FastAPI后端我们主要在两个轻量级框架中做选择Flask和FastAPI。Flask: 老牌微框架生态极其丰富文档齐全社区庞大。它的设计哲学是“微核心”只提供最基础的路由、请求/响应处理其他功能如数据库ORM、用户认证等都通过扩展Extension来添加。这种灵活性是它的优点但也意味着在构建API时你需要手动处理很多细节比如数据验证、自动生成API文档等需要引入额外的库如Flask-RESTful, Marshmallow。FastAPI: 一个新兴的现代框架基于Python类型提示Type Hints和Pydantic天生为构建API而设计。它最大的亮点是自动生成交互式API文档Swagger UI和ReDoc以及极高的性能基于Starlette和Pydantic。数据验证、序列化、依赖注入等功能都是内置的开发体验非常流畅。我的选择与理由 对于这个入门项目我推荐使用FastAPI。原因有三开发效率利用类型提示IDE的智能补全和错误检查会非常强大。定义好数据模型Pydantic Model路由函数参数的类型和验证就自动完成了。API文档自动生成的Swagger UI界面让你和后端、前端同学调试接口变得异常方便无需额外编写和维护文档。未来友好FastAPI代表了Python Web API开发的新趋势学习它对于应对更复杂的项目更有帮助。当然如果你对Flask更熟悉用它也完全没问题只是需要多配置一些扩展。本项目后续演示将以FastAPI为主但核心思想是相通的。后端项目初始化 首先创建一个干净的项目目录并建立虚拟环境这是Python项目的良好实践可以隔离依赖。# 创建项目根目录 mkdir python-vue-todo cd python-vue-todo # 创建后端目录并进入 mkdir backend cd backend # 创建Python虚拟环境假设使用Python3 python3 -m venv venv # 激活虚拟环境 # 在Windows上: venv\Scripts\activate # 在Mac/Linux上: source venv/bin/activate # 安装核心依赖 pip install fastapi uvicornuvicorn是一个ASGI服务器用于运行FastAPI应用。2.2 前端技术栈Vue 3 构建工具前端我们选择Vue 3的 Composition API 风格它比Vue 2的Options API逻辑组织更灵活。构建工具上我们使用Vite它比传统的Vue CLI启动更快热更新更迅速开发体验极佳。前端项目初始化 回到项目根目录使用Vite官方模板快速创建Vue项目。# 回到项目根目录 cd .. # 使用Vite创建Vue项目项目名为frontend npm create vuelatest frontend执行命令后命令行会交互式地询问你配置一些选项。对于这个简单项目我的选择如下Add TypeScript?-No(为简化先用JavaScript)Add JSX Support?-NoAdd Vue Router for Single Page Application?-No(本项目单页足够)Add Pinia for state management?-No(状态简单先用reactive/ref)Add Vitest for Unit Testing?-NoAdd an End-to-End Testing Solution?-NoAdd ESLint for code quality?-Yes(推荐保持代码规范)创建完成后进入前端目录安装依赖并启动开发服务器cd frontend npm install npm run dev此时访问http://localhost:5173应该能看到Vue的欢迎页面。我们的前端开发将在这里进行。注意前后端项目分别位于backend和frontend文件夹下这种结构清晰地将两者分离也便于后续分别部署。3. 后端API设计与实现3.1 定义数据模型与API接口我们的Todo应用需要几个核心操作获取所有任务、创建新任务、更新任务状态、删除任务。这对应着RESTful API的基本操作GET, POST, PUT/PATCH, DELETE。首先在后端backend目录下创建一个主应用文件main.py。# backend/main.py from fastapi import FastAPI, HTTPException from pydantic import BaseModel from typing import List, Optional from uuid import uuid4, UUID # 初始化FastAPI应用实例 app FastAPI( titleTodo API, description一个简单的待办事项API服务, version1.0.0 ) # 定义Todo项的数据模型Pydantic Model class TodoItem(BaseModel): id: Optional[UUID] None # 任务唯一ID由后端生成 title: str # 任务标题 description: Optional[str] # 任务描述可选 completed: bool False # 完成状态默认为未完成 # 模拟一个内存数据库用列表存储Todo项 # 在实际项目中这里会连接MySQL、PostgreSQL或MongoDB等数据库 todos_db: List[TodoItem] [] app.get(/) def read_root(): return {message: Welcome to Todo API} # 1. 获取所有Todo项 app.get(/todos, response_modelList[TodoItem]) def get_all_todos(): 返回所有的待办事项 return todos_db # 2. 创建新的Todo项 app.post(/todos, response_modelTodoItem) def create_todo(todo: TodoItem): 创建一个新的待办事项 # 为新的Todo项生成唯一ID todo.id uuid4() # 将新的Todo项添加到“数据库” todos_db.append(todo) return todo # 3. 根据ID获取单个Todo项 app.get(/todos/{todo_id}, response_modelTodoItem) def get_todo_by_id(todo_id: UUID): 根据ID获取指定的待办事项 for todo in todos_db: if todo.id todo_id: return todo # 如果没找到抛出404异常 raise HTTPException(status_code404, detailTodo item not found) # 4. 更新Todo项这里以更新完成状态为例 app.patch(/todos/{todo_id}, response_modelTodoItem) def update_todo_status(todo_id: UUID, completed: bool): 更新指定待办事项的完成状态 for todo in todos_db: if todo.id todo_id: todo.completed completed return todo raise HTTPException(status_code404, detailTodo item not found) # 5. 删除Todo项 app.delete(/todos/{todo_id}) def delete_todo(todo_id: UUID): 删除指定的待办事项 for index, todo in enumerate(todos_db): if todo.id todo_id: # 从列表中移除该项 deleted_todo todos_db.pop(index) return {message: fTodo item {deleted_todo.title} deleted successfully} raise HTTPException(status_code404, detailTodo item not found)代码解析与注意事项Pydantic模型 (TodoItem)它定义了API接口中“数据”的形状和验证规则。id字段我们使用Python内置的uuid模块生成UUID确保全局唯一。Optional表示该字段可以为None。内存数据库 (todos_db)这是一个全局列表用于在服务器运行期间存储数据。服务器重启后数据会丢失。这是为了简化演示生产环境务必使用持久化数据库。路径参数与查询参数app.get(/todos/{todo_id})中的{todo_id}是路径参数。app.patch(/todos/{todo_id})中completed: bool是查询参数FastAPI会自动从请求URL的查询字符串中解析。HTTP状态码与异常使用HTTPException可以返回标准的HTTP错误响应比如404未找到或400错误请求这是构建友好API的重要部分。response_model这个参数告诉FastAPI使用哪个Pydantic模型来序列化格式化返回的响应数据。它能确保输出数据的结构符合预期并自动过滤掉模型中未定义的字段增强了API的健壮性。3.2 处理跨域请求 (CORS)前后端分离开发时前端运行在localhost:5173后端运行在另一个端口如localhost:8000浏览器出于安全考虑会阻止这种跨域请求。因此后端必须配置CORS跨源资源共享。在main.py中增加CORS中间件的配置# 在文件顶部导入 CORSMiddleware from fastapi.middleware.cors import CORSMiddleware # 在创建app实例后挂载CORS中间件 app.add_middleware( CORSMiddleware, allow_origins[http://localhost:5173], # 允许前端的源这里填Vite开发服务器的地址 allow_credentialsTrue, allow_methods[*], # 允许所有HTTP方法 allow_headers[*], # 允许所有请求头 )实操心得allow_origins在生产环境中应该设置为确切的前端部署域名而不是*允许所有否则会带来安全风险。开发阶段为了方便可以暂时放宽。3.3 启动与测试后端API启动后端服务器# 确保在backend目录下且虚拟环境已激活 uvicorn main:app --reload --host 0.0.0.0 --port 8000main:appmain是模块名文件名app是FastAPI应用实例名。--reload开启热重载代码修改后服务器自动重启非常适合开发。--host 0.0.0.0让服务器监听所有网络接口方便同一网络内其他设备访问。--port 8000指定运行端口。访问http://localhost:8000/docs你会看到FastAPI自动生成的Swagger UI交互式文档。你可以在这里直接尝试调用我们刚写的所有API这是FastAPI最强大的特性之一极大简化了后端API的调试和前端对接工作。4. 前端Vue应用开发4.1 项目结构清理与组件设计进入frontend/src目录我们先清理一下默认文件使其更符合我们的项目。删除components/目录下的所有默认组件。清空App.vue文件的内容我们将从头编写。在src/components/目录下新建两个组件TodoList.vue用于展示任务列表。AddTodo.vue用于添加新任务的表单。我们的应用结构很简单App.vue作为根组件包含AddTodo和TodoList两个子组件。4.2 状态管理与API服务层在简单的应用中我们可以使用Vue 3的reactive或ref在根组件管理状态即Todo列表并通过provide/inject或Props传递给子组件。但为了更清晰地分离关注点并展示更通用的模式我们创建一个简单的“API服务”模块和状态管理。创建API服务 (src/services/todoApi.js) 这个模块封装所有与后端通信的HTTP请求使用axios库。# 在前端项目目录下安装axios npm install axios// src/services/todoApi.js import axios from axios; // 创建一个配置好的axios实例设置基础URL const apiClient axios.create({ baseURL: http://localhost:8000, // 后端API地址 headers: { Content-Type: application/json, }, }); export default { // 获取所有任务 getTodos() { return apiClient.get(/todos); }, // 创建新任务 createTodo(todoData) { return apiClient.post(/todos, todoData); }, // 更新任务状态 updateTodoStatus(id, completed) { return apiClient.patch(/todos/${id}, null, { params: { completed } // PATCH请求状态通过查询参数传递 }); }, // 删除任务 deleteTodo(id) { return apiClient.delete(/todos/${id}); }, };在根组件管理状态 (src/App.vue)template div idapp h1我的待办事项 (Python Vue)/h1 AddTodo todo-addedfetchTodos / TodoList :todostodos todo-updatedfetchTodos todo-deletedfetchTodos / /div /template script setup import { ref, onMounted } from vue; import AddTodo from ./components/AddTodo.vue; import TodoList from ./components/TodoList.vue; import todoApi from ./services/todoApi; // 使用ref管理响应式状态 const todos ref([]); // 获取所有Todo的函数 const fetchTodos async () { try { const response await todoApi.getTodos(); todos.value response.data; } catch (error) { console.error(获取任务列表失败:, error); alert(无法加载任务列表请检查后端服务是否运行。); } }; // 组件挂载时立即获取数据 onMounted(() { fetchTodos(); }); /script style #app { font-family: Avenir, Helvetica, Arial, sans-serif; max-width: 600px; margin: 0 auto; padding: 20px; } /style4.3 子组件实现添加与展示任务AddTodo.vue组件template div classadd-todo h3添加新任务/h3 form submit.preventhandleSubmit div label fortitle标题/label input typetext idtitle v-modelnewTodo.title required / /div div label fordescription描述/label textarea iddescription v-modelnewTodo.description/textarea /div button typesubmit添加/button /form /div /template script setup import { reactive } from vue; import todoApi from ../services/todoApi; const emit defineEmits([todo-added]); // 使用reactive管理表单数据 const newTodo reactive({ title: , description: , completed: false, }); const handleSubmit async () { if (!newTodo.title.trim()) { alert(标题不能为空); return; } try { // 调用API服务创建任务 await todoApi.createTodo({ title: newTodo.title, description: newTodo.description, completed: newTodo.completed, }); // 成功提示 alert(任务添加成功); // 清空表单 newTodo.title ; newTodo.description ; // 通知父组件刷新列表 emit(todo-added); } catch (error) { console.error(添加任务失败:, error); alert(添加任务失败请重试。); } }; /script style scoped .add-todo { margin-bottom: 30px; padding: 20px; border: 1px solid #eee; border-radius: 8px; } .add-todo div { margin-bottom: 15px; } label { display: inline-block; width: 80px; font-weight: bold; } input, textarea { width: calc(100% - 90px); padding: 8px; border: 1px solid #ccc; border-radius: 4px; } button { background-color: #42b983; color: white; padding: 10px 20px; border: none; border-radius: 4px; cursor: pointer; font-size: 16px; } button:hover { background-color: #3aa876; } /styleTodoList.vue组件template div classtodo-list h3任务列表/h3 p v-iftodos.length 0暂无任务请添加一个吧/p ul v-else li v-fortodo in todos :keytodo.id :class{ completed: todo.completed } div classtodo-content strong{{ todo.title }}/strong p v-iftodo.description{{ todo.description }}/p /div div classtodo-actions !-- 切换完成状态的复选框 -- input typecheckbox :checkedtodo.completed changetoggleTodoStatus(todo.id, $event.target.checked) / !-- 删除按钮 -- button clickdeleteTodo(todo.id) classdelete-btn删除/button /div /li /ul /div /template script setup import { defineProps, defineEmits } from vue; import todoApi from ../services/todoApi; const props defineProps({ todos: { type: Array, required: true, }, }); const emit defineEmits([todo-updated, todo-deleted]); // 切换任务完成状态 const toggleTodoStatus async (id, completed) { try { await todoApi.updateTodoStatus(id, completed); emit(todo-updated); // 通知父组件状态已更新 } catch (error) { console.error(更新任务状态失败:, error); alert(更新状态失败请重试。); } }; // 删除任务 const deleteTodo async (id) { if (!confirm(确定要删除这个任务吗)) { return; } try { await todoApi.deleteTodo(id); emit(todo-deleted); // 通知父组件任务已删除 } catch (error) { console.error(删除任务失败:, error); alert(删除任务失败请重试。); } }; /script style scoped .todo-list { padding: 20px; border: 1px solid #eee; border-radius: 8px; } ul { list-style: none; padding: 0; } li { display: flex; justify-content: space-between; align-items: flex-start; padding: 15px; margin-bottom: 10px; border: 1px solid #ddd; border-radius: 6px; background-color: #f9f9f9; } li.completed { opacity: 0.7; background-color: #e8f5e9; } li.completed .todo-content strong { text-decoration: line-through; color: #888; } .todo-content { flex-grow: 1; } .todo-actions { display: flex; align-items: center; gap: 10px; } .delete-btn { background-color: #f44336; color: white; padding: 5px 10px; border: none; border-radius: 4px; cursor: pointer; font-size: 14px; } .delete-btn:hover { background-color: #d32f2f; } /style4.4 前后端联调与运行启动后端确保在backend目录下运行uvicorn main:app --reload --host 0.0.0.0 --port 8000。启动前端在frontend目录下运行npm run dev。打开浏览器访问Vite开发服务器地址通常是http://localhost:5173。现在你应该能看到一个完整的Todo应用界面。尝试添加任务、勾选完成、删除任务所有操作都会通过HTTP请求与后端的FastAPI服务进行交互页面数据会实时更新。打开浏览器的开发者工具F12切换到“网络”(Network)标签页你可以清晰地看到每次操作发出的HTTP请求和响应直观地理解前后端分离的数据流。5. 项目部署与进阶优化思路5.1 开发与生产环境配置分离目前我们的配置如API基础URLhttp://localhost:8000是硬编码的这不利于部署。通常做法是利用环境变量。前端配置 在frontend目录下创建.env.development和.env.production文件。# .env.development VITE_API_BASE_URLhttp://localhost:8000# .env.production VITE_API_BASE_URLhttps://api.yourdomain.com修改todoApi.js中的baseURLconst apiClient axios.create({ baseURL: import.meta.env.VITE_API_BASE_URL, // 使用环境变量 // ... 其他配置 });Vite使用import.meta.env来访问以VITE_开头的环境变量。后端配置 可以使用python-dotenv等库来管理环境变量如数据库连接字符串、密钥等。5.2 前端构建与部署开发完成后需要将Vue项目构建成静态文件。npm run build该命令会在frontend/dist目录下生成优化后的静态资源HTML, CSS, JS。你可以将这些文件部署到任何静态文件托管服务上如Nginx、Apache、Vercel、Netlify或云存储AWS S3 CloudFront。5.3 后端部署FastAPI应用需要一个ASGI服务器来运行。生产环境推荐使用Gunicorn Uvicorn WorkersGunicorn作为进程管理器搭配Uvicorn worker来处理异步请求。pip install gunicorn gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker -b 0.0.0.0:8000容器化部署使用Docker是更现代和一致的选择。创建一个DockerfileFROM python:3.9-slim WORKDIR /app COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt COPY . . CMD [uvicorn, main:app, --host, 0.0.0.0, --port, 8000]然后构建镜像并运行容器可以轻松部署到云服务器或Kubernetes集群。5.4 常见问题与排查技巧实录在实际开发中你几乎一定会遇到下面几个问题问题1前端调用API失败控制台报错CORS policy现象浏览器控制台出现类似“Access to fetch at ‘http://localhost:8000/todos‘ from origin ‘http://localhost:5173‘ has been blocked by CORS policy”的错误。排查确认后端CORS中间件已正确配置且allow_origins包含了前端的地址http://localhost:5173。检查后端服务器是否已重启如果修改了CORS配置。如果是生产环境检查allow_origins是否配置了正确的前端域名。技巧可以在后端临时将allow_origins设置为[*]来快速判断是否是CORS问题但务必在上线前改回具体的域名。问题2前端页面空白控制台报错Failed to load module script现象构建后的前端页面无法加载控制台有JavaScript模块加载错误。排查最常见的原因是前端静态资源路径错误。如果你将前端构建文件部署在非根路径如/app/需要在Vite配置中设置base选项 (vite.config.js中的base: ‘/app/‘)。检查服务器如Nginx是否正确配置了静态资源的路由和MIME类型。技巧使用npm run preview命令可以在本地预览构建后的产物先确保本地是正常的。问题3后端API返回422 Unprocessable Entity现象前端发送POST或PUT请求时后端返回422错误。排查这是FastAPI/Pydantic的数据验证错误。检查前端发送的JSON数据格式是否与后端Pydantic模型定义完全匹配字段名、类型。打开浏览器开发者工具的“网络”标签查看请求的Payload并与后端main.py中的TodoItem模型对比。查看后端日志或Swagger UI的响应详情通常会明确提示哪个字段验证失败。技巧充分利用Swagger UI (/docs) 或 ReDoc (/redoc) 来测试你的API它能直观地展示请求体格式。问题4页面数据不更新现象前端操作如添加、删除后列表没有实时刷新。排查检查前端是否成功接收到了后端返回的响应网络标签。检查前端的事件发射 (emit) 和监听是否成功。在子组件中console.logemit的事件在父组件中检查对应的处理函数如fetchTodos是否被调用。确认fetchTodos函数是否正确更新了响应式变量如todos.value。技巧在Vue开发中可以安装Vue Devtools浏览器插件它能帮你审查组件层次结构、状态和事件是调试Vue应用的利器。这个简单的PythonVue前后端分离项目就像搭积木一样把现代Web开发的核心模块串联了起来。从后端的路由、模型、CORS到前端的组件、状态、API调用每一步都触及了关键概念。它可能不具备生产级的复杂度但足以作为一个坚实的起点。当你理解了数据如何通过JSON在浏览器和服务器之间穿梭如何用组件构建界面如何用异步函数处理网络请求你就已经掌握了分离架构的精髓。接下来你可以尝试为它添加用户登录JWT认证、连接真实的数据库如PostgreSQL、引入状态管理库Pinia、或编写单元测试每一步扩展都是对你全栈能力的夯实。