第 02 章 环境准备与快速开始
学习目标
学完本章，你应该能：
- 了解运行 fba 需要哪些前置环境
- 掌握两种初始化方式（自动 / 手动）
- 成功启动后端服务并打开接口文档
一、前置知识要求
官方明确提示：fba 面向有一定 Python 后端经验的开发者。如果你刚开始学 FastAPI，建议先补这些基础：
- Python 异步编程（
async/await） - FastAPI 基础用法
- SQLAlchemy 基础用法
- Pydantic 基础用法
即使基础薄弱也没关系，本指南会在每个章节对必要概念做通俗解释，跟着走也能上手。
二、准备本地环境
你需要准备以下软件：
| 软件 | 版本要求 | 作用 |
|---|---|---|
| Python | 3.12+ | 运行语言 |
| uv | 最新稳定版 | 包管理工具（推荐，替代 pip） |
| PostgreSQL 或 MySQL | PostgreSQL 16.0+ / MySQL 8.0+ | 数据库 |
| Redis | 最新稳定版 | 缓存/内存库 |
补充：使用 MySQL 需注意数据库配置（详见官方文档「切换数据库」章节）；如需用雪花主键 ID，见「切换主键」章节。
名词解释
- uv：一个极快的 Python 包管理工具，fba 官方推荐用它来管理依赖。安装方法见官方说明。
- PostgreSQL / MySQL：两种主流关系型数据库，fba 都支持，二选一即可。
- Redis：内存数据库，用于缓存、存 token、限流计数等，跑 fba 需要它。
环境依赖关系图
三、准备源码（二选一）
方式 A：直接拉取源码
git clone https://github.com/fastapi-practices/fastapi-best-architecture.git方式 B：创建模板仓库（推荐用于自己的项目）
在 GitHub 项目首页点 Use this template 按钮，创建一个属于你自己的仓库（非 fork），然后 clone 你自己的仓库。这样你的项目就是独立的，方便长期维护。
区别：fork 出来的仓库还关联原项目，template 创建的是全新的独立仓库。
四、初始化项目
初始化前，先完成 第 0 步：启动 PostgreSQL/MySQL 和 Redis（否则后续建表、连库会失败）。
初始化本身有自动和手动两种方式。
方式一：自动初始化（最简单）
在项目根目录打开终端，执行：
uv run fba init --auto方式二：手动初始化（更可控，推荐理解原理）
手动初始化分 5 步，理解这 5 步，你就理解了 fba 启动的完整链路：
各步骤详细命令：
第 1 步：创建数据库
创建一个名为 fba 的数据库，MySQL 用户记得选择 utf8mb4 编码。
第 2 步：创建环境变量文件
进入 backend 目录：
cp .env.example .env第 3 步：修改配置
按需修改 backend/core/conf.py 和 .env（数据库连接信息在这里配置）。
第 4 步：安装依赖（二选一）
# 方式 a：uv sync（推荐）
uv sync
# 方式 b：传统 pip
uv pip install -r requirements.txt第 5 步：创建数据库表和测试数据（二选一）
执行以下命令前，确保已激活虚拟环境（在根目录打开终端）。
方式 a：CLI 命令
fba init方式 b：Alembic 迁移 + 手动脚本
# 生成迁移文件
fba alembic revision
# 执行迁移（建表）
fba alembic upgrade然后初始化测试数据（用 fba --sql 执行对应 SQL 脚本）。注意要区分两类脚本，且都按主键模式选择：
# ① 架构脚本：backend/sql/{mysql|postgresql}/ 目录下对应主键模式的脚本
fba --sql backend/sql/mysql/xxx.sql
# ② 插件脚本：backend/plugin/{plugin}/sql/{mysql|postgresql}/ 目录下对应主键模式的脚本
fba --sql backend/plugin/xxx/sql/mysql/xxx.sql为什么要分"架构脚本"和"插件脚本"？ 架构脚本初始化主工程的表和数据，插件脚本初始化你安装的插件所需的表和数据，两者缺一不可（装了插件才需要跑插件脚本）。
术语解释
.env文件：存放环境变量（如数据库密码、密钥）的配置文件，通过cp .env.example .env从模板复制而来。- Alembic：SQLAlchemy 官方的数据库迁移工具，用来管理数据库表结构的版本升级，相当于"数据库版本的 Git"。
五、fba CLI 命令行工具速览
fba 内置了便利的 CLI（命令行工具），安装依赖后即可使用。前面用到的 fba init、fba run、fba alembic、fba celery 都是它的子命令。
查看所有命令和帮助：
fba -h
# 或
fba --help常用命令分类：
| 命令 | 用途 |
|---|---|
fba init | 初始化数据库（建表 + 测试数据） |
fba run | 启动后端服务 |
fba alembic revision/upgrade | 数据库迁移（生成/执行迁移） |
fba celery worker/beat/flower | 启动 Celery 相关服务 |
fba --sql 脚本路径 | 执行 SQL 初始化脚本 |
提示：使用 AI 执行初始化、迁移、格式化、插件安装等流程时，建议在提示词中附上 fba skills，确保命令顺序与 fba CLI 约定一致。
六、启动服务
在根目录执行：
fba run启动成功后，打开浏览器访问：
http://127.0.0.1:8000/docs这里就是 FastAPI 自带的 Swagger 交互式文档，你可以直接在网页上测试接口。
七、可选：启动 Celery 服务
Celery 用于异步任务，初次学习可以跳过。需要时再启动：
# Worker：真正执行任务的进程
fba celery worker
# Beat：定时调度器，按计划触发任务
fba celery beat
# Flower：任务监控面板
fba celery flower注意：如果从未启动过 worker 和 beat，任务结果表会缺失，调用任务相关接口会报错，至少启动一次后自动恢复。
八、开发流程（重要，先记住框架）
fba 官方推荐的标准开发流程（开发一个新业务模块时按此顺序）：
这个流程从第 05 章开始会逐个详解。务必先记住这个顺序，它是 fba 开发的"主干线"。
官方补充提示：
- 使用 AI 辅助开发时，建议先安装 fba skills，再按 model、schema、router、service、crud 的顺序生成或审查代码。
- 此顺序仅供参考，实际以个人开发习惯为准。
九、单元测试（进阶了解）
fba 集成了 pytest，运行测试需要以下步骤：
- 创建测试数据库
fba_test：选择 utf8mb4 编码（PostgreSQL 用户可忽略编码） - 创建数据库表：利用工具生成
fba库所有表的 DDL 脚本，再通过fba_test库执行 - 初始化测试数据：通过
backend/sql/{mysql|postgresql}/目录下对应主键模式的脚本初始化 - 执行测试：在项目根目录打开终端，执行：
pytest -vs --disable-warnings注意：官方提示，项目内仅提供基础测试示例，并不是完整的业务测试套件。如需覆盖实际业务，请按项目需求自行补充测试用例。
DDL 脚本：Data Definition Language（数据定义语言）脚本，即"建表语句"。可以把它理解为"数据库表结构的说明书"。
十、常见问题（FAQ）
Q1：自动初始化和手动初始化该选哪个？ 学习阶段建议先走一遍手动，理解每一步在做什么；实际项目用自动更省事。
Q2：fba init 和 fba init --auto 有什么区别？--auto 是"全自动"（含建库、建表、初始化数据等），fba init 需要先手动建库。
Q3：启动时报数据库连接失败怎么办？ 检查 .env 里的数据库地址、端口、用户名、密码是否正确，以及数据库是否已启动。
Q4：初始化测试数据时，架构脚本和插件脚本都要跑吗？ 主工程的架构脚本一定要跑；插件脚本只在安装了对应插件时才需要跑（没装插件就没有插件脚本）。
Q5：MySQL 和 PostgreSQL 的初始化脚本有区别吗？ 有。脚本按 backend/sql/mysql/ 和 backend/sql/postgresql/ 分目录存放，选你实际用的数据库对应目录即可。
本章小结
关键要点回顾：
- 环境：Python 3.12+、uv、PostgreSQL/MySQL、Redis
- 初始化最快路径：
uv run fba init --auto - 启动命令：
fba run，访问/docs查看接口文档 - 标准开发流程：model → schema → router → service → crud（务必记住顺序）
- 可选服务：Celery worker/beat/flower
你现在应该已经能把 fba 跑起来了。 下一章我们深入项目目录结构，搞清楚每个文件夹是干什么的。
对应官方文档：
快速开始（backend/summary/quick-start.html）