这是今天搭建的FastAPI Tortoise-ORM风格的后端 API 分层项目是 Python 异步后台通用规范目录下面逐个文件夹 / 文件说明作用一、app 核心业务包整个项目业务代码根目录1. app/apis路由接口层视图层存放所有接口路由文件按模块拆分如user.py、goods.py、login.py职责接收前端 HTTP 请求、参数校验、调用 service 业务逻辑、组装返回响应仅做请求转发不写复杂业务、不直接操作数据库典型代码APIRouter路由注册、接口函数、请求入参接收2. app/config配置文件层存放项目全局配置环境变量读取、数据库连接配置、JWT 密钥、跨域、日志、Redis、文件上传等全局参数配合根目录.env系列环境文件区分开发 / 测试 / 生产环境示例settings.py统一读取 env 配置导出全局配置对象供全项目导入3. app/core项目核心基础组件存放框架底层通用核心能力认证JWT 鉴权、登录权限校验中间件异常全局异常捕获处理器、统一错误返回格式中间件跨域中间件、请求日志中间件、限流中间件依赖注入公共依赖函数如获取当前登录用户启动事件应用启动 / 关闭钩子数据库连接、Redis 初始化4. app/models数据库模型层ORM 实体Tortoise-ORM 数据库实体模型每张数据库表对应一个 Model 类定义字段、主键、外键关联、索引只描述表结构不写业务逻辑示例User、Admin、Order 等数据表映射模型供 service 层调用操作数据库5. app/schemasPydantic 数据模型序列化 / 校验层分为两类 Schema入参 Schema接口请求参数校验登录账号密码、新增表单校验出参 Schema数据库 Model 转前端返回 JSON过滤敏感字段密码不返回作用强类型校验、数据格式化、隔离数据库实体与前端返回结构完全解耦 Model修改表结构不会直接影响接口返回格式6. app/services业务逻辑层核心业务处理项目业务逻辑全部写在这里分层核心apis 只调用 serviceservice 操作 models 数据库复杂计算、多表联查、事务、第三方接口调用短信 / OSS 支付、业务规则判断全部放此处单表简单 CRUD 封装复杂业务组合多个 model 操作保证 apis 简洁干净7. app/utils通用工具函数层无业务耦合的公共工具全项目可复用工具类日期处理、加密解密、文件处理、正则、分页工具、验证码生成第三方封装Redis 工具、OSS 文件上传、邮件发送、雪花 ID 生成器纯工具方法不依赖业务模块可单独抽离复用8. app/init.py包初始化文件一般用于导出全局对象路由实例、配置、数据库实例批量注册所有 apis 路由简化 main.py 代码二、根目录文件夹migrations数据库迁移文件Tortoise-ORM/Aerich 迁移工具生成记录数据表创建、字段修改、新增删除等版本记录命令aerich migrate生成迁移脚本aerich upgrade同步到数据库团队协作时统一管理表结构变更避免本地手动改库三、根目录配置文件.env / .env.dev / .env.test / .env.prod多环境环境变量文件dev本地开发环境本地数据库、调试日志test测试服务器环境prod线上生产环境正式数据库、关闭调试、加密密钥config 层读取对应文件不同环境切换数据库地址、密钥、开关.gitignore Git 忽略清单过滤虚拟环境、缓存、日志、本地 env、编译文件等不上传代码库main.py项目程序入口FastAPI 应用启动主文件创建 FastAPI 实例、注册全局中间件、全局异常处理加载配置、批量导入所有路由、生命周期事件注册本地启动命令入口python main.pypyproject.toml 现代 Python 项目配置文件Poetry/PyProject项目元信息、Python 版本限制、代码格式化ruff/black、linter 静态检查规则requirements.txt 项目依赖清单记录所有 pip 安装包及版本新环境一键安装bash运行pip install -r requirements.txttest_main.http IDE 接口测试文件PyCharm 内置 HTTP Client存放所有 API 测试请求不用 Postman直接在 IDE 发送请求调试接口分层调用流转标准执行流程前端 HTTP 请求 → apis 路由层 → service 业务层 → models 数据库层 数据校验由 schemas 完成全局能力由 core 提供配置由 config 读取工具由 utils 调用架构优势解耦分层接口、业务、数据库完全隔离改表不影响接口改前端返回只动 schemas易维护模块职责单一新增功能只需新增对应文件夹文件多环境适配env 多配置文件区分本地 / 测试 / 生产规范统一团队开发统一目录标准新人快速看懂项目结构适配异步 FastAPI 生态配合 Tortoise ORM 做高性能异步接口