快速入门 FastAPI 项目

项目结构分析

复制代码

backend/
  app/              # 主代码目录（重点看这里）
    models/         # 数据库模型 ⭐ 第3步看
    schemas/        # Pydantic 模型 ⭐ 第4步看
    routers/        # API 路由 ⭐ 第5步看
    crud/ 或 services/  # 数据库操作 ⭐ 第6步看
    config.py     # 管理所有配置项
    database.py     # 数据库连接配置
    main.py         # 入口文件 ⭐ 第1步看
  migrations/       # 数据库版本管理（自动生成，不用看）
  tests/            # 测试代码（学了再看）
  .env.example      # 环境变量示例 ⭐ 第2步看
  pyproject.toml    # 依赖配置 ⭐ 第2步看
  seed.py / seed.sql # 初始数据填充
  project_alpha.db  # SQLite 数据库文件

第1步：从入口文件开始 - 理解启动流程

找 main.py 或 app/__init__.py，通常在 backend/app/ 目录下：

bash 复制代码

backend/
  app/
    __init__.py      # 或者
    main.py          # 这是最常见的入口文件

看什么：

python 复制代码

# 典型的 main.py 结构
from fastapi import FastAPI
from app.routers import user, item  # 路由注册
from app.database import engine      # 数据库连接

app = FastAPI()

# 看这里注册了哪些路由
app.include_router(user.router)
app.include_router(item.router)

@app.on_event("startup")
def startup():
    # 启动时做什么
    pass

这一步让你知道：项目有哪些功能模块（通过 routers 看出）

第2步：看配置文件 - 理解项目依赖

找这些文件：

bash 复制代码

backend/
  .env.example      # 环境变量（数据库地址、密钥等）
  pyproject.toml    # 项目依赖（相当于 package.json）
  alembic.ini       # 数据库迁移配置

看什么：

.env.example → 复制成 .env，了解需要配置什么
pyproject.toml → dependencies 下面有哪些包
- fastapi + uvicorn → Web 框架
- sqlalchemy + alembic → 数据库 ORM
- pydantic → 数据验证
- httpx → HTTP 客户端

第3步：看数据模型 - 理解核心数据结构

找 models.py 或 app/models/ 目录：

bash 复制代码

backend/
  app/
    models/
      __init__.py
      user.py       # 用户表
      item.py       # 商品表
      order.py      # 订单表

看什么（SQLAlchemy 模型示例）：

python 复制代码

from sqlalchemy import Column, Integer, String
from app.database import Base

class User(Base):
    __tablename__ = "users"
    
    id = Column(Integer, primary_key=True)
    name = Column(String(50))
    email = Column(String(100), unique=True)

这一步让你知道：

数据库有哪些表
表之间如何关联（外键）
每个字段的类型和约束

第4步：看 Pydantic Schema - 理解 API 的输入输出

找 schemas.py 或 app/schemas/：

python 复制代码

from pydantic import BaseModel

# 请求体长什么样
class UserCreate(BaseModel):
    name: str
    email: str
    password: str

# 响应体长什么样
class UserResponse(BaseModel):
    id: int
    name: str
    email: str

对比 model 和 schema：

Model：对应数据库表（有 id、password 等）
Schema：API 暴露给外界的结构（可能隐藏 password）

第5步：看路由/接口 - 理解业务功能

找 routers/ 或 api/ 或 views/：

bash 复制代码

backend/
  app/
    routers/
      user.py       # /users 相关的接口
      item.py       # /items 相关的接口

看一个典型的路由文件：

python 复制代码

from fastapi import APIRouter, Depends, HTTPException
from sqlalchemy.orm import Session
from app import crud, schemas, models
from app.database import get_db

router = APIRouter(prefix="/users", tags=["用户"])

# GET 请求 - 获取列表
@router.get("/", response_model=list[schemas.UserResponse])
def get_users(
    skip: int = 0, 
    limit: int = 100,
    db: Session = Depends(get_db)
):
    users = crud.get_users(db, skip=skip, limit=limit)
    return users

# POST 请求 - 创建
@router.post("/", response_model=schemas.UserResponse)
def create_user(
    user: schemas.UserCreate, 
    db: Session = Depends(get_db)
):
    db_user = crud.get_user_by_email(db, email=user.email)
    if db_user:
        raise HTTPException(status_code=400, detail="Email already registered")
    return crud.create_user(db=db, user=user)

# GET 请求 - 获取单个
@router.get("/{user_id}", response_model=schemas.UserResponse)
def get_user(user_id: int, db: Session = Depends(get_db)):
    user = crud.get_user(db, user_id=user_id)
    if user is None:
        raise HTTPException(status_code=404, detail="User not found")
    return user

这一步让你知道：

有哪些 API 端点（GET/POST/PUT/DELETE）
每个接口需要什么参数
每个接口返回什么数据

第6步：看 CRUD 操作 - 理解数据库操作

找 crud.py 或 services/：

python 复制代码

from sqlalchemy.orm import Session
from app import models, schemas

def get_user(db: Session, user_id: int):
    return db.query(models.User).filter(models.User.id == user_id).first()

def get_user_by_email(db: Session, email: str):
    return db.query(models.User).filter(models.User.email == email).first()

def get_users(db: Session, skip: int = 0, limit: int = 100):
    return db.query(models.User).offset(skip).limit(limit).all()

def create_user(db: Session, user: schemas.UserCreate):
    fake_hashed_password = user.password + "notreallyhashed"
    db_user = models.User(
        email=user.email, 
        name=user.name,
        hashed_password=fake_hashed_password
    )
    db.add(db_user)
    db.commit()
    db.refresh(db_user)
    return db_user

这一步是项目的核心业务逻辑：如何从数据库读取/写入数据。

阅读步骤：

复制代码

第1步: app/main.py        ← 入口，看整体结构
   ↓
第2步: app/config.py      ← 配置，看环境变量
   ↓
第3步: app/database.py    ← 数据库连接，看 get_db()
   ↓
第4步: app/models/tag.py           ← 最简单的表
       app/models/ticket.py        ← 主表
   ↓
第5步: app/schemas/tag.py          ← 简单的数据结构
       app/schemas/ticket.py       ← 主要的 API 数据结构
   ↓
第6步: app/routers/tags.py         ← 简单的 API
       app/routers/tickets.py      ← 核心 API，看如何组合上面所有东西

实际操作步骤

bash 复制代码

# 1. 先找到 main.py
cd backend/app
ls -la
# 看看有没有 main.py 或者 __init__.py

# 2. 如果找不到，用 find 命令
find . -name "main.py" -o -name "__init__.py"

# 3. 查看目录结构
ls -R app/  # 递归列出所有文件

快速上手技巧

先改一个简单接口试试：
- 找一个 GET 接口
- 修改它的返回内容
- 重启服务看效果
跟着请求走一遍：
- 前端发起请求 → router 接收 → 调用 crud → 操作 model → 返回 schema
- 在 router 里打断点或加 print()，看数据流转