python AI WEB框架之fastAPI结构拆分
【摘要】 一、最简分层逻辑（核心 4 层）路由层 routers：接收请求、参数校验、返回响应，不写业务逻辑业务层 services：核心业务逻辑，调用数据库、第三方接口数据层 db/models/crud：模型定义、数据库增删改查公共层 core/schemas/utils：配置、Pydantic 模型、工具函数、依赖二、完整目录结构（推荐）plaintextfastapi_project/├── ...
一、最简分层逻辑（核心 4 层）
- 路由层 routers：接收请求、参数校验、返回响应，不写业务逻辑
- 业务层 services：核心业务逻辑，调用数据库、第三方接口
- 数据层 db/models/crud：模型定义、数据库增删改查
- 公共层 core/schemas/utils：配置、Pydantic 模型、工具函数、依赖
二、完整目录结构（推荐）
plaintext
fastapi_project/
├── main.py # 程序入口，注册路由、启动app
├── core/ # 核心配置
│ ├── config.py # 全局配置（数据库地址、密钥、跨域）
│ ├── security.py # JWT、密码加密、权限校验
│ └── dependencies.py # 全局依赖（登录鉴权、分页、日志）
├── db/ # 数据库相关
│ ├── base.py # 数据库基类、会话创建
│ ├── session.py # 数据库连接、get_db依赖
│ └── models/ # SQLAlchemy ORM模型
│ ├── user.py
│ └── goods.py
├── crud/ # 数据库操作封装（增删改查）
│ ├── base.py # 通用CRUD父类
│ ├── user_crud.py
│ └── goods_crud.py
├── schemas/ # Pydantic 序列化/校验模型
│ ├── user.py # 用户入参、出参模型
│ └── goods.py
├── routers/ # 接口路由（按模块拆分）
│ ├── __init__.py # 统一汇总所有路由
│ ├── user.py # 用户模块接口
│ └── goods.py # 商品模块接口
├── services/ # 业务逻辑层（复杂逻辑放这里）
│ ├── user_service.py
│ └── order_service.py
├── utils/ # 通用工具
│ ├── logger.py
│ ├── file.py
│ └── time.py
├── static/ # 静态文件
├── tests/ # 单元测试
└── requirements.txt
三、各层作用与代码示例
1. main.py 入口文件
只做初始化，不写接口逻辑
python
运行
from fastapi import FastAPI
from core.config import settings
from core.dependencies import cors_middleware
from routers import api_router
app = FastAPI(title=settings.PROJECT_NAME)
# 跨域
app.add_middleware(cors_middleware)
# 挂载所有路由
app.include_router(api_router, prefix="/api/v1")
if __name__ == "__main__":
import uvicorn
uvicorn.run(app, host="0.0.0.0", port=8000)
2. routers 路由层（只处理请求转发）
routers/user.py
python
运行
from fastapi import APIRouter, Depends
from schemas.user import UserCreate, UserResp
from services.user_service import create_user
from db.session import get_db
from sqlalchemy.orm import Session
router = APIRouter(prefix="/user", tags=["用户模块"])
@router.post("/add", response_model=UserResp)
def add_user(user_in: UserCreate, db: Session = Depends(get_db)):
# 只调用service，不写业务
return create_user(db=db, user_in=user_in)
routers/init.py 聚合路由
python
运行
from fastapi import APIRouter
from .user import router as user_router
from .goods import router as goods_router
api_router = APIRouter()
api_router.include_router(user_router)
api_router.include_router(goods_router)
3. services 业务层（核心逻辑）
services/user_service.py
python
运行
from sqlalchemy.orm import Session
from schemas.user import UserCreate
from crud.user_crud import user_crud
from core.security import hash_password
def create_user(db: Session, user_in: UserCreate):
# 业务逻辑：密码加密、重复校验、联动其他表
user_in.password = hash_password(user_in.password)
return user_crud.create(db, obj_in=user_in)
4. crud 数据操作层（纯数据库操作）
crud/user_crud.py
python
运行
from crud.base import CRUDBase
from db.models.user import User
from schemas.user import UserCreate, UserUpdate
class CRUDUser(CRUDBase[User, UserCreate, UserUpdate]):
def get_by_phone(self, db: Session, phone: str):
return db.query(User).filter(User.phone == phone).first()
user_crud = CRUDUser(User)
5. schemas 数据校验 / 序列化
分离入参（Create）、出参（Resp）、更新（Update），隔离数据库模型与前端交互
6. db 数据库层
- models：数据表 ORM 映射
- session：数据库连接池、会话依赖
get_db - base：公共模型基类（id、创建时间、更新时间）
7. core 全局核心
- config：读取.env 环境变量
- security：JWT 签发、密码加密、token 校验
- dependencies：全局依赖（登录校验、分页、统一异常捕获）
四、两种拆分方案选择
方案 1：按模块拆分（推荐，中大型项目）
routers/user、services/user、crud/user、schemas/user
方案 2：按功能分层（小型 demo）
不拆分模块，只分层 core /db/routers，所有逻辑写单个文件，适合简单工具接口
五、分层调用规范（单向依赖，禁止反向导入）
请求流向：
禁止：crud 导入 service、router 直接操作 crud、model 导入 schema
main → routers → services → crud → db.models
六、扩展补充
- 异常统一处理：core/exceptions.py，全局捕获异常统一返回格式
- 中间件：core/middleware.py（请求日志、耗时统计）
- 第三方接口：新建
clients/文件夹存放第三方 SDK（支付、OSS、短信） - 定时任务：单独
tasks/，使用 APScheduler，不和接口代码耦合
【声明】本内容来自华为云开发者社区博主，不代表华为云及华为云开发者社区的观点和立场。转载时必须标注文章的来源（华为云社区）、文章链接、文章作者等基本信息，否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容，欢迎发送邮件进行举报，并提供相关证据，一经查实，本社区将立刻删除涉嫌侵权内容，举报邮箱：
cloudbbs@huaweicloud.com
- 点赞
- 收藏
- 关注作者
评论（0）