简介这是Fyyur项目完整代码包源自优达学城全栈开发课程Fyyur是一个音乐表演场地与艺术家预定平台用于发现和预订本地演出。资源面向已经掌握Python基础、希望实践Flask与PostgreSQL集成开发的学习者当前代码框架已经搭建了视图、表单和页面模板但数据模型尚未实现需要学习者根据业务需求设计并构建数据库模型进而为网站API端点提供数据支持。压缩包共六十四份文件大小仅二点三二兆字节包含Python源码、HTML模板、CSS样式表、JavaScript脚本、Alembic迁移配置和说明文档其中前端资源负责页面展示与用户交互Python模块承担路由、表单处理和模型逻辑迁移脚本用于追踪数据库结构调整。另有README文件与依赖清单辅助环境搭建已有七十五人学习下载。通过研读这套代码可以体验从零建立数据模型、配置数据库迁移、完善接口查询的完整流程理解Flask应用与PostgreSQL数据库的协作方式适合作为全栈开发实战练习或课程设计的参考资料。1. 这个 Fyyur 项目不只是课程作业更是演出供需平台的最小可用原型Fyyur 这个名字乍看像某个虚构品牌但它背后是一个实打实的全栈练手项目围绕演出场馆Venue和艺人Artist的供需匹配做一个带增删改查的 Web 平台。很多从业者第一次见到它是在某门数据建模课程里但拆完你会发现它的价值远不止完成一个作业——从 ER 图设计到 HTML 表单提交再到底层数据库事务它把一套业务系统的骨架完整地搭在了你面前。如果你正在学 Flask SQLAlchemy或者想找一个能拿得出手的课程设计源码包这个项目是极好的参照物。它能解决的实际问题很明确怎么用 HTML 表单驱动数据库写入、怎么做多表关联查询、怎么在前端页面里呈现一对多关系。适合的人群也很清楚刚啃完基础语法、想动手做完整项目的开发者以及需要课程设计源码做二次开发的在校生。2. 数据建模先行看懂 Fyyur 的核心表结构与关系设计2.1 三个核心模型Venue、Artist、Show 的字段设计逻辑Fyyur 的数据模型是整个项目的地基。它一共三个主要模型Venue场馆、Artist艺人、Show演出。三者之间的关系是典型的多对多一个场馆可以办多场演出一个艺人也可以接多场演出而 Show 表就是连接两者的中间表。我一般拿到这类项目源码第一步不是看页面而是先打开 models.py 把字段过一遍这比跑起来更重要。Venue 表里值得注意的字段有 name、city、state、address、phone、genres、website、seeking_talent 这类字段。其中 genres 这个字段在不少版本里是用字符串存储的也就是把多个流派用逗号拼成一个字符串塞进数据库这种做法在后端处理简单但如果你想按流派做筛选就要用到 LIKE 查询性能上不如单独建一张关联表。Show 表则持有 venue_id 和 artist_id 两个外键同时记录了演出开始时间 start_time。这个时间字段在 SQLAlchemy 里通常用 DateTime 类型前端提交时如果格式不对很容易在入库时翻车。class Show(db.Model): __tablename__ show id db.Column(db.Integer, primary_keyTrue) venue_id db.Column(db.Integer, db.ForeignKey(venue.id), nullableFalse) artist_id db.Column(db.Integer, db.ForeignKey(artist.id), nullableFalse) start_time db.Column(db.DateTime, nullableFalse) venue db.relationship(Venue, backrefdb.backref(shows, cascadeall, delete)) artist db.relationship(Artist, backrefdb.backref(shows, cascadeall, delete))这段代码的逻辑很好理解venue_id 和 artist_id 都是外键分别指向 venue 和 artist 表的主键。relationship 的作用是让 SQLAlchemy 在查询时自动帮你做 JOIN 拼接不用手写 SQL。cascadeall, delete 意味着当你删除一个场馆时它关联的演出记录也会被清掉这在数据一致性上有用但也是很多新手踩坑的地方——如果你不想删除场馆时把历史演出记录一起删掉就得把 cascade 去掉。2.2 SQLAlchemy 关联查询一对多与多对多在实际业务中怎么用在 Fyyur 里最常用的查询场景有三个首页展示所有场馆、查看单个场馆详情包含它下面的演出列表、查看单个艺人详情包含它接过的演出。这三个场景分别对应不同的查询写法。# 查询所有场馆及其演出场次数量 venues db.session.query( Venue, db.func.count(Show.id).label(num_shows) ).outerjoin(Show).group_by(Venue.id).all()这里用 outerjoin 而不是 join原因是outerjoin左外连接能保证即使某个场馆一场演出都没有也依然会出现在列表里只是 num_shows 为 0。如果你用 join没演出的场馆会被直接过滤掉这在业务上是个隐蔽的 bug——场馆列表页面缺数据用户还以为出错了。group_by 则配合 count 做分组统计每个场馆得到自己的演出数量。这个查询是 Fyyur 首页最常见的玩法你把这段代码跑到一半会发现 query 层面其实比写原生 SQL 更直观因为 SQLAlchemy 帮你把表名和字段名做了映射。再看单个场馆详情的查询venue db.session.query(Venue).filter(Venue.id venue_id).first() upcoming_shows db.session.query(Show).filter( Show.venue_id venue_id, Show.start_time datetime.now() ).order_by(Show.start_time.asc()).all()这里的逻辑是用两次独立查询代替 JOIN 查询。第一次取场馆基本信息第二次查该场馆未来所有演出并按时间升序排列。这样写的好处是代码清晰坏处是数据库会被多访问一次。在小项目里这不是问题但在真实业务中你通常会用 JOIN group 一次搞定。Fyyur 里还有一种常见做法就是在 Venue 模型上直接定义 relationship 加 secondary 参数实现多对多但实际项目中用中间表手动管理更可控。3. HTML 模板与表单交互把数据库操作搬到浏览器里3.1 模板继承与 Jinja2 渲染页面骨架如何复用Fyyur 的前端部分用的是 Flask 默认的 Jinja2 模板引擎配合 HTML 表单实现数据的增删改查。这个组合在课程设计类项目里非常主流。如果你把 templates 目录打开会发现它大量使用了模板继承——一个基础布局文件 layout.html加上若干个子页面模板。!-- templates/layout.html -- !DOCTYPE html html langen head meta charsetUTF-8 title{% block title %}{% endblock %} | 演出管理平台/title /head body nav a href/首页/a a href/venues场馆/a a href/artists艺人/a /nav main {% block content %}{% endblock %} /main /body /html!-- templates/venues/new.html -- {% extends layout.html %} {% block title %}新增场馆{% endblock %} {% block content %} form methodPOST action/venues/create label场馆名称/label input typetext namename required label城市/label input typetext namecity required label州/label select namestate {% for state in states %} option value{{ state }}{{ state }}/option {% endfor %} /select button typesubmit提交/button /form {% endblock %}这个做法的价值在于所有页面的头部导航、底部脚本都不用重复写改一处全站生效。block title 和 block content 是 Jinja2 的占位块子模板通过 extends 继承父模板再覆盖对应 block 里的内容。表单的 method 是 POSTaction 指向 /venues/create这个地址由后端的 Flask 路由处理。你会发现整个流程是浏览器填写表单 → POST 请求发出 → Flask 路由接收 → SQLAlchemy 写入数据库 → 重定向到列表页。3.2 表单数据回显与编辑场景为什么需要 value 属性编辑功能是 Fyyur 里最容易被忽略但实际很关键的环节。新增页面和编辑页面共用同一个 HTML 模板差别只在编辑时要回填已有数据。form methodPOST action/venues/{{ venue.id }}/edit label场馆名称/label input typetext namename value{{ venue.name }} required label城市/label input typetext namecity value{{ venue.city }} required label流派/label select namegenres multiple {% for genre in all_genres %} option value{{ genre }} {% if genre in venue.genres %}selected{% endif %}{{ genre }}/option {% endfor %} /select input typesubmit value保存修改 /form这里的关键点是 value{{ venue.name }} 和 selected 的判断。如果不写 value编辑页面打开时所有输入框都是空的用户只能凭记忆重新输入全部内容这是产品设计上的低级失误。selected 的判断则用 Jinja2 的条件语法把该场馆已有的流派选项默认选中。这前后的逻辑分别是读取场馆对象 → 模板渲染时填充默认值 → 用户修改后提交 → 后端执行 UPDATE 语句。整个闭环里HTML 本身一点业务逻辑都没有但它在正确的位置上做好了数据展示这就是模板渲染的意义所在。3.3 下拉框数据从哪来状态字段与动态渲染Fyyur 里有一个细节值得单独说state 下拉框。美国有 50 个州你不可能在 HTML 里手写 50 个 option。常见的做法是在后端维护一个常量列表渲染模板时传进来。// 某些版本的前端会用 JavaScript 动态生成 const states [CA, NY, TX, WA, FL]; const select document.getElementById(state); states.forEach(state { const option document.createElement(option); option.value state; option.textContent state; select.appendChild(option); });在后端 Flask 路由里这个列表以参数形式传入 render_templateapp.route(/venues/new) def create_venue_form(): states [CA, NY, TX, WA, FL, IL, MA] return render_template(forms/new_venue.html, statesstates)这种做法的好处是数据和视图解耦后端改状态列表前端不需要动任何代码。坏处是如果前后端分离这个逻辑就得挪到前端处理。在 Fyyur 这个纯服务端渲染的架构里后端传列表、模板循环输出是最朴素也最不容易出错的方案。4. 路由与业务逻辑把增删改查串成完整闭环4.1 Flask 路由设计URL 与视图函数的映射关系Fyyur 里的路由大致分为三类展示类GET 请求、表单提交类POST 请求、操作类POST 或 DELETE 请求。展示类路由如 /、/venues、/artists、/venues/ int:venue_id 新增类路由如 /venues/create编辑类路由如 /venues/ int:venue_id /edit。app.route(/venues/int:venue_id) def show_venue(venue_id): venue Venue.query.get(venue_id) if not venue: return render_template(errors/404.html), 404 upcoming_shows db.session.query(Show).join(Artist).filter( Show.venue_id venue_id, Show.start_time datetime.now() ).all() past_shows db.session.query(Show).join(Artist).filter( Show.venue_id venue_id, Show.start_time datetime.now() ).all() return render_template(pages/show_venue.html, venuevenue, upcoming_showsupcoming_shows, past_showspast_shows)这段代码的逻辑很典型先查场馆查不到就返回 404查到就继续查未来演出和过往演出。future 和 past 的区分标准就是 start_time 和当前时间做比较。join(Artist) 是为了拿到艺人名称因为详情页要显示演出的艺人信息。这种写法在功能上没问题但有一个性能隐患如果一场演出都没查出来还是会执行两次数据库查询。用条件聚合可以优化成一次查询不过对课程设计来说这个体量完全够用。4.2 GET 与 POST 的正确姿势为什么不能用 GET 做删除不少新手会把删除操作做成 GET 请求也就是点击一个链接就直接删除数据。这是很危险的做法——搜索引擎爬虫、浏览器预加载、用户误点都会触发删除操作。app.route(/venues/int:venue_id/delete, methods[POST]) def delete_venue(venue_id): venue Venue.query.get(venue_id) if not venue: return render_template(errors/404.html), 404 db.session.delete(venue) db.session.commit() return redirect(url_for(index))对应的前端表单长这样form methodPOST action/venues/{{ venue.id }}/delete onsubmitreturn confirm(确定删除吗); button typesubmit删除/button /form这里的核心是用 POST 表单提交来执行删除而不是用 。配合 onsubmit 的 confirm 弹窗至少能给用户一个反悔的机会。你会在很多课程设计源码里看到 GET 删除的反面教材Fyyur 的正确写法值得当作标准格式记下来。4.3 数据校验与异常处理入库之前先想清楚这三件事数据从浏览器到数据库中间有大量可能翻车的环节。Fyyur 虽然是个课程项目但异常处理也算做足了功课。我一般关注三个位置唯一性约束、必填字段、类型转换。app.route(/artists/int:artist_id, methods[POST]) def edit_artist(artist_id): error False try: artist Artist.query.get(artist_id) artist.name request.form.get(name) artist.city request.form.get(city) artist.state request.form.get(state) artist.phone request.form.get(phone) db.session.commit() except: error True db.session.rollback() finally: db.session.close() if error: flash(保存失败请检查输入内容) return redirect(url_for(edit_artist_form, artist_idartist_id)) else: return redirect(url_for(show_artist, artist_idartist_id))db.session.rollback() 是后悔药一旦某条数据入库时报错数据库之前的事物状态会被回滚避免产生半截数据。db.session.close() 则是释放数据库连接资源。这段代码把异常处理拉满了但实际业务里你通常还需要在字段级别做校验——比如 phone 字段是否符合电话格式、email 字段是否合法。Fyyur 有一些版本用了自定义校验函数但大部分版本是依赖 HTML 的 required 属性做前端兜底后端主要靠 try-except 兜底。这种做法对付课程设计足够生产环境还得上 WTForms 这类表单验证库。5. 避坑指南Fyyur 从搭建到跑通的五个常见翻车现场5.1 数据库初始化不完整启动后报 no such table现象运行 flask run 后首页能打开但点击任意详情页时 SQLite 报错 no such table: show。原因数据库文件虽然生成了但表结构没有创建。很多初学者直接跑应用以为 SQLAlchemy 会自动建表但 Fyyur 里 create_all 可能只在某个特定入口调用或者需要手动执行迁移脚本。解决在 Flask shell 里手动创建全部表结构flask shellfrom app import db from models import Venue, Artist, Show db.create_all()执行完后再退出重启应用。注意 create_all 只负责建表不处理已有表的字段变更。如果你改了 models.py 里的字段定义需要删掉旧的数据库文件重建或者用 Flask-Migrate 做迁移。对这个体量的项目直接删 db 文件重建是效率最高的办法。5.2 表单提交后 404 或 405路由地址对不上现象填写完新场馆表单点击保存浏览器返回 405 Method Not Allowed。原因form 的 action 写的地址和 Flask 路由装饰器里的 methods 参数不一致。比如表单写 methodPOST但路由只写了 app.route(/venues/create)默认只能处理 GET 请求。解决打开对应模板文件确认 action 的路径和后端路由完全一致且路由方法的 methods 参数里包含 POST。app.route(/venues/create, methods[GET, POST]) def create_venue(): if request.method POST: # 处理提交逻辑 pass else: # 返回表单页面 pass一种常见的做法是一个路由同时处理 GET 和 POST——GET 时返回空表单POST 时处理提交逻辑。这样模板里的 action 就可以指向同一个地址也减少了路由数量。5.3 时间格式不对写入数据库报错现象新增演出信息时start_time 填写了 2024-06-01 这类格式提交后 SQLAlchemy 报错 ValueError: time data does not match format。原因HTML 的 datetime-local 输入框传给后端的是 2024-06-01T14:30 这种格式而你在后端直接用了 datetime.strptime 但格式串写错了。解决写一个专门的解析函数统一处理from datetime import datetime def parse_datetime(raw): # 兼容多种输入格式 for fmt in [%Y-%m-%dT%H:%M, %Y-%m-%d %H:%M:%S, %Y-%m-%d]: try: return datetime.strptime(raw, fmt) except ValueError: continue raise ValueError(f无法解析时间格式: {raw})前端 HTML 里对应的 input 标签要设置 typedatetime-local这样浏览器会给用户提供日期时间选择器输出格式也能被上面这个函数正确解析。Fyyur 的早期版本在时间处理上踩过不少坑一些提交的 issue 全是时间解析报错核心原因就这一个格式串不匹配。5.4 下拉框选项不显示或刷新后多出重复数据现象新增场馆页面的 state 下拉框是空的或者提交一次后列表里出现两条相同记录。原因下拉框空是因为后端没有把 states 列表传进 render_template或者模板里的变量名拼错了。重复数据则是表单被重复提交——用户在提交后刷新了页面浏览器重新发送了上一次的 POST 请求。解决第一个问题检查视图函数中 render_template 的第三个参数确认传了 statesstates。解决第二个问题在 POST 处理成功后使用 redirect而不是直接 render_templatereturn redirect(url_for(venues))这样做会发出一个新的 GET 请求用户刷新页面时重复的是 GET 而不是 POST数据库不会新增记录。这招叫 PRG 模式POST-Redirect-GET是 Web 开发里防重复提交的基本功。5.5 删除场馆时数据不同步出现孤立记录现象删除一个场馆后演出列表里还能看到这个场馆的演出记录点击详情时报错。原因Show 表里放着 venue_id 外键但删除 Venue 时没有处理关联的 Show 记录数据库又没有开启外键级联删除。解决在 relationship 定义时加上 cascadevenue db.relationship(Venue, backrefdb.backref(shows, cascadeall, delete))或者在删除前手动把关联的 Show 记录先删掉Show.query.filter_by(venue_idvenue_id).delete() db.session.delete(venue) db.session.commit()第二种方式更明确不会出现隐式行为。第一次做的时候你会觉得 cascade 很方便实际用多了就会发现最稳妥的永远是显式处理依赖关系代码跑得越久越认同这一点。6. 从项目到实战把 Fyyur 扩展成带用户登录的小系统如果你已经把 Fyyur 的基础增删改查跑通了下一步最有价值的提升方向是加入用户认证。Fyyur 本身没有登录注册模块但它的数据模型非常适合扩展——你可以把 User 表和 Venue、Artist 表关联起来做一个只有登录用户才能操作数据的版本。我用这个思路在自己的仿做项目里迭代过效果很好。第一步先在 models.py 加入 User 模型from flask_sqlalchemy import SQLAlchemy from werkzeug.security import generate_password_hash, check_password_hash db SQLAlchemy() class User(db.Model): __tablename__ user id db.Column(db.Integer, primary_keyTrue) email db.Column(db.String(120), uniqueTrue, nullableFalse) password_hash db.Column(db.String(128), nullableFalse) def set_password(self, password): self.password_hash generate_password_hash(password) def check_password(self, password): return check_password_hash(self.password_hash, password)第二步在路由层加登录装饰器。Flask 原生没有装饰器但你可以自己写一个非常简单的版本from functools import wraps from flask import session, redirect, url_for def login_required(f): wraps(f) def decorated_function(*args, **kwargs): if user_id not in session: return redirect(url_for(login)) return f(*args, **kwargs) return decorated_function app.route(/venues/create, methods[GET, POST]) login_required def create_venue(): # 原有逻辑 pass这套做法不依赖任何外部扩展只用 Flask 自带的 session 对象。登录成功后往 session 里写入 user_id登出时 pop 掉装饰器检查 session 里有没有这个键。你会发现 Fyyur 的代码结构本身就很适合这个扩展——所有敏感操作集中在几个 POST 路由里只要给这些路由加上 login_required整个系统的安全边界就拉起来了。第三体的验证方式是用实际数据跑一遍权限控制。我在本地验证时习惯用五个步骤走一遍保证任何改动都没把原有功能弄坏# 1. 启动服务 flask run # 2. 未登录访问新增场馆页面 curl -I http://localhost:5000/venues/new # 预期: 302 重定向到登录页 # 3. 注册新账号 curl -X POST http://localhost:5000/users/register \ -H Content-Type: application/x-www-form-urlencoded \ -d emailtestexample.compassword123456 # 4. 登录并保存 cookie curl -X POST http://localhost:5000/login \ -c cookies.txt \ -H Content-Type: application/x-www-form-urlencoded \ -d emailtestexample.compassword123456 # 5. 带 cookie 访问新增页面 curl -b cookies.txt http://localhost:5000/venues/new # 预期: 200 正常返回表单页面这套验证方法的逻辑是先确认未登录会被拦截再确认注册登录后能正常操作。几个命令跑完功能是否正常一目了然不用打开浏览器点半天。从那以后我每次接手类似的 Flask 课程设计都强制先按这个流程走一遍再动手改代码——权限有没有漏洞、表单能不能提交、数据库会不会报错十分钟内就能确认完。希望这份 Fyyur 的拆解对你有所帮助拿去用起来比躺在收藏夹里更有价值。本文还有配套的精品资源点击获取