# Fastapi_test

**Repository Path**: tkandy/fastapi_test

## Basic Information

- **Project Name**: Fastapi_test
- **Description**: No description available
- **Primary Language**: Python
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2024-11-25
- **Last Updated**: 2025-01-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# FastAPI + Tortoise-ORM 示例项目

## 项目简介

这是一个使用 FastAPI 和 Tortoise-ORM 构建的简单 API 项目。FastAPI 是一个现代、快速（高性能）的 Web 框架，用于构建 API，而 Tortoise-ORM 是一个异步 ORM，支持多种数据库。
![浏览编辑](images/s01.png)
![新增](images/s02.png)

另含一个双色球选号子项目
![输入图片说明](13%20backend/static/img/project.png)
#### **1. 概述**

本项目是一个基于 FastAPI 和 Tortoise-ORM 的简单应用，主要用于展示如何在 FastAPI 中集成 Tortoise-ORM 来进行数据库（示例用的数据库是PostgreSQL 17.2）操作。项目主要涉及以下几个部分：

*   **FastAPI 应用**：定义了 API 路由和启动配置。
*   **Tortoise-ORM 配置**：配置了数据库连接和模型。
*   **数据模型**：定义了数据库表结构。
*   **迁移文件**：记录了数据库的版本控制和迁移脚本。

#### **2. 文件结构**

    09 ORM/
    ├── db/
    │   └── models.py
    ├── migrations/
    │   └── models/
    │       ├── 0_20241208165711_init.py
    │       └── 1_20241208170340_update.py
    ├── main.py
    └── settings.py

#### **3. 代码详解**

##### 3.1 `main.py` - 主应用文件

```python
pythonimport uvicorn
from fastapi import FastAPI
from tortoise.contrib.fastapi import register_tortoise
from settings import TORTOISE_ORM  # 导入 config 字典

app = FastAPI()

# 注册数据库 连接 配置  ,  config 字典中包含了数据库的连接信息
register_tortoise(app=app, config=TORTOISE_ORM)

if __name__ == "__main__":
    uvicorn.run(
        "main:app",
        host="127.0.0.1",
        port=8000,
        reload=True,
        workers=1,
        log_level="debug",
    )
```

*   **导入模块**：导入了 FastAPI、uvicorn 和 Tortoise-ORM 相关模块。
*   **创建 FastAPI 实例**：创建了一个 FastAPI 应用实例 `app`。
*   **注册 Tortoise-ORM**：使用 `register_tortoise` 函数将数据库配置注册到 FastAPI 应用中。
*   **启动应用**：使用 uvicorn 启动 FastAPI 应用，配置了主机、端口、自动重载、工作进程数和日志级别。

##### 3.2 `settings.py` - 配置文件

```python
pythonimport os
from dotenv import load_dotenv

load_dotenv()

TORTOISE_ORM = {
    'connections': {
        'default':
        f"postgres://{os.getenv('DB_USER')}:{os.getenv('DB_PASSWORD')}@{os.getenv('DB_HOST')}:{os.getenv('DB_PORT')}/{os.getenv('DB_NAME')}"
    },
    'apps': {
        'models': {
            'models': ['db.models', 'aerich.models'],
            'default_connection': 'default'
        }
    },
    'use_tz': True,
    'timezone': 'Asia/Shanghai'
}
```

*   **加载环境变量**：使用 `dotenv` 模块加载 `.env` 文件中的环境变量。
*   **配置 Tortoise-ORM**：定义了 `TORTOISE_ORM` 字典，包含数据库连接信息、模型模块路径、时区等配置。

##### 3.3 `db/models.py` - 数据模型文件

```python
pythonfrom tortoise.models import Model
from tortoise import fields


class Student(Model):
    id = fields.IntField(pk=True)
    name = fields.CharField(max_length=50, description="姓名")
    pwd = fields.CharField(max_length=50, description="密码")
    sno = fields.CharField(max_length=20, description="学号")
    clas = fields.ForeignKeyField("models.Clas", related_name="students")
    courses = fields.ManyToManyField("models.Course", related_name="students")


class Clas(Model):
    id = fields.IntField(pk=True)
    name = fields.CharField(max_length=50, description="班级名称")


class Course(Model):
    id = fields.IntField(pk=True)
    name = fields.CharField(max_length=50, description="课程名称")
    teacher = fields.ForeignKeyField("models.Teacher", related_name="courses")
    addr = fields.CharField(max_length=50, description="上课地点", default="")


class Teacher(Model):
    id = fields.IntField(pk=True)
    name = fields.CharField(max_length=50, description="教师姓名")
    pwd = fields.CharField(max_length=50, description="密码")
    tno = fields.CharField(max_length=20, description="工号")
```

*   **定义模型类**：使用 Tortoise-ORM 定义了 `Student`、`Clas`、`Course` 和 `Teacher` 四个模型类。
*   **字段定义**：每个模型类中定义了相应的字段，包括主键、字符串字段、外键和多对多关系字段。

##### 3.4 `migrations/models/0_20241208165711_init.py` - 初始迁移文件

```python
pythonfrom tortoise import BaseDBAsyncClient


async def upgrade(db: BaseDBAsyncClient) -> str:
    return """
        CREATE TABLE IF NOT EXISTS "clas" (
    "id" SERIAL NOT NULL PRIMARY KEY,
    "name" VARCHAR(50) NOT NULL
);
COMMENT ON COLUMN "clas"."name" IS '班级名称';
CREATE TABLE IF NOT EXISTS "student" (
    "id" SERIAL NOT NULL PRIMARY KEY,
    "name" VARCHAR(50) NOT NULL,
    "pwd" VARCHAR(50) NOT NULL,
    "sno" VARCHAR(20) NOT NULL,
    "clas_id" INT NOT NULL REFERENCES "clas" ("id") ON DELETE CASCADE
);
COMMENT ON COLUMN "student"."name" IS '姓名';
COMMENT ON COLUMN "student"."pwd" IS '密码';
COMMENT ON COLUMN "student"."sno" IS '学号';
CREATE TABLE IF NOT EXISTS "teacher" (
    "id" SERIAL NOT NULL PRIMARY KEY,
    "name" VARCHAR(50) NOT NULL,
    "pwd" VARCHAR(50) NOT NULL,
    "tno" VARCHAR(20) NOT NULL
);
COMMENT ON COLUMN "teacher"."name" IS '教师姓名';
COMMENT ON COLUMN "teacher"."pwd" IS '密码';
COMMENT ON COLUMN "teacher"."tno" IS '工号';
CREATE TABLE IF NOT EXISTS "course" (
    "id" SERIAL NOT NULL PRIMARY KEY,
    "name" VARCHAR(50) NOT NULL,
    "teacher_id" INT NOT NULL REFERENCES "teacher" ("id") ON DELETE CASCADE
);
COMMENT ON COLUMN "course"."name" IS '课程名称';
CREATE TABLE IF NOT EXISTS "aerich" (
    "id" SERIAL NOT NULL PRIMARY KEY,
    "version" VARCHAR(255) NOT NULL,
    "app" VARCHAR(100) NOT NULL,
    "content" JSONB NOT NULL
);
CREATE TABLE IF NOT EXISTS "student_course" (
    "student_id" INT NOT NULL REFERENCES "student" ("id") ON DELETE CASCADE,
    "course_id" INT NOT NULL REFERENCES "course" ("id") ON DELETE CASCADE
);
CREATE UNIQUE INDEX IF NOT EXISTS "uidx_student_cou_student_0d222b" ON "student_course" ("student_id", "course_id");"""


async def downgrade(db: BaseDBAsyncClient) -> str:
    return """
        """
```

*   **初始迁移**：定义了创建所有表的 SQL 语句，包括 `clas`、`student`、`teacher`、`course` 和 `student_course` 表。
*   **回滚操作**：定义了回滚操作的 SQL 语句，但这里为空。

##### 3.5 `migrations/models/1_20241208170340_update.py` - 更新迁移文件

```python
pythonfrom tortoise import BaseDBAsyncClient


async def upgrade(db: BaseDBAsyncClient) -> str:
    return """
        ALTER TABLE "course" ADD "addr" VARCHAR(50) NOT NULL  DEFAULT '';"""


async def downgrade(db: BaseDBAsyncClient) -> str:
    return """
        ALTER TABLE "course" DROP COLUMN "addr";"""
```

*   **更新迁移**：定义了在 `course` 表中添加 `addr` 字段的 SQL 语句。
*   **回滚操作**：定义了删除 `addr` 字段的 SQL 语句。

#### **4. 知识点总结**

*   **FastAPI**：一个现代、快速（高性能）的 web 框架，用于构建 API。
*   **Tortoise-ORM**：一个异步 ORM，支持多种数据库，与 FastAPI 集成良好。
*   **环境变量**：使用 `.env` 文件管理敏感信息，如数据库连接信息。
*   **数据模型**：定义了数据库表结构，包括字段类型、关系等。
*   **数据库迁移**：使用迁移文件管理数据库 schema 的变更，确保数据一致性。

#### **5. 运行项目**

1.  **安装依赖**：

    ```python
    pip install fastapi uvicorn tortoise-orm
    ```
2.  **启动应用**：

    ```python
    python main.py
    ```
3.  **访问 API**： 打开浏览器或使用工具（如 Postman）访问 `http://127.0.0.1:8000`。

#### **6. 常见问题**

*   **数据库连接失败**：检查 `.env` 文件中的数据库连接信息是否正确。
*   **迁移失败**：确保数据库中有相应的权限，并且迁移文件中的 SQL 语句正确无误。
*   **API 调用失败**：检查 API 路由和请求参数是否正确。

#### **7. aerich知识**

1.  **初始化 aerich**： 在你的项目根目录下运行以下命令来初始化 `aerich`：

    ```python
    aerich init -t your_project.settings.TORTOISE_ORM
    ```

    这里的 `your_project.settings.TORTOISE_ORM` 是你的 Tortoise ORM 配置路径。
2.  **初始化数据库**： 接下来，你需要初始化数据库：

    ```python
    aerich init-db
    ```
3.  **创建模型类**： 在你的项目中创建模型类。例如，在 `models.py` 文件中定义你的模型：

    ```python
    pythonfrom tortoise import Model, fields

    class User(Model):
        id = fields.IntField(pk=True)
        username = fields.CharField(max_length=50)
        email = fields.CharField(max_length=100)

        class Meta:
            table = "users"
    ```
4.  **生成迁移文件**： 使用 `aerich` 生成迁移文件：

    ```python
    aerich migrate
    ```
5.  **应用迁移**： 最后，应用迁移文件来更新数据库结构：

    ```python
    aerich upgrade
    ```