fast_api_template/development.md

# FastAPI 项目 - 开发（Development）

## Docker Compose

* 使用 Docker Compose 启动本地 stack：

```bash
docker compose watch
```

* 启动后，你可以在浏览器中访问以下地址：

前端（通过 Docker 构建，基于路径路由）：<http://localhost:5173>

后端（基于 OpenAPI 的 JSON Web API）：<http://localhost:8000>

自动生成的 Swagger UI 交互文档：<http://localhost:8000/docs>

Adminer 数据库管理界面：<http://localhost:8080>

Traefik UI（查看代理如何路由请求）：<http://localhost:8090>

**注意**：第一次启动整个 stack 时，后端会等待数据库就绪并完成配置，这可能需要一点时间。你可以通过查看日志来确认进度。

在另一个终端中查看日志：

```bash
docker compose logs
```

查看某个特定服务的日志时，可以加上服务名，例如：

```bash
docker compose logs backend
```

## Mailcatcher

Mailcatcher 是一个简单的 SMTP 服务器，在本地开发过程中会拦截后端发出的所有邮件。邮件不会真正发送出去，而是通过 Web 界面展示。

它适用于：

* 在开发阶段测试邮件功能；
* 检查邮件内容与排版；
* 调试邮件相关逻辑，而无需发送真实邮件。

在本地使用 Docker Compose 运行时，后端会自动配置为使用 Mailcatcher（SMTP 端口为 1025）。所有被捕获的邮件可以在 <http://localhost:1080> 查看。

## 本地开发

Docker Compose 文件已经配置好，让每个服务在 `localhost` 上使用不同端口。

后端与前端使用的端口与其本地开发服务器一致：后端为 `http://localhost:8000`，前端为 `http://localhost:5173`。

这样你可以随时关闭某个 Docker 服务并启动本地开发服务器，其余服务仍能通过相同端口正常访问。

例如，想用本地 Vite 开发服务器，可以在另一个终端中停止 Docker 中的 `frontend` 服务：

```bash
docker compose stop frontend
```

然后启动本地前端开发服务器：

```bash
cd frontend
npm run dev
```

同样地，可以停止 Docker 中的 `backend` 服务：

```bash
docker compose stop backend
```

接着运行本地后端开发服务器：

```bash
cd backend
fastapi dev app/main.py
```

## 在 `localhost.tiangolo.com` 下使用 Docker Compose

启动 Docker Compose stack 时，默认使用 `localhost`，不同服务（后端、前端、Adminer 等）分别占用不同端口。

在生产（或预发布）环境中，每个服务通常使用不同子域名，例如后端使用 `api.example.com`，前端使用 `dashboard.example.com`。

在 [deployment.md](deployment.md) 中提到的 Traefik 就是用于根据子域名将请求转发到对应服务的反向代理。

如果你想在本地完整测试这套子域名路由方案，可以修改本地 `.env` 文件中的配置：

```dotenv
DOMAIN=localhost.tiangolo.com
```

该值会被 Docker Compose 用于配置各服务的基础域名。

Traefik 会将 `api.localhost.tiangolo.com` 的请求转发到后端，将 `dashboard.localhost.tiangolo.com` 的请求转发到前端。

`localhost.tiangolo.com` 是一个特殊域名，它及其所有子域名都指向 `127.0.0.1`，非常适合作为本地多子域名开发环境。

修改 `.env` 后，重新运行：

```bash
docker compose watch
```

在生产环境部署时，主 Traefik 一般在 Docker Compose 之外单独配置。本地开发时，`docker-compose.override.yml` 中包含了一个 Traefik 配置，仅用于测试如 `api.localhost.tiangolo.com` 与 `dashboard.localhost.tiangolo.com` 这样的本地域名是否按预期工作。

## Docker Compose 文件与环境变量

主配置文件 `docker-compose.yml` 包含整个 stack 的全部配置，`docker compose` 会自动读取它。

另外还有一个 `docker-compose.override.yml` 文件，专门用于开发环境的覆盖配置，例如将源代码目录挂载为 volume。`docker compose` 会自动将其作为 `docker-compose.yml` 的覆盖层进行合并。

这些 Docker Compose 文件会读取 `.env` 文件中的配置，并将其作为环境变量注入到容器中。

此外，在运行 `docker compose` 命令前，某些脚本可能会设置额外的环境变量供配置使用。

修改环境变量后，请记得重启 stack：

```bash
docker compose watch
```

## .env 文件

`.env` 文件包含所有配置、生成的密钥和密码等。

根据你的工作流程，你可能希望将其从 Git 中排除（尤其当项目是公开的）。在这种情况下，需要确保 CI 工具在构建或部署时能够获取到这些配置。

一种做法是：将每个环境变量添加到 CI/CD 系统中，并修改 `docker-compose.yml`，让它读取对应的环境变量，而不是从 `.env` 文件中读取。

## Pre-commit 与代码检查

本项目使用 [pre-commit](https://pre-commit.com/) 进行代码检查与格式化。

安装后，它会在每次 git commit 之前自动运行，确保代码在提交前就保持一致的风格和格式。

项目根目录下有一个 `.pre-commit-config.yaml` 配置文件，定义了所有检查规则。

#### 安装 pre-commit 以自动运行

`pre-commit` 已经作为项目依赖的一部分，你也可以按照 [官方文档](https://pre-commit.com/) 全局安装它。

安装好 `pre-commit` 工具后，需要在本地仓库"安装"它，使其在每次提交前自动执行。

使用 `uv` 的方式：

```bash
❯ uv run pre-commit install
pre-commit installed at .git/hooks/pre-commit
```

现在每次执行 commit 时，例如：

```bash
git commit
```

...pre-commit 都会运行，检查并格式化即将提交的代码，如果有修改会要求你重新 `git add` 这些文件后再提交。

然后你可以 `git add` 修改 / 修复的文件，再执行 commit。

#### 手动运行 pre-commit 钩子

你也可以手动对所有文件运行 `pre-commit`，使用 `uv` 的方式：

```bash
❯ uv run pre-commit run --all-files
check for added large files..............................................Passed
check toml...............................................................Passed
check yaml...............................................................Passed
ruff.....................................................................Passed
ruff-format..............................................................Passed
eslint...................................................................Passed
prettier.................................................................Passed
```

## 访问地址

生产或预发布环境使用相同的路径结构，只是替换为你自己的域名。

### 开发环境地址

以下是本地开发环境的地址。

前端：<http://localhost:5173>

后端：<http://localhost:8000>

自动生成的交互式文档（Swagger UI）：<http://localhost:8000/docs>

自动生成的备选文档（ReDoc）：<http://localhost:8000/redoc>

Adminer：<http://localhost:8080>

Traefik UI：<http://localhost:8090>

MailCatcher：<http://localhost:1080>

### 配置 `localhost.tiangolo.com` 后的开发地址

以下是本地开发环境的地址。

前端：<http://dashboard.localhost.tiangolo.com>

后端：<http://api.localhost.tiangolo.com>

自动生成的交互式文档（Swagger UI）：<http://api.localhost.tiangolo.com/docs>

自动生成的备选文档（ReDoc）：<http://api.localhost.tiangolo.com/redoc>

Adminer：<http://localhost.tiangolo.com:8080>

Traefik UI：<http://localhost.tiangolo.com:8090>

MailCatcher：<http://localhost.tiangolo.com:1080>