FastAPI入门练手项目如何对接SQL数据库存储用户数据

API 探路者

2026-8-27

改造实现难度

整体属于低门槛的入门级改造，只要你已经能独立写基础FastAPI接口，全程1-2小时就能跑通核心CRUD，没有陡峭的学习曲线。唯一需要提前了解的就是基础SQL表结构常识，不需要提前掌握很深的数据库专业知识。

具体实现方案

直接用FastAPI生态最成熟的搭配就行，不用折腾小众库：

开发阶段选SQLite作为数据库，不需要额外安装、启动数据库服务，数据直接存在本地文件里，天然持久化，等后续要上线的时候再切MySQL/PostgreSQL，代码改动量极小。ORM选SQLAlchemy，不想写裸SQL的时候直接调用封装好的方法，要写复杂原生SQL也支持，灵活度足够。
先装依赖：执行pip install sqlalchemy就行，如果你之前装的是精简版FastAPI，补装pip install fastapi[all]也可以。
替换原来的内存存储文件users_db.py，新建database.py做数据库连接配置，代码直接用下面这段即可：

from sqlalchemy import create_engine
from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy.orm import sessionmaker

# 数据库连接地址，SQLite会自动在项目根目录生成sql_app.db文件存所有数据
SQLALCHEMY_DATABASE_URL = "sqlite:///./sql_app.db"

engine = create_engine(
    SQLALCHEMY_DATABASE_URL,
    # 下面这个是SQLite专属的线程兼容配置，换其他数据库的时候删掉就行
    connect_args={"check_same_thread": False}
)
# 数据库会话工厂，每个请求单独拿一个会话操作数据库
SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
# 所有数据模型的基类
Base = declarative_base()

新建models.py定义用户表结构，把你之前存在字典里的用户字段全部映射成表字段即可，示例：

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

class User(Base):
    __tablename__ = "users"
    # 主键id，自增
    id = Column(Integer, primary_key=True, index=True)
    username = Column(String, unique=True, index=True)
    email = Column(String, unique=True, index=True)
    # 你之前存的其他字段比如密码哈希、昵称、注册时间之类的，照着这个格式加就可以

改main.py的启动逻辑，加两个内容：一是启动时自动根据模型创建数据库表，二是加数据库会话的依赖注入，方便所有接口拿数据库连接：

from fastapi import Depends
from sqlalchemy.orm import Session
from .database import engine, SessionLocal
from . import models, endpoints

# 应用启动时自动建表，开发阶段用足够，后续改表结构再上迁移工具
models.Base.metadata.create_all(bind=engine)

# 数据库会话依赖，每个请求结束自动关闭连接
def get_db():
    db = SessionLocal()
    try:
        yield db
    finally:
        db.close()

最后改endpoints.py里的接口逻辑，把之前读写users_db列表的代码全部换成数据库操作就行，思路和之前内存操作完全一致：比如原来查全量用户是直接返回列表，现在就是在接口参数里加db: Session = Depends(get_db)，然后执行db.query(models.User).all()返回结果；原来新增用户是往列表里append字典，现在就是创建User类的实例，db.add()之后db.commit()就存到库里了，删改逻辑同理，替换成本很低。

小提示：刚改造的时候不用急着上Alembic做数据库迁移，先把基础CRUD跑通，等需要频繁改表结构的时候再学迁移工具就行，一开始堆太多知识点容易卡壳。

参考学习路径

优先看FastAPI官方文档里的「SQL 数据库」章节，步骤和上面的方案完全对齐，就是针对你这种从内存存储转持久化的场景写的，没有冗余内容，跟着走一遍就能跑通。
CRUD跑通之后，用到什么查询语法就查SQLAlchemy的官方文档就行，比如条件过滤、分页、多表关联这些，不用一开始把所有语法全背下来。
等核心功能稳定了，再按需去看事务处理、索引优化、数据库迁移这些进阶内容，不用一开始就追求完美。

内容的提问来源于stack exchange，提问作者Serhei