# fastapi-stencil

**Repository Path**: jeromexiong/fastapi-stencil

## Basic Information

- **Project Name**: fastapi-stencil
- **Description**: 使用 python 的 web 框架fastapi编写模版，自动生成 api 文档。集成 jwt、redis、mysql
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-04-27
- **Last Updated**: 2025-04-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

## 环境配置
1. `mac`使用[homebrew](https://www.jianshu.com/p/b7b789a2ed2c)管理安装包，并且配置中文源
2. [pyenv](https://github.com/pyenv/pyenv#homebrew-on-macos)管理 Python 版本
3. [pipx](https://pipx.pypa.io/stable/)在独立的隔离环境中安装这些工具，从而避免它们干扰其他项目的依赖。默认会依赖最新的`python`版本
4. [poetry](https://python-poetry.org/docs/)管理安装依赖，类似于`npm`。

```shell
poetry add fastapi
poetry add greenlet --group test #将依赖关系分组到test组
```

## 官方文档
- [FastAPI](https://fastapi.tiangolo.com/zh/tutorial/) 比肩 GoLang 和NodeJS 的高并发服务器，以下三个依赖默认安装
- [Starlette](https://www.starlette.io/) 轻量级的 ASGI 服务器框架
- [Pydantic](https://pydantic-docs.helpmanual.io/) 类型检查库
- [Uvicorn](https://www.uvicorn.org/) 是用 Python 编写的 ASGI 服务器，它是 FastAPI 的默认服务器。

- [sqlmodel](https://sqlmodel.tiangolo.com/) 允许使用`Python`类来定义数据库表结构，并通过这些类与数据库进行交互。它基于[SQLAlchemy](https://www.sqlalchemy.org/)构建，同时集成了`Pydantic`的数据验证功能，使得我们在操作数据库时能够享受到更好的开发体验和数据安全性
- [aiomysql](https://aiomysql.readthedocs.io/en/stable/) mysql异步驱动
- [aioredis](https://aioredis.readthedocs.io/en/latest/) Redis异步缓存
- [passlib]()Passlib 是一个更高级的密码哈希库，它支持多种哈希算法（如 bcrypt、PBKDF2、Argon2 等）。需要安装数据支持库，如`bcrypt==4.0.1`或`argon2`。
- [celery](https://docs.celeryq.dev/en/stable/)Celery是一个简单的,灵活且可靠的,处理大量消息的分布式系统,专注于实时处理的异步任务队列,同时也支持任务调度
----

## 安装运行
1. 安装依赖`poetry install`
2. 激活虚拟环境`poetry env activate`
3. 配置虚拟环境解释器：使用`poetry env info`查看虚拟环境路径，在`.vscode`中配置`settings.json`。
```json
{
  "python.defaultInterpreterPath": "/Users/jerome/Library/Caches/pypoetry/virtualenvs/fastapi-stencil-D-dxz738-py3.13/bin/python3.13"
}
```
4. 在`src`目录下运行`poetry run fastapi dev app.py`启动项目 `or`运行`python app.py start`
```
 ╭────────── FastAPI CLI - Development mode ───────────╮
 │                                                     │
 │  Serving at: http://127.0.0.1:8000                  │
 │                                                     │
 │  API docs: http://127.0.0.1:8000/docs               │
 │                                                     │
 │  Running in development mode, for production use:   │
 │                                                     │
 │  fastapi run                                        │
 │                                                     │
 ╰─────────────────────────────────────────────────────╯
```
5. `CTRL + Z` to exit

- 设置访问端口 `fastapi run --port 8080`

### 配置*vscode*调试
```json
{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python 调试程序: FastAPI",
            "type": "debugpy",
            "request": "launch",
            "module": "uvicorn",
            "args": [
                "app:app",
                "--reload"
            ],
            "jinja": true
        }
    ]
}
```

----
## 问题修复

### 解决*poetry*拉取包失败的问题，从指定的 PyPi 镜像中拉取代码
```toml
[[tool.poetry.source]]
name = "mirrors"
url = "https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple/"
priority = "primary"
```

### 解决Vscode无法解析导入“xxxxx”Pylance的问题
1. 打开设置，搜索 `Analysis: Extra Path`s，添加包路径：`/Users/jerome/.local/pipx/venvs`。但是这种方式只解决报错，依然没有代码提示。
2. ***推荐***配置虚拟环境。需要项目在`vscode`根目录而不是其他二级目录。首先运行`poetry install`安装依赖，之后激活虚拟环境`poetry env activate`，然后`poetry env info`查看虚拟环境路径，并将虚拟环境配置在`settings.json`中，该方法配置的环境又代码提示。
```json
{
  "python.defaultInterpreterPath": "/Users/jerome/Library/Caches/pypoetry/virtualenvs/fastapi-stencil-D-dxz738-py3.13/bin/python3.13"
}
```

### `ModuleNotFoundError: No module named 'distutils'"`报错
`Python 3.12`已经移除了`distutils`模块，需要使用`setuptools`模块代替。
```shell
pip install setuptools
or
poetry add setuptools
```

### 异步aioredis连接时报错`TypeError: duplicate base class TimeoutError`报错
```shell
启动连接时会报一个TypeError: duplicate base class TimeoutError的错误
问了Copilot，说是兼容性问题，在 Python3.11 中，asyncio.TimeoutError 被移动到了 asyncio.exceptions 模块中，而 aioredis 库没有及时更新以适应这个变化。
所以我们找到aioredis目录下的exceptions.py文件，定位到14行代码
class TimeoutError(asyncio.TimeoutError, builtins.TimeoutError, RedisError):
    pass

所以我们修改为如下代码，即可运行
class TimeoutError(asyncio.exceptions.TimeoutError, RedisError):
    pass
```