基于 SQLModel 的 FastAPI 基础应用开发指南

一、环境准备

1. 安装依赖

pip install fastapi uvicorn sqlmodel

（SQLite 无需额外驱动，如需使用 PostgreSQL 需安装 psycopg2-binary）

2. 项目结构

fastapi-sqlmodel-demo/ 
├── main.py # 主应用入口 
└── models.py # 数据模型定义

二、核心代码实现

1. 数据模型定义 (models.py)

from sqlmodel import SQLModel, Field class Hero(SQLModel, table=True): 
id: int | None = Field(default=None, primary_key=True) name: str = Field(index=True, max_length=50) 
age: int | None = Field(default=None, index=True) 
secret_name: str = Field(min_length=3)

• table=True 标记该类为数据库表模型
• Field 定义字段属性（索引、长度限制等）

2. 数据库配置 (main.py)

from sqlmodel import create_engine, Session from fastapi import FastAPI, Depends 
# 数据库配置 
sqlite_url = "sqlite:///./heroes.db" 
engine = create_engine(sqlite_url, connect_args={"check_same_thread": False}) 
# 依赖注入会话 
def get_session(): 
with Session(engine) as session: 
yield session app = FastAPI()

3. 自动建表

@app.on_event("startup") 
def create_tables(): 
SQLModel.metadata.create_all(engine)

三、API 接口实现

1. 创建英雄

@app.post("/heroes/", response_model=Hero) 
def create_hero(hero: Hero, session: Session = Depends(get_session)): 
session.add(hero) 
session.commit() 
session.refresh(hero) 
return hero

• 自动验证请求数据
• 返回创建后的完整对象

2. 查询接口

@app.get("/heroes/", response_model=list[Hero]) 
def read_heroes( session: Session = Depends(get_session), offset: int = 0, limit: int = 10 ): 
return session.exec( select(Hero).offset(offset).limit(limit) ).all()

• 支持分页查询
• 自动转换为 Pydantic 模型

3. 单项操作

@app.get("/heroes/{hero_id}", response_model=Hero) 
def read_hero(hero_id: int, session: Session = Depends(get_session)): hero = session.get(Hero, hero_id) if not hero: 
raise HTTPException(status_code=404, detail="Hero not found") 
return hero @app.delete("/heroes/{hero_id}") 
def delete_hero(hero_id: int, session: Session = Depends(get_session)): 
hero = session.get(Hero, hero_id) if not hero: 
raise HTTPException(status_code=404) 
session.delete(hero) 
session.commit() 
return {"status": "success"}

四、运行与测试

1. 启动服务

uvicorn main:app --reload

2. 测试接口
   • 访问 Swagger UI：http://localhost:8000/docs
   • 使用示例请求：

curl -X POST "http://localhost:8000/heroes/" \ -H "Content-Type: application/json" \ -d '{"name": "钢铁侠", "secret_name": "托尼·斯塔克", "age": 48}'

五、技术特性解析

1. ORM 优势
   • 单一模型定义同时支持数据库操作和 API 验证
   • 自动类型转换和数据验证
   • 支持复杂关系模型（需扩展）
2. 最佳实践
   • 使用依赖注入管理数据库会话
   • 分离模型定义与业务逻辑
   • 通过 response_model 控制 API 输出

六、扩展建议

1. 生产环境优化
   • 改用 PostgreSQL/MySQL 数据库
   • 添加连接池配置
   • 实现异步操作（需调整引擎配置）
2. 功能扩展
   • 添加分页参数验证
   • 实现全局异常处理
   • 集成身份验证模块