警告

fba 仅适用于资深 Python 后端开发人员，如果您是非资深用户，我们建议您从 精简版 开始学习

本地开发

提示

• 雪花主键 ID 用户，请先移步到 切换主键
• PostgreSQL 用户，请先移步到 切换数据库

1. 准备本地环境

   • Python 3.10+
   • MySQL 8.0+ 或 PostgreSQL 16.0 +

   • Redis 推荐最新稳定版

2. 准备 Git 仓库 二选一

   拉取源代码

   git clone https://github.com/fastapi-practices/fastapi_best_architecture.git

   创建模板仓库

   此项目支持创建模板仓库，意味着，你可以直接创建一个非 fork 的个人仓库，如图所示，进入此项目 GitHub 首页， 使用 use this template 按钮创建即可，创建完成之后，使用 git clone 命令拉取你自己的仓库即可

   

3. 安装依赖

   注意

   此项目使用 uv 作为项目管理器，您需要先 安装 uv， 如果您本地已经存在 uv, 建议将其升级至最新版本

   拉取项目到本地后，在项目根目录打开终端，执行以下命令安装架构依赖

   uv - sync

   uv sync --frozen

   uv - pip

   uv pip install -r requirements.txt

4. 创建数据库：fba，选择 utf8mb4 编码（PostgreSQL 用户可忽略编码）

5. 启动 Redis

6. env

   在 backend 目录打开终端，执行以下命令创建环境变量文件

   touch .env

   将初始化环境变量配置拷贝到环境变量文件中

   cp .env.example .env

7. 按需修改配置文件 backend/core/conf.py 和 .env

8. 创建数据库表 二选一

   自动创建

   跳过此步骤，启动 fba 后将自动创建

   Alembic 迁移

   生成迁移文件

   alembic revision --autogenerate

   执行迁移

   alembic upgrade head

9. 启动 celery worker, beat 和 flower 此步骤为可选，可直接跳过

   在 根目录 或 backend 目录 打开终端，执行以下命令启动 celery 相关服务

   Worker

   fba celery worker

   Beat

   fba celery beat

   Flower

   fba celery flower

10. 启动

    在 根目录 或 backend 目录 打开终端，执行以下命令启动 FastAPI 服务

    fba run

11. 初始化测试数据

    通过 backend/sql/ 目录下对应主键模式的脚本初始化测试数据

12. 打开浏览器访问：http://127.0.0.1:8000/docs

开发流程

提示

仅供参考，实际以个人开发习惯为准

1. 定义数据库模型（model）

2. 定义数据验证模型（schema）

3. 定义路由（router）

4. 编写业务（service）

5. 编写数据库操作（crud）

单元测试

相关信息

通过 pytest 运行单元测试，项目内仅提供了非常简易的 demo，并不是完整单元测试，如需要，请自行编写

1. 创建测试数据库 fba_test，选择 utf8mb4 编码，postgresql 用户可忽略编码

2. 创建数据库表，利用工具创建 fba 库所有表的 DDL 脚本，再通过 fba_test 库执行

3. 初始化测试数据，通过 backend/sql/ 目录下对应主键模式的脚本初始化测试数据

4. 在项目根目录打开终端，执行以下单元测试命令

   pytest -vs --disable-warnings