警告

fba 仅适用于资深 Python 后端开发人员，如果您是非资深用户，建议使用 精简版

重要

我们建议新手用户从基础且简单的部分开始学习，这不仅是对自己学习负责的表现，也为未来顺利掌握这一架构奠定了坚实基础。欢迎加入我们的 Discord 社区，一起交流讨论！

最后，请务必认真阅读本文档，并严格按照文档的顺序启动项目，否则在启动过程中很可能会遇到各种问题。

本地开发

提示

如果您是 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 - pip

     uv pip install -r requirements.txt

     uv - sync

     uv sync --frozen

     pip

     pip install -r requirements.txt

   • 插件依赖

     执行 backend/scripts/init_plugin.py 文件安装插件依赖

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

5. 启动 Redis

6. env

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

   touch .env

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

   cp .env.example .env

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

8. 创建数据库表 三选一

   自动创建

   直接启动后端项目

   Alembic 迁移

   生成迁移文件

   alembic revision --autogenerate

   执行迁移

   alembic upgrade head

   SQL 脚本

   执行 backend/sql/ 目录下对应数据库的 create_tables.sql 脚本

9. 启动 celery worker, beat 和 flower 此步骤为可选

   在 backend 目录打开终端，执行以下创建启动 celery 相关服务

   Worker

   celery -A app.task.celery worker -l info

   Beat

   celery -A app.task.celery beat -l info

   Flower

   celery -A app.task.celery flower --port=8555 --basic-auth=admin:123456

10. 初始化测试数据

    执行 backend/sql/init_test_data.sql 脚本初始化测试数据

11. 启动 fastapi 服务

    相关信息

    此项目默认使用 CLI 启动服务，为了方便本地调试，你仍然可以选择在 IDE 中右键运行 run.py 文件

    注意

    如果你在项目中安装了 应用级插件，请务必使用 run.py 文件启动项目，否则，您将收到启动错误

    详情：fastapi/fastapi#13372 (comment)

    帮助

    fastapi --help

    开发模式

    fastapi dev main.py

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

开发流程

提示

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

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

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

3. 定义路由（router）

4. 编写业务（service）

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

单元测试

相关信息

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

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

2. 创建数据库表，执行 backend/sql/ 目录下对应数据库的 create_tables.sql 脚本

3. 初始化测试数据，执行 backend/sql/ 目录下对应数据库的 init_test_data.sql 脚本

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

   pytest -vs --disable-warnings

常见问题

请点击跳转查看：常见问题

版权所有

许可证：MIT