3步实现用户行为追踪：full-stack-fastapi-postgresql数据可视化指南

2026-02-05 04:44:10作者：蔡丛锟

你是否还在为用户行为数据分散在日志文件中难以分析而烦恼？是否需要一个轻量级方案实现从事件采集到数据可视化的全流程？本文将基于full-stack-fastapi-postgresql框架，通过数据模型扩展、事件跟踪实现和可视化看板搭建三个步骤，帮助你快速构建用户行为分析系统。读完本文你将获得：

自定义用户行为事件模型的设计方法
无侵入式事件跟踪API的实现方案
基于现有前端组件的数据可视化 dashborad 搭建指南

数据模型扩展：构建行为分析基础

用户行为分析的核心是建立结构化的事件记录系统。full-stack-fastapi-postgresql框架的数据库模型位于backend/app/models.py，我们需要扩展现有模型以支持事件跟踪。

事件模型设计

在现有User和Item模型基础上，添加Event模型记录用户行为：

class Event(SQLModel, table=True):
    id: uuid.UUID = Field(default_factory=uuid.uuid4, primary_key=True)
    user_id: uuid.UUID = Field(foreign_key="user.id", nullable=False)
    event_type: str = Field(max_length=50)  # 如"item_view", "item_create"
    resource_type: str = Field(max_length=50)  # 如"item", "user"
    resource_id: uuid.UUID
    timestamp: datetime = Field(default_factory=datetime.utcnow)
    metadata: dict | None = Field(default=None, sa_type=JSONB)
    user: User = Relationship(back_populates="events")

数据访问层实现

在backend/app/crud.py中添加事件CRUD操作：

def create_event(*, session: Session, event_in: EventCreate, user_id: uuid.UUID) -> Event:
    db_event = Event.model_validate(event_in, update={"user_id": user_id})
    session.add(db_event)
    session.commit()
    session.refresh(db_event)
    return db_event

def get_user_events(*, session: Session, user_id: uuid.UUID, skip: int=0, limit: int=100) -> list[Event]:
    statement = select(Event).where(Event.user_id == user_id).order_by(Event.timestamp.desc()).offset(skip).limit(limit)
    return session.exec(statement).all()

事件跟踪实现：无侵入式数据采集

API请求拦截器

利用FastAPI的依赖注入功能，在backend/app/api/deps.py中实现请求拦截器，自动记录API访问事件：

async def track_request(session: SessionDep, current_user: CurrentUser, request: Request):
    # 在请求处理后记录事件
    yield
    event_data = {
        "event_type": f"{request.method.lower()}_{request.url.path.split('/')[-1]}",
        "resource_type": request.url.path.split('/')[1] if len(request.url.path.split('/'))>1 else "unknown",
        "resource_id": request.path_params.get("id"),
        "metadata": {"path": request.url.path, "status_code": response.status_code}
    }
    create_event(session=session, event_in=EventCreate(**event_data), user_id=current_user.id)

关键操作埋点

在现有业务逻辑中添加关键事件跟踪，例如在backend/app/api/routes/items.py的创建物品接口中：

@router.post("/", response_model=ItemPublic)
def create_item(
    *, session: SessionDep, current_user: CurrentUser, item_in: ItemCreate
) -> Any:
    item = Item.model_validate(item_in, update={"owner_id": current_user.id})
    session.add(item)
    session.commit()
    session.refresh(item)
    
    # 记录物品创建事件
    create_event(
        session=session,
        event_in=EventCreate(
            event_type="item_create",
            resource_type="item",
            resource_id=item.id,
            metadata={"title": item.title}
        ),
        user_id=current_user.id
    )
    return item

数据可视化实现：从数据到决策

后端统计接口

扩展backend/app/api/routes/utils.py添加统计分析接口：

@router.get("/event-stats", response_model=dict)
def get_event_stats(session: SessionDep, current_user: CurrentUser, days: int=7):
    # 计算日期范围
    start_date = datetime.utcnow() - timedelta(days=days)
    # 查询事件统计
    statement = select(
        Event.event_type, 
        func.count(Event.id).label("count")
    ).where(
        Event.user_id == current_user.id,
        Event.timestamp >= start_date
    ).group_by(Event.event_type)
    results = session.exec(statement).all()
    return {"events": {row.event_type: row.count for row in results}}

前端可视化组件

利用现有前端框架，在frontend/src/routes/_layout/index.tsx中集成行为数据看板：

function Dashboard() {
  const { user: currentUser } = useAuth();
  const { data: eventStats } = useQuery({
    queryKey: ["event-stats"],
    queryFn: () => UtilsService.getEventStats({ days: 7 }),
  });

  return (
    <Container maxW="full">
      <Box pt={12} m={4}>
        <Text fontSize="2xl">User Activity Dashboard</Text>
        {/* 事件统计图表 */}
        <SimpleGrid columns={{ base: 1, md: 2 }} spacing={4} mt={6}>
          <Card>
            <CardBody>
              <Heading size="md">Event Distribution</Heading>
              <Box h="300px" mt={4}>
                <BarChart data={Object.entries(eventStats?.events || {}).map(([k, v])=>({name: k, count: v}))}>
                  <XAxis dataKey="name" />
                  <YAxis />
                  <Tooltip />
                  <Bar dataKey="count" fill="#8884d8" />
                </BarChart>
              </Box>
            </CardBody>
          </Card>
        </SimpleGrid>
      </Box>
    </Container>
  );
}