从零构建FastAPI后端管理系统：新手详细教程

从零构建FastAPI后端管理系统：新手详细教程

本文将带你逐步解析一个基于FastAPI的后端管理系统，从项目配置到核心功能实现，每个文件的作用和代码细节都将详细讲解。

点击进入后端项目仓库https://gitcode.com/geyaliang/geeker-admin-js-fastapi 

特别提示：请务必对照项目代码进行阅读，项目中的代码是完整的，尤其是 README.md 文件能帮助你快速搭建出全栈环境，搭建好以后，登录--->系统管理--->账号管理模块进行研究。
在此向大家表示歉意，原本计划逐步详细讲解每个部分，但由于时间有限未能实现。不过不用担心，代码中包含了丰富的注释，再加上配套的前端项目，可以帮助你更好地理解和测试各个功能模块，逐步吸收和掌握这些内容。

一、项目入口：main.py

from contextlib import asynccontextmanager
from fastapi import FastAPI
from fastapi.staticfiles import StaticFiles
from internal.auth import router as auth_router
from middleware.cors_middleware import add_cors_middleware
from sqlmodel import SQLModel
from dependencies.database import engine

@asynccontextmanager
async def lifespan(app: FastAPI):
    # 应用启动时创建数据库表
    SQLModel.metadata.create_all(engine)
    yield  # 应用关闭时执行清理操作

app = FastAPI(lifespan=lifespan)
add_cors_middleware(app)  # 添加跨域支持
app.mount("/static", StaticFiles(directory="static"), name="static")  # 静态文件目录
app.include_router(auth_router, prefix="/geeker")  # 集成认证路由

关键点解析：

• @asynccontextmanager：管理应用生命周期，初始化时创建数据库表
• SQLModel.metadata.create_all()：自动生成数据库表结构
• add_cors_middleware：解决前端跨域请求问题
• mount("/static")：托管前端静态文件（如图片、CSS）

二、环境配置：config.env

SECRET_KEY=c2VjcmV0LWtleS1mb3ItaHMyNTYtand0LXNpZ25pbmc=
ALGORITHM=HS256
EXPIRE=330
SERVER_HOST=0.0.0.0
SERVER_PORT=6061

参数说明：

• SECRET_KEY：JWT签名密钥（Base64编码）
• ALGORITHM：加密算法类型
• EXPIRE：Token有效期（分钟）
• SERVER_HOST/PORT：服务监听地址和端口

三、配置加载：utils/config.py 

from dotenv import load_dotenv
import os
from pydantic_settings import BaseSettings

load_dotenv('config.env')  # 加载环境变量

class Settings(BaseSettings):
    SECRET_KEY: str = os.getenv('SECRET_KEY')
    ALGORITHM: str = os.getenv('ALGORITHM', 'HS256')
    ACCESS_TOKEN_EXPIRE_MINUTES: int = int(os.getenv('EXPIRE', 300))
    
    @property
    def BASE_URL(self):
        return f"http://{self.SERVER_HOST}:{self.SERVER_PORT}/"

settings = Settings()  # 全局配置单例

 设计亮点：

• 使用python-dotenv管理敏感配置
• @property动态生成BASE_URL
• 类型自动转换（如字符串转整型）

四、响应规范：utils/response_utils.py 

def response_value(data=None, msg="成功", code=200):
    return {"code": code, "data": data, "msg": msg}

 使用示例：

# 成功响应
return response_value(data={"user_id": 1})

# 错误响应
return response_value(code=400, msg="密码错误")

统一响应格式的优势：

• 前端处理逻辑标准化
• 错误信息传递更清晰
• 方便日志监控和分析

五、安全工具：utils/sysutils.py 

from passlib.context import CryptContext

pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")

def get_password_hash(password):
    return pwd_context.hash(password)  # 自动加盐

def verify_password(plain_password, hashed_password):
    return pwd_context.verify(plain_password, hashed_password)

安全实践：

• 使用bcrypt算法：抗彩虹表攻击
• 每次哈希生成不同的盐值
• 验证时自动处理盐值比对

六、文本处理：utils/txt_utils.py 

import os

def read_config(file_path):
    config = {}
    with open(file_path) as file:
        for line in file:
            line = line.strip()
            if line and not line.startswith('#'):
                key, value = line.split('=', 1)
                config[key.strip()] = value.strip()
    return config

# 示例：读取同级目录下的config.txt
config = read_config(os.path.join(os.path.dirname(__file__), 'config.txt'))

 文件格式要求：

# 注释行
DB_HOST=localhost
DB_PORT=3306

七、验证工具：utils/validate_utils.py

import re

def validate_email(email: str) -> bool:
    pattern = r'^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$'
    return bool(re.match(pattern, email))

def validate_mobile(mobile: str) -> bool:
    return mobile.isdigit() and len(mobile) == 11

 使用场景：

if not validate_email(user.email):
    raise HTTPException(400, "邮箱格式错误")

 八、数据库连接：dependencies/database.py

from sqlmodel import create_engine, Session
from dotenv import load_dotenv
import os

load_dotenv('config.env')
SQLITE_URL = f"sqlite:///{os.getenv('SQLITE_DB_PATH', 'database.db')}"

engine = create_engine(SQLITE_URL)

def get_session():
    with Session(engine) as session:
        yield session  # 生成器方式提供会话

SessionDep = Annotated[Session, Depends(get_session)]  # 依赖注入类型注解

扩展MySQL配置：

# 修改为MySQL连接
MYSQL_URL = f"mysql+pymysql://{user}:{password}@{host}:{port}/{dbname}"
engine = create_engine(MYSQL_URL)

九、跨域处理：middleware/cors_middleware.py

from fastapi.middleware.cors import CORSMiddleware

def add_cors_middleware(app):
    app.add_middleware(
        CORSMiddleware,
        allow_origins=["*"],  # 生产环境应限制为具体域名
        allow_credentials=True,
        allow_methods=["*"],
        allow_headers=["*"]
    )

 各参数作用：

• allow_origins：允许跨域的源列表
• allow_credentials：是否允许携带Cookie
• allow_methods：允许的HTTP方法（GET/POST等）
• allow_headers：允许的请求头

十、用户模型：models/auth.py 

from sqlmodel import SQLModel, Field, Session, select
from typing import Optional, List

class UserBase(SQLModel):
    username: str = Field(index=True, unique=True)
    email: str = Field(max_length=100)
    disabled: bool = False

class User(UserBase, table=True):
    id: Optional[int] = Field(default=None, primary_key=True)
    hashed_password: str = Field(nullable=False)

class UserCreate(UserBase):
    password: str  # 接收明文密码

def get_user(db: Session, username: str):
    return db.exec(select(User).where(User.username == username)).first()

 模型功能：

• 定义数据库表结构
• 实现用户查询方法
• 分离输入模型和存储模型

十一、认证路由：internal/auth.py 

from fastapi import APIRouter, Depends, HTTPException
from models.auth import User, get_user
from dependencies.database import SessionDep
from utils.sysutils import verify_password

router = APIRouter()

@router.post("/login")
async def login(form_data: OAuth2PasswordRequestForm = Depends(), 
               db: Session = Depends(get_session)):
    user = get_user(db, form_data.username)
    if not user or not verify_password(form_data.password, user.hashed_password):
        raise HTTPException(401, "用户名或密码错误")
    
    access_token = create_access_token(data={"sub": user.username})
    return {"access_token": access_token, "token_type": "bearer"}

# 其他路由：用户注册、信息修改、列表查询...

 路由功能：

• /login：用户登录获取Token
• /users/me：获取当前用户信息
• /users：用户列表查询（分页）

十二、项目说明：README.md

1.项目结构  

├── main.py             # 主入口
├── database.py         # 数据库配置
├── auth.py             # 认证路由
├── models/             # 数据模型
│   └── auth.py        
├── middleware/         # 中间件
│   └── cors_middleware.py
├── utils/              # 工具类
│   ├── config.py      
│   ├── response_utils.py
│   └── validate_utils.py
   

2.快速启动

pip install fastapi uvicorn 
pip install python-multipart pyjwt sqlmodel pymysql passlib==1.7.4 bcrypt==4.0.1 python-dotenv fastapi-static-files pandas openpyxl pydantic-settings

我的环境里面pip很多，就用这种方式写出来，如果是pycharm创建Fastapi项目，安装第二行的依赖即可。

3.接口文档

访问 http://localhost:6061/docs 查看Swagger文档

4.前端对接 

配套前端地址 https://gitee.com/ge-yaliang/geeker-admin-js

一定要看项目内的README.md，前端有的代码按照md文件里的覆盖粘贴即可。

开发总结

通过本项目，你已掌握以下技能：

1. FastAPI核心功能：路由、依赖注入、中间件
2. 安全实践：密码哈希、JWT认证
3. 数据库操作：SQLModel ORM使用
4. 项目配置：环境变量管理
5. 前后端协作：跨域处理、响应规范

下一步建议：

1. 添加日志记录（logging模块）
2. 实现文件上传接口
3. 集成单元测试（pytest）
4. 部署到云服务器（Docker容器化）

遇到问题怎么办？

1. 查看FastAPI官方文档
2. 在Gitee仓库提交Issue
3. 使用Postman调试接口