工程实践4 · 第12讲  |  2025 春季学期

目录

Reflex 是什么？

Reflex 是一个纯 Python 全栈框架，让你无需编写 HTML/CSS/JavaScript，仅用 Python 即可构建交互式 Web 应用。

import reflex as rx

def index():
    return rx.text(
        "Hello, World!",
        color="indigo",
        font_size="2em",
    )

技术选型对比：Reflex vs Vaadin vs Spring Boot + Vue

维度	Reflex	Vaadin	Spring Boot + Vue
开发语言	纯 Python	Java（+ HTML/CSS 可选）	Java 后端 + JS/TS 前端
学习门槛	低（Python 入门友好）	中（需 Java OOP）	高（双语言双框架）
前后端分离	一体（Python 写全部 UI）	一体（Java 描述 UI）	分离（两套独立项目）
AI 代码生成	优（Python 训练数据最多）	中（Java 冗长）	中（需维护两端）
静态导出	reflex export	依赖 JVM 运行时	Vue 可静态，后端仍需 JVM
部署镜像体积	~25 MB（Nginx）	~500 MB+（JVM + JRE）	~200 MB（JVM + Node）
原型→产品衔接	无缝（同一套代码）	需重构	前后端分别重构
课程适配度

Reflex 架构剖析

┌──────────────────────────────────────────────────────────────────┐
│                        开发者（Python）                           │
│   rx.State  +  rx.Component  →  app.compile()                    │
└──────────────────┬───────────────────────────────────────────────┘
                   │ reflex run / reflex export
         ┌─────────▼─────────┐
         │   Reflex 编译器    │
         │  Python → Next.js │   .web/ 目录（临时构建产物）
         └─────────┬─────────┘
                   │
        ┌──────────▼──────────────────────────────┐
        │           运行模式选择                    │
        │                                          │
        │  ① reflex run       ② reflex export      │
        │    动态模式             静态导出模式       │
        │  FastAPI后端          纯静态 HTML/JS/CSS  │
        │  WebSocket 同步        无需后端进程        │
        │  支持 State 变更        适合无状态页面      │
        └─────────────────────────────────────────┘

静态导出 vs 动态运行

对比项	reflex run（动态）	reflex export（静态）
后端进程	需要 FastAPI 持续运行	不需要
WebSocket	实时双向通信	无
State 更新	完整支持	仅初始状态
部署复杂度	中（需管理进程）	低（Nginx 直接伺服）
适用场景	交互式仪表盘、表单	展示型页面、文档、原型
本课程原型	最终产品	当前阶段（原型验证）

AI 生成 Reflex 页面的方法论

三步工作法：描述 → 生成 → 约束

1. 写需求描述（自然语言）
        ↓
2. AI 生成 Reflex Python 代码
        ↓
3. 用约束文件（copilot-instructions.md）保证代码风格统一

帮我创建一个 Reflex 页面，
显示学生成绩统计卡片：
- 左侧：班级平均分（大字体）
- 右侧：成绩分布饼图
- 颜色：indigo 系
- 使用 rx.flex 布局

帮我做一个成绩页面
（太模糊，AI 会猜测框架、
样式、布局，容易不符合
项目已有规范）

Copilot 指令规范（copilot-instructions.md）

项目根目录的 .github/copilot-instructions.md 控制 AI 输出风格：

# 技术栈约束

## 前端
- 框架：Reflex（纯 Python，禁止直接写 HTML/CSS/JS）
- 样式：Tailwind CSS v3（通过 rx 组件的 class_name 参数传入）
- 图标：rx.icon()，Lucide 图标库
- 布局：优先使用 rx.flex、rx.grid，避免裸 div

## 命名规范
- State 类：PascalCase，继承 rx.State
- 页面函数：snake_case，返回 rx.Component
- 事件处理器：动词开头（handle_submit, toggle_modal）

## 禁止事项
- 禁止使用 JavaScript（含 rx.script）
- 禁止内联样式（style= 参数）
- 禁止 rx.html()（除非有正当理由）

典型 Reflex 页面结构

import reflex as rx
from ..components.navbar import navbar

# ① 状态类（数据 + 事件）
class GradeState(rx.State):
    avg_score: float = 87.5
    score_dist: list[dict] = [
        {"grade": "A", "count": 8},
        {"grade": "B", "count": 14},
    ]
    def refresh(self):   # 事件处理器，接入后端 API
        pass

# ② 子组件
def score_card(label: str, value: rx.Var) -> rx.Component:
    return rx.box(
        rx.text(label, color="gray", font_size="sm"),
        rx.text(value, font_size="3xl", color="indigo"),
        class_name="p-6 bg-white rounded-xl shadow-sm",
    )

# ③ 页面入口函数
def grades_page() -> rx.Component:
    return rx.vstack(
        navbar(),
        score_card("班级平均分", GradeState.avg_score),
        spacing="4", padding="6",
    )

AI 生成流程实战演示

提示词模板（复制即用）：

请用 Reflex 框架（Python）创建一个【页面名称】页面。

技术要求：
- 遵循 .github/copilot-instructions.md 规范
- 布局：三段式（顶部导航 + 左侧边栏 w-56 + 右侧主内容 flex-1）
- 配色：indigo-700/600（教师端）或 blue-600/500（学生端）
- 禁用 JavaScript，禁用内联样式

页面内容：
【在此描述你需要的 UI 元素、数据字段、交互行为】

参考文件：
- prototype/【对应原型文件名】.html（UI 原型参考）
- backend/models.py（数据模型参考）

reflex export 完整流程

# 在项目根目录执行
reflex export --no-zip

内部执行步骤：

Step 1: 收集所有 pages/*.py 中的页面函数
         ↓
Step 2: 生成 Next.js 项目到 .web/ 目录
         ↓
Step 3: 执行 next build（编译 React 组件）
         ↓
Step 4: 执行 next export（输出静态 HTML/JS/CSS）
         ↓
Step 5: 将产物复制到 .web/out/ 目录

产物结构：

.web/out/
├── index.html          # 首页
├── _next/
│   ├── static/css/     # 样式文件（Hash 命名）
│   └── static/chunks/  # JS 代码块（按路由分割）
└── dashboard/
    └── index.html      # /dashboard 路由页面

Docker 多阶段构建集成

# Stage 1: 构建（Python + Node.js）
FROM python:3.12-slim AS builder
WORKDIR /app
RUN apt-get update && apt-get install -y --no-install-recommends \
    curl nodejs npm && rm -rf /var/lib/apt/lists/*
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
RUN reflex export --no-zip          # 输出到 .web/out/

# Stage 2: 运行（仅 Nginx，~25 MB）
FROM nginx:alpine
COPY --from=builder /app/.web/out /usr/share/nginx/html
COPY nginx.conf /etc/nginx/conf.d/default.conf
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

镜像体积对比：

Nginx 配置：SPA 路由支持

# nginx.conf
server {
    listen 80;
    root /usr/share/nginx/html;
    index index.html;

    # 关键：所有路由回退到 index.html（SPA 路由）
    location / {
        try_files $uri $uri/ $uri.html /index.html;
    }

    # 静态资源强缓存（带 Hash 的文件永久缓存）
    location /_next/static/ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }

    # 安全头
    add_header X-Frame-Options "SAMEORIGIN";
    add_header X-Content-Type-Options "nosniff";
}

try_files 的作用：当用户直接访问 /dashboard 时，先找 /dashboard.html，找不到则回退到 index.html 让前端路由接管

CI/CD 自动化流程（GitHub Actions）

# .github/workflows/deploy.yml
name: 构建并部署到 Coolify
on:
  push:
    branches: [main]
jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: 安装 Python 依赖
        run: pip install -r requirements.txt
      - name: 生成静态资源
        run: reflex export --no-zip   # 核心步骤
      - name: 触发 Coolify 部署
        run: |
          curl -X POST \
            -H "Authorization: Bearer ${{ secrets.COOLIFY_API_TOKEN }}" \
            "${{ secrets.COOLIFY_WEBHOOK_URL }}"

CI/CD 自动化链路

从代码提交到上线的完整流程：

git push main
    ↓
GitHub Actions 触发（自动）
    ↓
reflex export --no-zip（生成 .web/out/）
    ↓
Docker 多阶段构建（Stage 1 build → Stage 2 Nginx）
    ↓
Coolify 拉取新镜像，滚动部署
    ↓
 https://oaepp.uwis.cn 上线新版本

每次 git push main → 约 3~5 分钟后自动上线，零人工干预。

规范开发流程：GitHub PR + Coolify Preview

强制要求：任何新功能 禁止 直接 push main，必须走 PR 流程：

① 创建 feature 分支
   git checkout -b feature/grade-report

② 本地开发 + 测试（reflex run / pytest）
   bash start_prototype.sh   # 原型对照验证

③ 推送 feature 分支，开 Pull Request
   git push origin feature/grade-report
   → GitHub → New Pull Request → base: main ← compare: feature/grade-report

④ Coolify 自动部署 PR Preview（独立预览环境）
   → https://pr-42.oaepp.uwis.cn  ← 验证效果

⑤ Preview 无问题 → Squash & Merge 到 main
   → Coolify 自动部署正式环境

最佳实践：Git Flow 开发规范

main         ──●────────────────────────────●── 生产（受保护分支）
                  \                        /
develop      ──────●──────────────────────●─── 集成测试
                    \        \           /
feature/*            ●──●─●   \         /      功能开发
                              \       /
release/*                      ●──●──●         预发布测试

本课程简化版：feature/* → PR Review → Merge to main，省略 develop/release 层，但 PR 保护不可省。

本讲要点总结

原型预览：VS Code 端口转发 + start_prototype.sh

核心原则：prototype/*.html 与 Reflex 编译输出 1:1 完全一致

原型 HTML 仅使用 Reflex 内置组件对应的 HTML 结构 + Tailwind CSS，
因此无需运行 Python，直接用浏览器打开静态 HTML 即可验证 UI 效果。

一行命令启动预览服务器：

bash start_prototype.sh          # 默认端口 8088
# 或指定端口
bash start_prototype.sh 9000

脚本自动完成三件事：

VS Code 端口转发（Remote / Codespaces 场景）：

① 终端运行：bash start_prototype.sh
② Ctrl+Shift+P → "Forward a Port" → 输入 8088
③ VS Code 底部「端口」面板 → 点击「在浏览器中打开」

参考资料

• Reflex 官方文档：https://reflex.dev/docs
• Marp 幻灯片文档：https://marp.app
• 项目仓库：https://github.com/roboticsystem/OA-EPP