这个博客没有做前后端分离,也没有用 Vue 或 React。页面由 FastAPI 直接返回服务端渲染好的 HTML,模板用 Jinja2,数据放在 MySQL 里。这篇文章只谈技术选型,以及这套方案适合什么、不适合什么。
整体结构
请求进入 FastAPI 后,路由负责查数据库,Jinja2 把数据填进模板,浏览器拿到的是完整的 HTML。CSS 和少量 JavaScript 作为静态文件提供,图片上传后也放在静态目录里。
技术栈大致是:
- Web 框架:FastAPI
- 模板:Jinja2
- 数据库:MySQL
- ORM 与迁移:SQLAlchemy 2.0 + Alembic
- Markdown:markdown-it-py + Pygments
为什么是 FastAPI
选择 FastAPI 的原因很直接:
- 博客主要用 Python 构建,FastAPI 成本低。
- 类型提示和 Pydantic 让请求参数、表单和配置的校验更清楚。
- 依赖注入适合处理数据库会话、登录状态这类横切逻辑。
- 自动生成的接口文档在调试时很方便,即使这个项目主要返回 HTML。
- 它基于 Starlette,需要的时候可以继续往异步、API、WebSocket 方向扩展。
FastAPI 的文档大多以 JSON API 为例,服务端渲染的写法需要多查 Starlette 和 Jinja2 的资料。但只要把 Request、TemplateResponse、表单和重定向这几件事用顺,写页面并不复杂。
为什么用 Jinja2 做服务端渲染
这是一个以内容为主的站点。页面不需要复杂的客户端状态,也不需要频繁的局部刷新,服务端渲染正好匹配这种场景:
- 浏览器拿到 HTML 就能显示,首屏不依赖 JavaScript。
- 搜索引擎和 RSS 抓取更直接。
- 不需要维护一套前端路由和 API 层。
- 部署简单:一个 FastAPI 进程、一个 MySQL、一组静态文件。
代价是交互体验不如单页应用,页面切换要重新请求;模板和 CSS 也需要自己维护。
为什么不做前后端分离
前后端分离适合团队协作、前端交互复杂、需要多端复用的项目。这个博客只有我一个人维护,功能以阅读和内容管理为主,拆成前后端会多出这些事情:
- 设计并维护一套 API
- 处理跨域、鉴权、会话
- 维护前端构建工具和依赖
- 处理 SSR/SEO 或预渲染
把 HTML 的生成放在 FastAPI 里,代码路径更短,调试也更直接。后台的登录、表单、上传都能用同一套 Session 和模板完成,不需要再写一套前端状态管理。
数据层:MySQL + SQLAlchemy + Alembic
MySQL 是我本来就在用的数据库,事务、索引、字符集这些概念比较熟。项目里用 SQLAlchemy 2.0 做 ORM,Alembic 管理表结构迁移。
这样做的好处是:
- 模型定义和查询都在 Python 里,类型提示比较完整。
- 表结构变化有版本记录,不靠手工改库。
- 以后加字段、加索引时,迁移脚本可以进 Git。
标签用 MySQL 的 JSON 字段存储,查询时用 JSON_CONTAINS。数据量不大时够用;如果以后标签查询变复杂,再考虑单独的标签表。
这套方案的代价
FastAPI + Jinja2 不是万能方案,它有自己的边界:
- 页面交互复杂时,原生 JavaScript 和模板会越来越难维护。
- 没有前端组件体系,重复的 UI 需要靠模板片段复用。
- 服务端渲染的调试要同时看 Python 日志和浏览器页面。
- 高并发、缓存、异步任务这些还没有接,后面需要再补。
评论
登录后评论
暂无评论。