# py-fastapi-server

**Repository Path**: jalontsui/py-fastapi-server

## Basic Information

- **Project Name**: py-fastapi-server
- **Description**: 个人demo用py-faseapi-server
- **Primary Language**: Unknown
- **License**: ISC
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-22
- **Last Updated**: 2026-05-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# FastAPI 省市级联动服务

基于 FastAPI + MySQL 8 的行政区划级联查询服务，支持中国省、市、区三级行政区划查询及历史版本管理。

---

## 目录

- [技术栈](#技术栈)
- [前置要求](#前置要求)
- [从零开始运行项目](#从零开始运行项目)
  - [1. 下载项目代码](#1-下载项目代码)
  - [2. 创建 Python 虚拟环境](#2-创建-python-虚拟环境)
  - [3. 安装项目依赖](#3-安装项目依赖)
  - [4. 配置数据库连接](#4-配置数据库连接)
  - [5. 创建 MySQL 数据库](#5-创建-mysql-数据库)
  - [6. 执行数据库迁移](#6-执行数据库迁移)
  - [7. 导入初始化数据](#7-导入初始化数据)
  - [8. 启动服务](#8-启动服务)
- [验证服务是否运行成功](#验证服务是否运行成功)
- [接口说明](#接口说明)
- [表结构设计](#表结构设计)
- [常见问题](#常见问题)

---

## 技术栈

| 组件 | 版本 | 用途 |
|------|------|------|
| Python | 3.9+ | 编程语言 |
| FastAPI | 0.111.0 | Web 框架 |
| Uvicorn | 0.30.0 | ASGI 服务器 |
| SQLAlchemy | 2.0.30 | ORM |
| Alembic | 1.13.1 | 数据库迁移 |
| MySQL | 8.0+ | 数据库 |
| PyMySQL | 1.1.1 | MySQL 驱动 |

---

## 前置要求

在开始之前，请确保你的电脑已安装以下软件：

1. **Python 3.9 或更高版本**
   - 验证命令：`python --version` 或 `python3 --version`
   - 如果未安装，请前往 [Python 官网](https://www.python.org/downloads/) 下载安装
   - ⚠️ **Windows 用户**：安装时请勾选 "Add Python to PATH"

2. **MySQL 8.0 或更高版本**
   - 验证命令：`mysql --version`
   - 如果未安装，请参考：
     - Windows：[MySQL Installer](https://dev.mysql.com/downloads/installer/)
     - macOS：`brew install mysql`
     - Ubuntu/Debian：`sudo apt install mysql-server`

3. **Git**（用于克隆代码）
   - 验证命令：`git --version`
   - 如果未安装，请前往 [Git 官网](https://git-scm.com/downloads) 下载

---

## 从零开始运行项目

### 1. 下载项目代码

打开终端（Windows 请使用 PowerShell 或 CMD），进入你想存放项目的目录，执行：

```bash
git clone <你的仓库地址>
cd fastapi-server
```

> 如果是直接下载的 ZIP 压缩包，请解压后进入文件夹。

### 2. 创建 Python 虚拟环境

**虚拟环境的作用**：把项目用到的 Python 包和系统全局环境隔离开，避免不同项目之间的依赖冲突。

#### Windows

```bash
# 创建虚拟环境（会在当前目录生成 .venv 文件夹）
python -m venv .venv

# 激活虚拟环境
.venv\Scripts\activate
```

激活成功后，命令行前面会出现 `(.venv)` 的标识，例如：

```
(.venv) C:\Users\xxx\fastapi-server>
```

#### macOS / Linux

```bash
# 创建虚拟环境
python3 -m venv .venv

# 激活虚拟环境
source .venv/bin/activate
```

激活成功后，命令行前面会出现 `(.venv)` 的标识，例如：

```
(.venv) user@host:~/fastapi-server$
```

> 💡 **提示**：之后所有 `pip` 和 `python` 命令都要在虚拟环境激活状态下执行。如果需要退出虚拟环境，输入 `deactivate` 即可。

### 3. 安装项目依赖

确保虚拟环境已激活（看到命令行前面有 `(.venv)`），然后执行：

```bash
pip install -r requirements.txt
```

这会自动安装 FastAPI、SQLAlchemy、Alembic 等所有需要的 Python 包。安装过程可能需要 1-3 分钟，请耐心等待。

### 4. 配置数据库连接

在项目根目录下有一个 `.env` 文件（如果没有请手动创建），填写你的 MySQL 连接信息：

```bash
# Windows
notepad .env

# macOS / Linux
nano .env
```

文件内容如下，请把 `你的密码` 替换成你的 MySQL root 密码：

```env
DB_HOST=localhost
DB_PORT=3306
DB_NAME=area_db
DB_USER=root
DB_PASSWORD=你的密码
```

> ⚠️ **注意**：`.env` 文件包含数据库密码，**请勿提交到 Git 仓库**，项目根目录的 `.gitignore` 已默认忽略该文件。

### 5. 创建 MySQL 数据库

登录 MySQL（会提示输入密码）：

```bash
mysql -u root -p
```

在 MySQL 命令行中执行：

```sql
CREATE DATABASE area_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
EXIT;
```

或者直接在系统终端中一行执行：

```bash
mysql -u root -p -e "CREATE DATABASE area_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
```

### 6. 执行数据库迁移

迁移的作用是根据代码中的模型定义，自动在数据库中创建对应的表结构：

```bash
alembic upgrade head
```

执行成功后，MySQL 中会自动创建 `provinces`、`cities`、`districts` 等数据表。

### 7. 导入初始化数据

执行以下命令，将省、市、区的初始数据导入数据库：

```bash
python init_data.py
```

导入完成后，你会看到类似 `成功导入 XX 条数据` 的提示。

### 8. 启动服务

```bash
uvicorn app.main:app --reload
```

参数说明：
- `--reload`：开发模式，代码修改后自动重启，方便调试。生产环境请去掉此参数。

看到如下输出即表示启动成功：

```
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO:     Started reloader process [xxx] using WatchFiles
INFO:     Started server process [xxx]
```

---

## 验证服务是否运行成功

1. **打开浏览器**，访问 http://127.0.0.1:8000/docs
2. 如果能看到 Swagger 风格的 API 文档页面，说明服务已成功运行
3. 点击接口旁边的 "Try it out" → "Execute" 即可测试接口

或者直接在终端用 curl 测试：

```bash
curl http://127.0.0.1:8000/api/v1/areas/provinces
```

如果返回 JSON 格式的省份列表，说明一切正常。

---

## 接口说明

| 接口 | 方法 | 路径 | 说明 |
|------|------|------|------|
| 健康检查 | GET | `/health` | 返回服务状态 |
| 查询省 | GET | `/api/v1/areas/provinces` | 查询所有当前有效的省级行政区 |
| 查询市 | GET | `/api/v1/areas/cities/{province_code}` | 查询指定省份下当前有效的市级行政区 |
| 查询区 | GET | `/api/v1/areas/districts/{city_code}` | 查询指定城市下当前有效的区级行政区 |

### 响应格式示例

```json
{
  "code": 0,
  "message": "success",
  "data": [
    {"code": "110000", "name": "北京市"}
  ]
}
```

---

## 表结构设计

### 设计原则

- **三张独立表**：`provinces`（省）、`cities`（市）、`districts`（区）
- **无外键约束**：表间关联通过 `province_code` / `city_code` 做逻辑关联，不建立 FOREIGN KEY
- **历史版本**：每张表包含 `effective_date`（生效日期）、`expiry_date`（失效日期）、`is_active`（是否当前有效）字段
- **主键**：`INT UNSIGNED AUTO_INCREMENT`

### 索引设计

- `uk_province_code` / `uk_city_code` / `uk_district_code`：国标编码唯一约束
- `idx_active_*`：按是否有效 + 父级编码查询，用于级联接口

---

## 常见问题

**Q1：提示 `python` 命令找不到？**
- Windows：请检查安装 Python 时是否勾选了 "Add Python to PATH"，或尝试使用 `py` 命令
- macOS/Linux：尝试使用 `python3` 代替 `python`

**Q2：提示 `pip` 命令找不到？**
- 尝试 `python -m pip` 或 `python3 -m pip` 代替 `pip`

**Q3：MySQL 连接失败？**
- 检查 MySQL 服务是否已启动
- 检查 `.env` 中的密码是否正确
- 检查 MySQL 端口是否为默认的 3306

**Q4：提示 `alembic` 命令找不到？**
- 请确认虚拟环境已激活（看到 `(.venv)` 标识）
- 确认已执行 `pip install -r requirements.txt`

**Q5：如何退出虚拟环境？**
```bash
deactivate
```

**Q6：如何重新进入虚拟环境？**
```bash
# Windows
.venv\Scripts\activate

# macOS / Linux
source .venv/bin/activate
```