警告

fba 面向具备一定 Python 后端经验的开发者。如果你刚开始学习 FastAPI，建议先熟悉 Python 异步编程、FastAPI、SQLAlchemy 和 Pydantic 的基础用法

本地开发

1. 准备本地环境

   • Python 3.10+
   • 安装 uv（建议使用当前稳定版本）
   • PostgreSQL 16.0 + 或 MySQL 8.0+ 使用雪花主键 ID使用 MySQL

   • Redis（推荐最新稳定版）

2. 准备源码 二选一

   拉取源代码

   git clone https://github.com/fastapi-practices/fastapi-best-architecture.git

   创建模板仓库

   此项目支持创建模板仓库，你可以直接创建一个非 fork 的个人仓库。如图所示，进入此项目 GitHub 首页，使用 use this template 按钮创建

   创建完成之后，使用 git clone 命令拉取你自己的仓库即可

   

3. 启动 PostgreSQL/MySQL、Redis

4. 初始化

   自动

   在 根目录 打开终端，执行以下命令

   uv run fba init --auto

   手动

   1. 创建数据库：fba

      • PostgreSQL 用户直接创建
      • MySQL 用户创建时需选择 utf8mb4 编码

   2. env

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

      cp .env.example .env

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

   4. 安装依赖

      uv - sync

      uv sync

      uv - pip

      uv pip install -r requirements.txt

   5. 创建数据库表和测试数据 二选一

      CLI

      在 根目录 打开终端（确保已激活虚拟环境），执行以下命令

      fba init

      Alembic + 手动

      1. 在 根目录 打开终端（确保已激活虚拟环境），执行以下命令

         生成迁移文件

         fba alembic revision

         执行迁移

         fba alembic upgrade

      2. 初始化测试数据

         架构：执行 backend/sql/{mysql|postgresql}/ 目录下对应主键模式的脚本

         插件：执行 backend/plugin/{plugin}/sql/{mysql|postgresql}/ 目录下对应主键模式的脚本

         fba --sql 脚本文件路径

5. 启动

   在 根目录 打开终端（确保已激活虚拟环境），执行以下命令

   fba run

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

   在 根目录 打开终端（确保已激活虚拟环境），执行以下命令启动 celery 相关服务

   Worker

   fba celery worker

   Beat

   fba celery beat

   Flower

   fba celery flower

   注意

   如果从未执行过以上命令，任务结果表将缺失，此时，无论从何处调用任务结果相关接口都会直接报错，直到至少启动一次 worker 和 beat 服务，相关接口将自动恢复正常

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

开发流程

提示

使用 AI 辅助开发时，建议先安装 fba skills，再按 model、schema、router、service、crud 的顺序生成或审查代码

注

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

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

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

3. 定义路由（router）

4. 编写业务（service）

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

单元测试

相关信息

通过 pytest 运行单元测试。项目内仅提供基础测试示例，并不是完整业务测试套件；如需覆盖实际业务，请按项目需求补充测试用例

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

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

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

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

   pytest -vs --disable-warnings

编辑此页面

上一页简介

下一页为什么选择我们？