3步搞定精彩小故事一文搞懂从零搭建全栈项目

学会语法却不知怎么搭项目？这是很多开发者的通病。别急，今天带你一文搞懂如何从零搭建【精彩小故事】实战项目。咱们不整虚的，直接上代码，让你看懂项目骨架怎么搭。

项目目标与场景定位

咱们要做的不是一个简单的增删改查（CRUD）Demo，而是一个具备完整业务逻辑的“精彩小故事”发布与阅读平台。

核心功能拆解：

用户系统：注册、登录、JWT Token 鉴权。
故事管理：创建、编辑、删除故事，支持 Markdown 格式。
内容展示：首页列表、详情页、标签分类、热度排序。
交互功能：点赞、评论、收藏（预留接口）。

为什么选这个题材？ 在市政公用工程或者一般后端开发中，我们常遇到“需求模糊”的问题。比如甲方说“我要个故事板块”，具体要啥？字段怎么设计？性能怎么保证？通过这个【精彩小故事】项目，你能把“模糊需求”变成“清晰技术文档”。这正是从“写代码”到“做项目”的关键跨越。

技术栈选型：

后端：Python (FastAPI) + PostgreSQL
前端：Vue 3 + TypeScript
数据库：PostgreSQL (支持 JSONB 存储扩展字段)
部署：Docker Compose

选 FastAPI 是因为它自带 API 文档，适合快速迭代；选 PostgreSQL 是因为它的 JSONB 类型在处理灵活的故事元数据时非常强大。

目录结构与工程化规范

很多新手写代码像“乱麻”，今天加个文件，明天改个配置。我们要建立标准的工程化目录。

story-platform/
├── backend/
│   ├── app/
│   │   ├── __init__.py
│   │   ├── main.py           # 应用入口
│   │   ├── config.py         # 配置管理
│   │   ├── database.py       # 数据库连接
│   │   ├── models/           # ORM 模型
│   │   │   ├── __init__.py
│   │   │   ├── user.py
│   │   │   └── story.py
│   │   ├── schemas/          # Pydantic 数据校验
│   │   │   ├── __init__.py
│   │   │   ├── user.py
│   │   │   └── story.py
│   │   ├── routers/          # API 路由
│   │   │   ├── __init__.py
│   │   │   ├── auth.py
│   │   │   └── stories.py
│   │   └── services/         # 业务逻辑层
│   │       ├── __init__.py
│   │       └── story_service.py
│   ├── tests/                # 单元测试
│   ├── requirements.txt
│   └── Dockerfile
├── frontend/
│   ├── src/
│   │   ├── api/              # Axios 封装
│   │   ├── components/       # 公共组件
│   │   ├── views/            # 页面视图
│   │   └── store/            # Pinia 状态管理
│   ├── package.json
│   └── Dockerfile
├── docker-compose.yml
└── README.md

关键点解析：

分层架构：严格区分 routers（路由）、services（业务逻辑）、models（数据模型）。路由只负责接收请求和返回响应，业务逻辑全部下沉到 service 层。这样后续改需求，你只需要动 service 层，不用碰路由。
配置分离：config.py 使用 pydantic-settings 读取 .env 文件。千万不要把数据库密码硬编码在代码里，这是 Stack Overflow 上被问爆的安全问题之一。
前端 API 封装：所有 HTTP 请求统一在 api 目录下管理，便于统一处理错误拦截和 Token 刷新。

核心代码实现与逐行讲解

这里我们聚焦后端最核心的两个部分：数据模型定义 和 故事发布接口。

1. 数据模型 (Models)

使用 SQLAlchemy ORM。注意 Story 表的设计，我们加入 tags 字段支持 JSON 数组，以及 views 和 likes 用于热度排序。

# backend/app/models/story.py
from sqlalchemy import Column, Integer, String, Text, DateTime, JSON, ForeignKey
from sqlalchemy.orm import relationship
from datetime import datetime
from app.database import Baseclass Story(Base):__tablename__ = 'stories'id = Column(Integer, primary_key=True, index=True)title = Column(String(255), nullable=False, index=True)content = Column(Text, nullable=False)summary = Column(String(500), nullable=True) # 用于列表页展示tags = Column(JSON, default=list)             # 存储标签数组 ["python", "fastapi"]author_id = Column(Integer, ForeignKey('users.id'))views = Column(Integer, default=0)likes = Column(Integer, default=0)is_published = Column(Boolean, default=False) # 草稿状态created_at = Column(DateTime, default=datetime.utcnow)updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)# 关联用户author = relationship("User", back_populates="stories")

逐行注释重点：

index=True：在 title 和 author_id 上建立索引。因为我们要经常搜索标题和查看某人的故事，不加索引后期查询会慢到崩溃。
JSON 类型：PostgreSQL 的 JSON 字段非常灵活。以后如果想加“故事难度”、“预计阅读时间”等字段，不需要改表结构，直接往 JSON 里塞数据就行。
is_published：很多新手忽略“草稿”功能。实际上，用户写完一半不想发出去，这个字段能救命。

2. 数据校验 (Schemas)

FastAPI 的强大在于 Pydantic。我们定义输入和输出数据结构。

# backend/app/schemas/story.py
from pydantic import BaseModel, Field
from typing import List, Optional
from datetime import datetimeclass StoryBase(BaseModel):title: str = Field(..., min_length=5, max_length=100)content: str = Field(..., min_length=10)summary: Optional[str] = Field(None, max_length=500)tags: List[str] = Field(default_factory=list)is_published: bool = Falseclass StoryCreate(StoryBase):passclass StoryResponse(StoryBase):id: intauthor_id: intviews: intlikes: intcreated_at: datetimeupdated_at: datetimeclass Config:from_attributes = True # 允许从 ORM 对象转换为 Pydantic 模型

避坑指南：

Field(..., min_length=5)：强制校验。防止用户提交空标题或过短内容，减少脏数据。
from_attributes = True：这是 Pydantic v2 的新特性（v1 是 orm_mode）。必须加上，否则 FastAPI 无法自动将数据库查询到的 SQLAlchemy 对象转换为 JSON 返回给前端。很多 Stack Overflow 的回答里，这个配置错误导致 500 错误的案例比比皆是。

3. 业务逻辑与路由 (Routers & Services)

我们将业务逻辑剥离到 services 层，保持路由整洁。

# backend/app/services/story_service.py
from fastapi import HTTPException, Depends
from sqlalchemy.orm import Session
from app.models import Story, User
from app.schemas.story import StoryCreate
from typing import Listdef get_stories(db: Session, skip: int = 0, limit: int = 10, tag: str = None) -> List[Story]:"""获取故事列表，支持分页和标签筛选"""query = db.query(Story)# 只查已发布的query = query.filter(Story.is_published == True)# 如果有标签筛选if tag:# PostgreSQL JSON 包含查询query = query.filter(Story.tags.any(tag))# 按热度排序（浏览量 + 点赞数）query = query.order_by((Story.views + Story.likes).desc())return query.offset(skip).limit(limit).all()def create_story(db: Session, story_in: StoryCreate, current_user: User) -> Story:"""创建故事"""# 业务校验：标题不能重复（简单实现，实际可加全文检索）existing = db.query(Story).filter(Story.title == story_in.title, Story.author_id == current_user.id).first()if existing:raise HTTPException(status_code=400, detail="Title already exists for this user")db_story = Story(**story_in.model_dump(), author_id=current_user.id)db.add(db_story)db.commit()db.refresh(db_story)return db_story

# backend/app/routers/stories.py
from fastapi import APIRouter, Depends, HTTPException, status
from sqlalchemy.orm import Session
from typing import List
from app.database import get_db
from app.services.story_service import get_stories, create_story
from app.schemas.story import StoryCreate, StoryResponse
from app.models.user import User
from app.core.security import get_current_userrouter = APIRouter(prefix="/api/stories", tags=["Stories"])@router.get("/", response_model=List[StoryResponse])
def read_stories(skip: int = 0,limit: int = 10,tag: str = None,db: Session = Depends(get_db),current_user: User = Depends(get_current_user) # 鉴权依赖
):return get_stories(db, skip=skip, limit=limit, tag=tag)@router.post("/", response_model=StoryResponse, status_code=status.HTTP_201_CREATED)
def create_story_endpoint(story_in: StoryCreate,db: Session = Depends(get_db),current_user: User = Depends(get_current_user)
):return create_story(db, story_in, current_user)

代码解读：

依赖注入 (Depends)：FastAPI 的核心灵魂。get_db 管理数据库会话生命周期，get_current_user 处理 JWT 解析和用户获取。路由函数变得非常干净，只关心“做什么”，不关心“怎么连数据库”和“怎么验证用户”。
JSON 查询：Story.tags.any(tag) 是 SQLAlchemy 对 JSONB 数组的查询语法。如果直接用 Python 的 in 操作，性能极差且容易出错。
事务控制：在 create_story 中，db.commit() 才是真正写入数据库。如果中间抛出异常，FastAPI 会自动回滚，保证数据一致性。

运行与测试策略

代码写完了，不能只靠 F5 跑起来就算完事。

1. 本地环境搭建

使用 docker-compose.yml 一键启动 PostgreSQL 和 Redis（如果用到缓存）。

# docker-compose.yml
version: '3'
services:db:image: postgres:15environment:POSTGRES_USER: adminPOSTGRES_PASSWORD: admin123POSTGRES_DB: story_dbports:- "5432:5432"volumes:- pgdata:/var/lib/postgresql/datavolumes:pgdata:

2. 自动化测试 (Pytest)

单元测试是保障重构信心的基石。我们测试最复杂的 get_stories 逻辑。

# backend/tests/test_stories.py
import pytest
from fastapi.testclient import TestClient
from app.main import app
from app.database import get_db
from app.models import Story, Userclient = TestClient(app)# 简单的 Fixture，创建测试数据
@pytest.fixture
def test_data(db_session):user = User(email="test@test.com", password="hashed_pass")db_session.add(user)db_session.commit()story1 = Story(title="Python FastAPI 入门", content="Content 1", author_id=user.id, is_published=True, views=100, likes=10)story2 = Story(title="Vue3 实战", content="Content 2", author_id=user.id, is_published=True, views=50, likes=5)db_session.add_all([story1, story2])db_session.commit()return user, [story1, story2]def test_get_stories_sorted_by_popularity(test_data, client):user, stories = test_data# 模拟登录获取 Token (此处省略具体 Token 生成逻辑，假设已存在)response = client.get("/api/stories/", headers={"Authorization": "Bearer test_token"})assert response.status_code == 200data = response.json()# 验证排序：story1 (110) 应该排在 story2 (55) 前面assert data[0]["id"] == stories[0].id

测试要点：

隔离性：每个测试用例使用独立的数据库会话，测试结束后回滚，互不干扰。
断言明确：不要只测 status_code == 200，要测数据内容、排序逻辑、边界条件（如空列表）。

优化扩展与性能瓶颈

项目跑通只是开始，真正的挑战在数据量上来之后。

1. 数据库查询优化

N+1 问题：在列表页，如果直接返回 Story 对象，FastAPI 序列化时可能会触发多次查询 User 信息。
- 解决方案：在 get_stories 中使用 joinedload 预加载作者信息。
```
from sqlalchemy.orm import joinedload
query = db.query(Story).options(joinedload(Story.author)).filter(...)
```
分页深翻页问题：LIMIT 100000 OFFSET 100000 在百万级数据下极慢。
- 解决方案：改用 Keyset Pagination（游标分页）。根据上一页最后一条记录的 id 或 created_at 进行查询，效率稳定。