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:5432volumes:- 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 进行查询，效率稳定。2. 缓存策略
故事列表是典型的“读多写少”场景。Redis 缓存：将热门故事列表缓存 5 分钟。
缓存失效：当有新故事发布或点赞数变化时，删除对应 Key，下次请求重新加载。
注意：缓存穿透（查不存在的数据）可以通过布隆过滤器解决，但初期可以先加空值缓存。3. 全文搜索
如果故事多了，简单的 LIKE '%keyword%' 会导致全表扫描。进阶方案：集成 Elasticsearch 或 PostgreSQL 自带的 tsvector 全文搜索索引。对于中小型项目，PostgreSQL 的 tsvector 足够用，无需引入额外组件。4. 安全性加固XSS 攻击：前端渲染 Markdown 时，必须使用 DOMPurify 等库清洗 HTML，防止用户插入 script 窃取 Token。
SQL 注入：SQLAlchemy ORM 已经天然防御，但如果你写了原生 SQL，务必使用参数化查询，严禁字符串拼接。小结
通过【精彩小故事】这个项目，我们不仅仅实现了功能，更重要的是构建了一套可维护、可扩展的工程体系。
从目录结构的规范，到分层架构的解耦，再到数据库索引与缓存的优化，每一步都是为了解决“学会语法却不知怎么搭项目”的痛点。
你不需要一开始就写出完美的架构，但你需要知道哪里容易出问题。比如，你知道 JSON 字段灵活但查询难，你就该提前规划好标签筛选方案；你知道 LIMIT/OFFSET 慢，你就该考虑游标分页。
这种“预判风险”的能力，才是资深工程师与新手的分水岭。
还有什么不懂的？评论区留言挨个回。 比如你卡在 JWT 刷新逻辑上，或者 Vue 的状态管理怎么和后端同步，直接说，我针对性拆解。
