---
url: /fastapi_best_architecture_docs/backend/summary/quick-start.md
---
::: caution
fba 面向具备一定 Python 后端经验的开发者。如果你刚开始学习 FastAPI，建议先熟悉 Python 异步编程、FastAPI、SQLAlchemy 和
Pydantic 的基础用法
:::

## 本地开发

:::: steps

1. 准备本地环境

   * Python 3.10+
   * [安装 uv](https://docs.astral.sh/uv/getting-started/installation/)（建议使用当前稳定版本）
   * PostgreSQL 16.0 + 或 MySQL 8.0+
     [使用**雪花主键 ID**](../reference/pk.md){.read-more}
     [使用 **MySQL**](../reference/db.md){.read-more}

2. 准备源码 

   ::: tabs
   @tab 拉取源代码

   ```shell:no-line-numbers
   git clone https://github.com/fastapi-practices/fastapi-best-architecture.git
   ```

   @tab 创建模板仓库

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

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

   ![use\_this\_template](/images/use_this_template.png)
   :::

3. 启动 PostgreSQL/MySQL、Redis

4. 初始化

   ::: tabs
   @tab 自动

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

   ```shell:no-line-numbers
   uv run fba init --auto
   ```

   @tab 手动

   1. 创建数据库：`fba`

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

   2. env

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

      ```shell:no-line-numbers
      cp .env.example .env
      ```

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

   4. 安装依赖

      ::: code-tabs
      @tab uv - sync

      ```shell:no-line-numbers
      uv sync
      ```

      @tab uv - pip

      ```shell:no-line-numbers
      uv pip install -r requirements.txt
      ```

      :::

   5. 创建数据库表和测试数据 

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

      ```shell:no-line-numbers
      fba init
      ```

      @tab Alembic + 手动

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

         生成迁移文件

         ```shell:no-line-numbers
         fba alembic revision
         ```

         执行迁移

         ```shell:no-line-numbers
         fba alembic upgrade
         ```

      2. 初始化测试数据

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

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

         ```shell:no-line-numbers
         fba --sql 脚本文件路径
         ```

      :::

5. 启动

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

   ```shell:no-line-numbers
   fba run
   ```

6. 启动 celery worker, beat 和 flower 

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

   ::: code-tabs
   @tab Worker

   ```shell:no-line-numbers
   fba celery worker
   ```

   @tab Beat

   ```shell:no-line-numbers
   fba celery beat
   ```

   @tab Flower

   ```shell:no-line-numbers
   fba celery flower
   ```

   :::

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

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

::::

## 开发流程

::: tip
使用 AI 辅助开发时，建议先安装 [fba skills](https://skills.sh/fastapi-practices/skills/fba)，再按 model、schema、router、service、crud 的顺序生成或审查代码
:::

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

::: steps

1. 定义数据库模型（[model](../reference/model.md)）

2. 定义数据验证模型（[schema](../reference/schema.md)）

3. 定义路由（[router](../reference/router.md)）

4. 编写业务（service）

5. 编写数据库操作（[crud](../reference/CRUD.md)）

:::

## 单元测试

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

::: steps

1. 创建测试数据库 `fba_test`，选择 utf8mb4 编码，PostgreSQL 用户可忽略编码
2. 创建数据库表，利用工具创建 `fba` 库所有表的 DDL 脚本，再通过 `fba_test` 库执行
3. 初始化测试数据，通过 `backend/sql/{mysql|postgresql}/` 目录下对应主键模式的脚本初始化测试数据
4. 在项目根目录打开终端，执行以下单元测试命令

   ```shell:no-line-numbers
   pytest -vs --disable-warnings
   ```

:::