共用后端

两个项目维护同一套 FastAPI 后端。业务接口、数据库模型、认证权限、任务调度、文件能力和插件运行时只需要开发与验证一次，前端差异不会改变后端分层。

先回答三个问题

你想知道什么	先看哪里	看完应能完成什么
应用是怎样启动并接收请求的？	目录与分层、应用创建与生命周期	能从 `app.py` 追到 `server.py`、中间件、路由和 Lifespan
一个接口应该放在哪一层？	路由自动注册、新增业务模块	能创建 `module_<domain>`，并让路由被自动发现
线上问题该查配置、数据库还是任务？	环境与配置、数据库支持、定时任务与调度器、CLI 系统	能用同一套 `ruoyi` 命令定位配置、连接、迁移和任务状态

技术组成

能力	实现
Web 与接口文档	FastAPI、OpenAPI、Swagger UI / ReDoc
数据访问	SQLAlchemy 异步会话，支持 MySQL 与 PostgreSQL
参数校验	Pydantic 模型与字段校验装饰器
缓存与会话	Redis asyncio 客户端
认证	OAuth2、JWT、多终端登录状态
权限	接口权限、角色菜单权限和数据范围过滤
调度	后端 Scheduler 与任务日志
运维入口	`ruoyi` CLI、向导和 TUI
扩展	插件发现、检查、安装、启停、升级和卸载

后端目录地图

后端目录不是把所有代码都塞进 Controller、Service、DAO 四个全局文件夹，而是先按运行入口、公共基础设施、业务域、插件域和工程工具分区；只有普通业务域内部再按层组织。

text

ruoyi-fastapi-backend/
├── app.py                    # Python / Uvicorn 进程入口
├── server.py                 # FastAPI 应用工厂与 lifespan
├── config/                   # 环境配置与基础设施连接
├── common/                   # 路由、依赖、装饰器、上下文和公共模型
├── middlewares/              # ASGI / HTTP 中间件
├── exceptions/               # 业务异常与全局异常映射
├── sub_applications/         # 静态资源等子应用挂载
├── module_admin/             # 系统管理业务域
├── module_generator/         # 代码生成业务域与模板
├── module_plugin/            # 插件管理 API 入口
├── module_task/              # 调度器可调用的后台任务
├── plugins/
│   ├── core/                 # 插件宿主运行时
│   └── <plugin_id>/          # 可安装、启停的具体插件
├── utils/                    # 无业务归属的通用工具
├── cli/                      # ruoyi CLI、向导与 TUI
├── alembic/                  # 增量数据库迁移
├── sql/                      # MySQL / PostgreSQL 首次初始化
├── scripts/                  # 一次性维护与迁移脚本
├── tests/                    # 分层测试与运行时契约测试
├── docs/                     # 随后端源码维护的专题说明
├── assets/                   # 字体等受版本控制的静态资源
├── .env.*                    # 不同运行环境的配置入口
├── requirements*.txt         # 运行依赖
└── pyproject.toml            # ruoyi CLI 包与命令入口

按职责理解顶层目录

区域	目录或文件	在项目中的真实职责
进程与装配	`app.py`、`server.py`	`app.py` 交给 Uvicorn 启动应用工厂；`server.py` 创建 FastAPI、挂载子应用、注册中间件和异常处理、发现内置路由，并绑定插件运行时
基础设施	`config/`	加载 `.env.*`，创建数据库 Engine / Session、Redis 连接池和 Scheduler；它不是业务配置表的实现目录
Web 公共层	`common/`、`middlewares/`、`exceptions/`、`sub_applications/`	提供路由注册、鉴权与数据范围依赖、装饰器、请求上下文、统一响应、横切处理和静态资源挂载
普通业务域	`module_admin/`、`module_generator/`、其他 `module_<domain>/`	以业务域组织 Controller、Service、DAO、DO、VO；模块按真实职责选择需要的层次
插件域	`module_plugin/`、`plugins/core/`、`plugins/<plugin_id>/`	分别承担插件管理接口、宿主运行时、具体插件代码，三者不能互相替代
后台与运维	`module_task/`、`cli/`、`scripts/`	放置调度任务、日常运维命令以及一次性维护脚本，不参与普通 HTTP 分层
数据演进	`alembic/`、`sql/`	Alembic 管理已有环境的增量升级；SQL 文件用于首次初始化数据库
质量与说明	`tests/`、`docs/`、`assets/`	保存自动化测试、与源码同步的专题说明以及受版本控制的资源

容易混淆的目录

路径	应该放什么	不应该放什么
`common/`	多个模块共同依赖的框架能力，例如 `APIRouterPro`、鉴权依赖、数据范围、公共响应模型	只服务某一个业务域的规则
`utils/`	文件、时间、加密、JWT、Excel 等无状态或低状态通用函数	Controller、数据库查询或完整业务流程
`module_plugin/`	面向管理端的插件查询、安装、启停、升级和卸载接口	插件扫描、迁移、依赖校验等宿主底层实现
`plugins/core/`	插件发现、清单校验、生命周期、迁移、依赖策略、启动协调和路由防护	某个具体插件的业务功能
`plugins/<plugin_id>/`	插件自己的 Controller、Service、DAO、模型、迁移、种子数据和 `plugin.yaml`	宿主应用的通用业务代码
`module_task/`	可被 Scheduler 按模块路径调用的后台任务函数	请求入口和常规业务 API
`alembic/`	已部署数据库的版本迁移	新环境的一次性全量建库脚本
`sql/`	MySQL / PostgreSQL 初始结构和基础数据	日常增量变更的唯一记录

源码与运行产物

vf_admin/、logs/、build/、*.egg-info/、.pytest_cache/、.ruff_cache/、__pycache__/ 以及本地虚拟环境都是运行、构建或测试产生的内容，不属于后端目录架构本身。排查目录职责时应以受版本控制的源码为准，不要根据本机上传文件、日志或缓存反推项目结构。

请求处理链

一次典型的管理接口请求会依次经过以下处理环节：

Middleware 接收请求并建立公共上下文。
鉴权与数据范围依赖确认身份和可访问范围。
Controller 校验 HTTP 参数并声明权限契约。
Service 执行业务规则与事务编排。
DAO 组织最小查询或写入。
SQLAlchemy / Redis 读取或持久化数据。
统一响应模型封装结果并返回客户端。

Controller 负责 HTTP 契约和权限依赖，Service 负责业务规则，DAO 负责查询与持久化。目录依赖见目录与分层，中间件真实执行顺序见中间件与异常。

开发入口

后端目录与分层：真实目录、自动路由、分层依赖和新增业务模块的方法。
应用生命周期：资源初始化、Reload 与安全关闭。
环境与配置：.env.* 的配置分组和安全规则。
新增业务模块：Controller、Service、DAO 与事务闭环。
数据库支持与Alembic 迁移：双数据库开发与升级。
Redis 与系统缓存和定时任务：运行时后台能力。
CLI 系统：理解命令架构、环境上下文、结构化输出、安全保护、自动化和交互工具。
插件运行时：插件发现、校验、生命周期和启用路由。
初始化共用后端：第一次安装和启动。
Swagger、ReDoc 与路由检查：查看 OpenAPI、接口分组与路由巡检入口。

共用后端 ​

先回答三个问题 ​

推荐阅读路径 ​

技术组成 ​

后端目录地图 ​

按职责理解顶层目录 ​

容易混淆的目录 ​

源码与运行产物 ​

请求处理链 ​

开发入口 ​