这个博客没有做前后端分离,也没有用 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 的原因很直接:

  1. 博客主要用 Python 构建,FastAPI 成本低。
  2. 类型提示和 Pydantic 让请求参数、表单和配置的校验更清楚。
  3. 依赖注入适合处理数据库会话、登录状态这类横切逻辑。
  4. 自动生成的接口文档在调试时很方便,即使这个项目主要返回 HTML。
  5. 它基于 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 日志和浏览器页面。
  • 高并发、缓存、异步任务这些还没有接,后面需要再补。

项目地址:github.com/DenJeb/Denjeb-s-personal-blog