# 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**: 2026-02-24

## 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. 克隆项目
```bash
# 克隆仓库
git clone <仓库地址> fastapi-stencil

# 进入项目目录
cd fastapi-stencil
```

### 2. 安装依赖
```bash
# 安装所有依赖（包括开发依赖）
poetry install

# 激活虚拟环境（可选）
poetry env activate

# 查看虚拟环境路径
poetry env info
```

### 3. 启动服务

#### 开发模式（推荐）
```bash
# 启动开发服务器（带热重载）
poetry run dev

# 输出示例：
# ============================================================
# 启动开发服务器
# 基础地址: http://127.0.0.1:8000
# API地址: http://127.0.0.1:8000/api/v1
# 文档地址: http://127.0.0.1:8000/api/v1/docs
# ============================================================
```

#### 生产模式
```bash
# 启动生产服务器
poetry run start
```

### 4. 访问地址
- **基础地址**: http://127.0.0.1:8000
- **API地址**: http://127.0.0.1:8000/api/v1
- **API文档**: http://127.0.0.1:8000/api/v1/docs
- **ReDoc文档**: http://127.0.0.1:8000/api/v1/redoc

### 5. 停止服务
- 按 `CTRL + C` 停止开发服务器

### 6. 快速启动命令
以下是项目的常用命令，方便快速操作：

| 命令 | 功能描述 |
|------|----------|
| `poetry run lint` | 检查代码问题 |
| `poetry run lint-fix` | 自动修复代码问题 |
| `poetry run fmt` | 格式化代码 |
| `poetry run fmt-imports` | 排序imports |
| `poetry run check` | 完整检查（lint + 格式 + import排序） |
| `poetry run dev` | 启动开发服务器（带热重载） |
| `poetry run start` | 启动服务器（生产模式） |
| `poetry run test` | 运行测试 |
----

### 配置*vscode*调试
在 `.vscode/launch.json` 中添加：
```json
{
  "version": "0.2.0",
  "configurations": [
    // 开发模式
    {
      "name": "🚀 开发服务器 (scripts.py dev)",
      "type": "debugpy",
      "request": "launch",
      "program": "${workspaceFolder}/scripts.py",
      "args": ["dev"],
      "console": "integratedTerminal",
      "justMyCode": false
    },
    // 生产模式
    {
      "name": "📦 生产服务器 (scripts.py start)",
      "type": "debugpy",
      "request": "launch",
      "program": "${workspaceFolder}/scripts.py",
      "args": ["start"],
      "console": "integratedTerminal",
      "justMyCode": true
    },
    // 运行测试
    {
      "name": "🧪 运行测试 (scripts.py test)",
      "type": "debugpy",
      "request": "launch",
      "program": "${workspaceFolder}/scripts.py",
      "args": ["test"],
      "console": "integratedTerminal",
      "justMyCode": false
    }
  ]
}

```

----
## 问题修复

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

### 解决Vscode无法解析导入“xxxxx”Pylance的问题
### 推荐配置
不需要手动设置 python.defaultInterpreterPath ，而是使用 VSCode 的自动检测功能：

1. 打开命令面板 ： Cmd+Shift+P (Mac) 或 Ctrl+Shift+P (Windows)
2. 输入并选择 ： Python: Select Interpreter
3. 选择对应环境 ：VSCode 会显示所有检测到的环境，包括 Poetry 虚拟环境

- 手动配置
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
```