基于FastAPI和Vue的Python前后端分离题库系统架构设计

一、系统整体分层架构与职责划分

题库系统不仅要处理常规的内容管理（CRUD），还需要应对高频的试题检索、在线作答交互、复杂的公式与富文本展示，以及批量自动判分任务。若将所有逻辑混杂在单体后端中，极易因客观题评分密集计算或大量静态资源交互拖垮系统吞吐。因此，系统在整体设计上采用清晰的四层分离结构：表现层、网关与契约层、业务编排层与持久化存储层。

在上述分层中，前端采用基于 Vue 3 的单页面应用结构，重点解决交互体验与富文本表现问题；后端基于 FastAPI 配合 Uvicorn 构建，利用 Python 原生 asyncio 机制，在高频并发读写试卷时避免线程阻塞。

二、异构试题数据建模与 Pydantic 契约设计

题库系统最典型的设计难点是题型多样性。单选题、多选题、不定项题、填空题、客观问答题和代码编程题，其题目结构、选项格式、评分规则各不相同。传统关系型数据库若为每种题型单独建表，在组卷抽取时需要做大量多表联合查询；若将所有属性扁平化堆积在一张大表中，则会出现大量空字段。

在 PostgreSQL 搭配 FastAPI 的方案中，推荐采用“核心元数据关系列 + 题型载荷 JSONB 列”的混合建模策略：

from enum import Enum
from typing import List, Dict, Any, Optional, Union
from pydantic import BaseModel, Field
from datetime import datetime

class QuestionType(str, Enum):
    SINGLE_CHOICE = "single_choice"
    MULTIPLE_CHOICE = "multiple_choice"
    FILL_IN_BLANK = "fill_blank"
    CODE_JUDGE = "code_judge"

class BaseQuestionPayload(BaseModel):
    stem: str = Field(..., description="题干富文本或Markdown内容")
    analysis: Optional[str] = Field(None, description="答案解析")

class ChoicePayload(BaseQuestionPayload):
    options: List[Dict[str, str]] = Field(..., description="选项列表，如 [{'key': 'A', 'value': '...'}]")
    standard_keys: List[str] = Field(..., description="正确选项键，如 ['A'] 或 ['A', 'C']")

class CodeJudgePayload(BaseQuestionPayload):
    language: str = Field(..., description="评测语言 Python/Java/Go")
    time_limit_ms: int = Field(1000, description="执行时限")
    memory_limit_mb: int = Field(128, description="内存配额")
    test_cases: List[Dict[str, str]] = Field(..., description="输入输出测试样例")

class QuestionCreateSchema(BaseModel):
    type: QuestionType
    title: str = Field(..., max_length=200)
    difficulty: int = Field(1, ge=1, le=5, description="难度级别1-5")
    tags: List[str] = Field(default_factory=list)
    payload: Union[ChoicePayload, CodeJudgePayload] = Field(..., discriminator=None)

通过 Pydantic 的类型校验，传入后端的请求在到达业务代码前即可完成多态题型校验。前端提交的非法结构会在入口处被拦截并返回标准 422 Unprocessable Entity 结构，杜绝脏数据入库。

三、组卷引擎与异步判题核心处理流程

题库系统的两个核心业务动作为：根据规则抽取题目组成试卷，以及接收用户提交答卷后计算分值与正确率。在生产实践中，这两个步骤必须遵循明确的流水线操作：

1. 试卷快照（Snapshot）设计原则

题库系统绝不能直接在考试记录中只关联 question_id。因为老师或管理员后续极可能修改题干、修正错别字、甚至调换选项顺序。如果直接读取最新题库，已经完成答卷的学生成绩会发生剧烈波动甚至错位。

正确做法：在组卷确认发布的瞬间，由后端将所选题目在当刻的完整题干、选项、分值序列化为只读的 JSON 快照（paper_snapshot），并存入独立的试卷实体中。后续一切考生的作答与判分，严格与该快照数据绑定。

2. 异步判题与幂等交卷后端代码实现

from fastapi import APIRouter, Depends, HTTPException, BackgroundTasks, status
from sqlalchemy.ext.asyncio import AsyncSession
import redis.asyncio as aioredis

router = APIRouter(prefix="/api/v1/exams", tags=["Exam"])

@router.post("/{exam_id}/submit")
async def submit_exam_paper(
    exam_id: int,
    submission: ExamSubmissionSchema,
    background_tasks: BackgroundTasks,
    current_user: User = Depends(get_current_user),
    db: AsyncSession = Depends(get_db_session),
    redis_client: aioredis.Redis = Depends(get_redis)
):
    lock_key = f"submit_lock:{exam_id}:{current_user.id}"
    # 1. 依靠 Redis SetNX 实现接口级别 10 秒防重复提交幂等锁
    is_locked = await redis_client.set(lock_key, "1", nx=True, ex=10)
    if not is_locked:
        raise HTTPException(
            status_code=status.HTTP_429_TOO_MANY_REQUESTS,
            detail="交卷请求正在处理中，请勿重复点击"
        )

    # 2. 验证考试状态是否允许交卷
    exam_record = await get_user_exam_record(db, exam_id, current_user.id)
    if exam_record.status == "submitted":
        return {"status": "success", "message": "该试卷已完成提交"}

    # 3. 内存快速评测客观题，标记主观题
    objective_score, pending_tasks = evaluate_objective_items(
        exam_record.paper_snapshot, submission.answers
    )
    
    exam_record.objective_score = objective_score
    exam_record.status = "grading" if pending_tasks else "finished"
    await db.commit()

    # 4. 若存在代码评测或大模型主观判题，转入后台异步流水线
    if pending_tasks:
        background_tasks.add_task(
            dispatch_complex_judge,
            exam_record.id,
            pending_tasks
        )

    return {
        "status": "success",
        "exam_record_id": exam_record.id,
        "is_completed": not bool(pending_tasks),
        "preliminary_score": objective_score
    }

四、Vue 3 表现层架构与交互落地

在题库与答题交互中，前端不仅是一个显示模板，而要承担实时答题计时器、断网防丢单、富文本公式排版与代码高亮等关键职能：

1. 断网容灾与草稿自动保存策略

网络波动是在线考试中最常见的问题。Vue 3 组件在用户每次更改选项或在输入框失去焦点时，应触发 Pinia 状态管理器的变更。Pinia 不仅将答案保存在响应式对象中，同时立即利用 localStorage 写入当前 exam_id 的草稿副本。即使考生误关闭浏览器或突然断网刷新，页面重新加载时优先检测本地草稿与服务端同步版本，确保题目答案零丢失。

// stores/examStore.ts
import { defineStore } from 'pinia'
import { ref, watch } from 'vue'

export const useExamStore = defineStore('exam', () => {
  const currentExamId = ref<number | null>(null)
  const answers = ref<Record<number, any>>({})
  const remainingSeconds = ref<number>(0)

  // 初始化时优先读取本地离线草稿
  function initExam(examId: number, serverData: any) {
    currentExamId.value = examId
    const localDraft = localStorage.getItem(`exam_draft_${examId}`)
    if (localDraft) {
      answers.value = JSON.parse(localDraft)
    } else {
      answers.value = serverData.cachedAnswers || {}
    }
    remainingSeconds.value = serverData.remainingSeconds
  }

  // 监听答题变化，即时持久化到本地存储
  watch(answers, (newVal) => {
    if (currentExamId.value) {
      localStorage.setItem(`exam_draft_${currentExamId.value}`, JSON.stringify(newVal))
    }
  }, { deep: true })

  return { currentExamId, answers, remainingSeconds, initExam }
})

2. 公式与代码编辑器的模块化挂载

试题常涉及理科公式与代码块，全量引入庞大的渲染库会导致首屏加载异常缓慢。采用动态异步组件（defineAsyncComponent）挂载 Monaco Editor 或 KaTeX 渲染模块：只有当试卷包含相应题型时，才按需加载渲染引擎，将核心答题界面的初始包体积控制在合理范围。

五、全景架构选型与部署实践总结

为了保证前后端分离架构平稳上线并兼顾未来水平扩容能力，整套系统的技术选型优缺点及关键实施指标如下表所示：

综上所述，通过将复杂、变动的试题表现交由 Vue 3 前端及 Pinia 本地持久化管理，而把接口契约、安全脱敏、事务一致性与判分流水线交给 FastAPI 及其异步生态，系统既保留了面对新题型时的拓展灵活性，又在大型在线考试场景下具备稳定可控的吞吐表现。