本文详细介绍一个基于Flask Vue 3的全栈项目——PIWH 平台涵盖项目背景、使用场景、技术选型、核心设计、使用方法和踩坑经验并附完整代码结构和 API 设计帮助你快速上手前后端分离开发。一、写在前面为什么要做这样一个项目对于很多后端开发者来说「会用 Flask 写接口」和「能独立搭起一个前后端分离的完整应用」之间隔着一整条经验鸿沟接口怎么写才算规范、可维护权限认证、密码安全、文件上传这些「脏活累活」该怎么处理前端 Vue 和后端 Flask 之间怎么优雅地对接数据库的表结构、关联关系、迁移版本如何管理带着这些问题我基于Flask 3 Vue 3 Element Plus MySQL从零搭建了一个完整的全栈项目PIWH 平台。它把用户管理、待办事项、博客、记账、课程管理五个常见业务模块揉进了一个系统里同时内置了 Token 认证、密码哈希、验证码、限流、文件上传校验等企业级能力。这篇文章就是我在这个项目中的完整复盘。希望能帮你少走一些弯路。二、项目背景与应用场景2.1 项目背景PIWH 平台项目代号test_flask_project-v1最初是为了系统地练习「前后端分离」的开发范式而创建。在业务上它像一个迷你版的「个人工作台」把日常生活和工作中常见的几类需求整合在一起记一笔待办Todo写一篇博客 / 笔记Blog记一次账Bookkeeping开一门课程、选一次课Course2.2 典型使用场景场景对应模块说明个人任务管理待办事项记录每日待办标记完成状态知识沉淀 / 博客写作博客系统专栏分类、文章发布、读者评论日常收支记账记账管理分类记账按时间段统计收支教学 / 培训管理课程管理课程创建、学生选课退课账号与文件中心用户 文件注册登录、忘记密码、文件上传下载换句话说它既可以当作一个「个人效率工具箱」也可以作为中小型业务系统如课程平台、记账软件、博客站的起步模板。2.3 技术选型理由Flask轻量、灵活配合 Flask-RESTX 能自动生成 Swagger 文档适合快速搭建 RESTful API。Vue 3 Element Plus生态成熟、组件丰富Composition API 让逻辑复用更清晰。MySQL SQLAlchemy关系型数据场景下最稳妥的组合配合 Alembic 管理 schema 变更。前后端分离前端专注交互后端专注业务与数据职责清晰、可独立部署。三、系统架构与核心设计3.1 整体架构┌──────────────────────────────────────────┐ │ 前端 (Vue 3) │ │ Element Plus → Pinia → Axios → API │ └───────────────────┬──────────────────────┘ │ HTTP (JSON) ┌───────────────────┴──────────────────────┐ │ 后端 (Flask) │ │ Services 层API 视图 → Controls 层 │ │ 业务逻辑→ Model 层ORM │ └───────────────────┬──────────────────────┘ │ ┌─────┴─────┐ │ MySQL │ └───────────┘后端采用清晰的三层架构各司其职层级职责Service 层services/注册路由、参数校验、调用控制层、序列化响应Control 层controls/核心业务逻辑、权限校验、数据转换、邮件发送Model 层model/ORM 模型、表结构、关联关系Common 层common/数据库基类、日志、限流、认证、分页工具3.2 两个核心设计模式BaseCtl 模式 —— 通用 CRUD所有控制器继承BaseCtl通过model_cls绑定模型自动获得通用的增删改查能力极大减少重复代码。AdvResource 模式 —— 通用查询所有 API 视图继承AdvResource统一提供分页、过滤、搜索、排序能力通过简单的查询参数即可完成复杂查询GET /blog/article/?page1limit10f_status1s_titleFlasko_created_atdesc四、数据库设计项目共设计了 12 张表核心关系如下User 1 ── N Token / Todo / File / Article / Comment / Expense / Record / Category User N ── N Course通过 StudentCourse 中间表实现多对多 Category 1 ── N Article Article 1 ── N Comment Expense 1 ── N Record几个值得注意的设计点多对多选课通过student_course中间表 (user_id, course_id)联合唯一索引防止重复选课。级联删除所有一对多关系配置cascadeall, delete-orphan删除父记录自动清理子记录。验证码哈希存储密码重置验证码使用 werkzeug 哈希后入库防止数据库泄露时明文验证码被窃取。五、核心功能与使用场景详解5.1 用户模块认证体系注册用户名/邮箱唯一性校验、邮箱格式校验、密码强度校验≥6 位含数字字母、密码哈希后入库。登录密码校验兼容旧明文数据登录时自动升级为哈希、Token 生成secrets.token_urlsafe、记录 User-Agent 和 IP 用于设备绑定。忘记密码邮箱发送 6 位验证码3 分钟有效验证通过后重置密码并强制该用户所有 Token 失效。文件上传黑名单 白名单 MIME 校验 用户目录隔离 同名自动重命名。5.2 待办事项模块每个 Todo 绑定到特定用户同一用户名下name唯一列表查询强制过滤当前用户数据天然实现数据隔离。5.3 博客模块「专栏 → 文章 → 评论」三级结构文章详情可带出评论列表extend_fields[comments]删除时校验所有者身份防止越权操作。5.4 记账模块收支分类 收支记录统计接口使用数据库聚合查询SELECT COALESCE(SUM(income), 0), COALESCE(SUM(spend), 0) FROM record WHERE user_id ? AND record_time BETWEEN ? AND ?5.5 课程模块典型的多对多关系课程列表额外计算is_enrolled当前用户是否已选和studentCount选课人数。六、使用步骤手把手6.1 准备环境Python 3.8Node.js 16推荐 18MySQL 5.7 / 8.x6.2 配置环境变量复制模板并填入真实值cp .env.example .env.env关键配置敏感信息请用你自己的值DB_USERroot DB_PASSxxx DB_HOSTxxx DB_PORT3306 DB_NAMEtest ​ MAIL_SERVERsmtp.qq.com MAIL_PORT465 MAIL_USERNAMExxxqq.com MAIL_PASSWORDxxx6.3 初始化数据库cd src pip install -r requirements.txt alembic upgrade head6.4 安装前端依赖cd frontend npm install6.5 一键启动回到项目根目录python start.py浏览器访问http://localhost:5173即可进入登录/注册页面。后端 Swagger 文档地址http://localhost:5000/七、API 设计一览方法路径说明POST/user/注册用户POST/user/token/登录POST/user/password-reset/request/发送验证码POST/user/password-reset/verify/验证码重置密码GET/POST/todo/Todo 列表/创建GET/POST/blog/article/文章列表/发布GET/POST/blog/category/专栏列表/创建GET/POST/blog/comment/评论列表/发表GET/POST/bookkeeping/expense/收支分类GET/POST/bookkeeping/record/收支记录POST/bookkeeping/count/收支统计GET/POST/course/课程列表/选课所有 GET 列表接口支持统一的page/limit/f_{field}精确过滤/s_{field}模糊搜索/o_{field}排序参数。八、安全设计踩坑与心得这是我在项目中最花心思的部分分享几个关键点密码一定要哈希存储且登录时若发现旧明文数据要「自动升级」平滑迁移历史数据。验证码不能明文存库我用哈希存储 失效机制请求新码/重置成功时批量失效旧码双保险也修复了早期「验证码明文写日志」的高危漏洞。登录/忘记密码接口必须限流否则可被暴力枚举这是我项目里标记为待优化的一点登录接口当前还缺限流装饰器。文件上传要做多层校验黑名单拦可执行文件、白名单限扩展名、MIME 校验防伪装、按用户目录隔离。所有数据查询强制过滤f_user_id这是多租户隔离最简单有效的做法。完整的安全措施清单和潜在 Bug 分析可以参考项目里的设计文档这里不再赘述。九、运行成功效果图十、总结与展望这个项目让我完整走了一遍「前后端分离」的开发流程从架构设计、数据库建模、接口设计到安全防护收获很大。当然它也有一些可以继续优化的地方比如Token 目前是简单随机字符串后续可迁移到JWT Refresh Token限流器目前是内存存储可引入Redis测试覆盖率偏低可补充单元测试和集成测试可引入Docker和CI/CD提升工程化水平。如果你也在学习 Flask 或 Vue希望这篇文章和这个项目能给你一些启发。完整的代码结构和环境配置可以参考项目的README.md。提示本文所有示例代码中的数据库密码、邮箱账号等敏感信息均已用xxx代替实际使用时请通过.env文件管理切勿硬编码或提交到公开仓库。如果这篇文章对你有帮助欢迎点赞、收藏、关注也欢迎在评论区交流你的想法有需要项目源码的可以私我获取