第 03 章 项目结构与目录导航

学习目标

学完本章，你应该能：

1. 看懂 fba 后端的整体目录结构
2. 知道每个核心目录的职责
3. 修改代码时能快速定位到正确的位置

一、为什么要看懂目录结构

很多人上手新框架的第一障碍，就是"代码在哪？我该改哪里？"。fba 的目录结构是它最核心的价值之一——目录一看就懂，新人少踩坑。

官方社区评价：

"目录结构一看就懂，少解释很多。"

"统一分层的价值在于，不是每个人都按自己的习惯放代码，review 的时候少很多'这个应该放哪'的讨论。"

二、整体目录结构

fba 后端（backend/ 目录）的核心结构如下：

backend/                      # 后端工程根目录
├── alembic/                  # 数据库迁移（管理表结构版本）
├── app/                      # 应用（业务代码核心区）
│   ├── admin/                # 系统后台模块
│   │   ├── api/              # 接口层（路由）
│   │   ├── crud/             # 数据访问层
│   │   ├── model/            # 数据库模型
│   │   ├── schema/           # 数据校验模型
│   │   └── service/          # 业务逻辑层
│   └── task/                 # 异步任务（Celery）
├── common/                   # 公共资源（通用工具）
│   ├── model.py              # 通用数据库模型
│   ├── schema.py             # 通用 Schema
│   └── response/             # 响应相关
├── core/                     # 核心配置（conf.py 在这里）
├── database/                 # 数据库连接（redis.py 在这里）
├── locale/                   # 国际化语言包
├── log/                      # 日志
├── middleware/               # 中间件
├── plugin/                   # 插件目录
│   └── code_generator/       # 代码生成插件
├── scripts/                  # 脚本
├── sql/                      # 初始化 SQL 文件
├── static/                   # 静态文件
├── tests/                    # 测试
└── utils/                    # 工具包

目录结构全景图（按职责归类）

三、核心目录逐个讲

1. app/ —— 业务代码的核心区

这是你日常开发最常接触的目录。它遵循三层架构组织，每个业务模块内部又分：

子目录	职责	类比
api/	定义接口（路由），对接前端请求	前台接待
service/	写业务逻辑	业务主管
crud/	写数据库操作	数据搬运工
model/	定义数据库表结构	仓库货架设计
schema/	定义数据格式与校验	表单模板

这个"五件套"（model/schema/api/service/crud）就是 fba 三层架构的落地，第 04 章会详细拆解。

2. admin/ —— 内置后台模块

fba 已经内置了完整的系统后台（用户、角色、菜单、日志等），都在 app/admin/ 下。你可以：

• 直接使用这些现成功能
• 参考它的写法，开发你自己的业务模块

3. core/conf.py —— 全局配置中心

所有配置项集中在这里（数据库连接、Redis、token、时区等）。第 11 章专门讲配置系统。

4. database/ —— 数据库连接

• 数据库引擎、会话工厂
• redis.py：全局 Redis 客户端

5. middleware/ —— 中间件

请求进出都要经过的关卡，如 JWT 鉴权中间件、跨域中间件等。

6. common/ —— 通用资源

被各处复用的通用代码：

• model.py：通用模型基类（含时间戳、逻辑删除等 Mixin）
• schema.py：通用 Schema 基类（含驼峰转换等）
• response/：统一响应相关

7. sql/ —— 初始化 SQL 脚本

数据库初始化测试数据的 SQL 文件，按 mysql/ 和 postgresql/ 分目录存放。

四、一张图看懂请求流转

当浏览器/前端发起一个请求，它在 fba 里的流转路径：

这个"层层向下、逐层返回"的结构，就是三层架构的核心思想，下一章深入讲解。

五、如何快速定位代码

遇到问题时，按这个思路找：

想改什么	去哪个目录
接口路径/参数	app/xxx/api/
业务逻辑	app/xxx/service/
数据库操作	app/xxx/crud/
表结构	app/xxx/model/
数据校验	app/xxx/schema/
全局配置	core/conf.py

定位决策流程图

本章小结

关键要点回顾：

• 业务代码在 backend/app/，遵循 model/schema/api/service/crud 五件套组织
• core/conf.py 是全局配置中心
• common/ 放通用基类和工具
• 请求流转：中间件 → api → service → crud → 数据库
• 目录结构清晰是 fba 的核心竞争力之一

---

对应官方文档：项目结构（backend/summary/intro.html）、架构（architecture.html）