# python_chat_microservices

**Repository Path**: yu-yantao/python_chat_microservices

## Basic Information

- **Project Name**: python_chat_microservices
- **Description**: 社交系统：基于 Python+Poetry+FastAPI 的分布式微服务架构
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-17
- **Last Updated**: 2025-10-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Python, Poetry, FastAPI, consul

## README

# Python Chat Microservices 项目

## 项目简介
本项目是一个基于 Python + FastAPI + SQLAlchemy + Consul 的轻量级聊天微服务架构，包含 3 个核心模块：
- **user-service**：用户服务（注册、登录、用户信息管理）
- **friend-service**：好友服务（添加好友、查询好友列表）
- **gateway-service**：网关服务（统一接口入口，转发请求到对应微服务）


## 前置环境准备
拉取项目前，需确保本地已安装以下软件，版本需符合要求（避免兼容问题）：
| 软件         | 版本要求       | 用途                     |
|--------------|----------------|--------------------------|
| Python       | 3.11+          | 运行微服务代码           |
| MySQL        | 8.0+           | 存储用户、好友数据       |
| Consul       | 1.15+          | 服务注册与发现（微服务通信依赖） |
| Git          | 任意版本       | 拉取项目代码             |
| Poetry       | 1.6+           | Python 依赖管理（项目统一用 Poetry 管理依赖） |


## 1. 拉取项目代码
```bash
# 克隆项目到本地
git clone https://你的仓库地址/chat-microservices.git
cd chat-microservices
```


## 2. 数据库配置（必做）
### 2.1 创建 MySQL 数据库
先登录本地 MySQL，创建 2 个数据库（分别供用户服务、好友服务使用）：
```sql
-- 登录 MySQL（命令行或可视化工具均可）
mysql -u root -p

-- 创建用户服务数据库（user_db）
CREATE DATABASE IF NOT EXISTS user_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

-- 创建好友服务数据库（friend_db）
CREATE DATABASE IF NOT EXISTS friend_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```


### 2.2 配置环境变量（.env 文件）
项目依赖环境变量存储敏感配置（如数据库密码），需在项目根目录创建 `.env` 文件，复制以下内容并修改为你的本地配置：
```env
# -------------------------- MySQL 配置 --------------------------
# MySQL 连接信息（替换为你的本地 MySQL 账号、密码、地址）
MYSQL_USER=root
MYSQL_PASSWORD=你的MySQL密码（如123456）
MYSQL_HOST=localhost  # 本地运行填localhost，远程数据库填对应IP
MYSQL_PORT=3306       # MySQL 默认端口

# 数据库名称（与步骤2.1创建的数据库对应，不要改）
MYSQL_DB_USER=user_db
MYSQL_DB_FRIEND=friend_db

# -------------------------- 服务端口配置 --------------------------
# 各服务端口（默认即可，避免与本地其他服务冲突）
USER_SERVICE_PORT=8001
FRIEND_SERVICE_PORT=8002
GATEWAY_SERVICE_PORT=8000

# -------------------------- Consul 配置 --------------------------
CONSUL_HOST=localhost  # Consul 默认地址
CONSUL_PORT=8500       # Consul 默认端口
```


## 3. 安装各服务依赖
项目分 3 个独立模块，需分别进入每个模块目录，用 Poetry 安装依赖（确保已激活 Poetry 环境）。

### 3.1 安装父级工程依赖
```bash
# 进入项目根目录
cd python_chat_microservice

# 安装依赖（首次安装可能需要1-2分钟）
poetry install --no-root
```

### 3.2 安装 user-service 依赖
```bash
# 进入用户服务目录
cd user-service

# 安装依赖（首次安装可能需要1-2分钟）
poetry install --no-root
```

### 3.3 安装 friend-service 依赖
```bash
# 返回项目根目录，再进入好友服务目录
cd ../friend-service

# 安装依赖
poetry install --no-root
```

### 3.4 安装 gateway-service 依赖
```bash
# 返回项目根目录，再进入网关服务目录
cd ../gateway-service

# 安装依赖
poetry install --no-root
```


## 4. 执行数据库迁移（初始化表结构）
user-service 和 friend-service 需执行 Alembic 迁移，创建数据库表结构（确保 MySQL 已启动，且 `.env` 配置正确）。

### 4.1 user-service 数据库迁移
```bash
# 进入 user-service 目录
cd user-service

# 执行迁移（创建 users 表）
poetry run alembic upgrade head
```

### 4.2 friend-service 数据库迁移
```bash
# 进入 friend-service 目录
cd ../friend-service

# 执行迁移（创建 friendships 表）
poetry run alembic upgrade head
```

> 迁移成功标志：终端输出 `INFO  [alembic.runtime.migration] Context impl MySQLImpl.` 且无报错。


## 5. 启动服务（按顺序启动！）
服务启动有依赖关系：**先启动 Consul → 再启动微服务（user/friend）→ 最后启动网关**，顺序错会导致服务注册失败。

### 5.1 启动 Consul（服务注册与发现）
打开一个新的终端窗口，进入 Consul 安装目录，执行以下命令（开发模式，无需复杂配置）：
```bash
# Consul 开发模式启动（允许外部服务注册）
consul agent -dev -client=0.0.0.0
```
- 启动成功标志：终端显示 `Client Addr: [0.0.0.0] (HTTP: 8500, HTTPS: -1, gRPC: 8502, gRPC-TLS: -1, DNS: 8600)`。
- 注意：Consul 窗口需保持打开，关闭则服务停止。


### 5.2 启动 user-service（用户服务）
打开新的终端窗口，进入 user-service 目录：
```bash
cd user-service

# 启动用户服务（端口 8001）
poetry run start
```
- 启动成功标志：终端显示 `服务注册成功：user-service（xxx.xxx.xxx.xxx:8001）` 和 `INFO:     Application startup complete.`。


### 5.3 启动 friend-service（好友服务）
打开新的终端窗口，进入 friend-service 目录：
```bash
cd friend-service

# 启动好友服务（端口 8002）
poetry run start
```
- 启动成功标志：终端显示 `服务注册成功：friend-service（xxx.xxx.xxx.xxx:8002）` 和 `INFO:     Application startup complete.`。


### 5.4 启动 gateway-service（网关服务）
打开新的终端窗口，进入 gateway-service 目录：
```bash
cd gateway-service

# 启动网关服务（端口 8000）
poetry run start
```
- 启动成功标志：终端显示 `INFO:     Uvicorn running on http://0.0.0.0:8000` 和 `INFO:     Application startup complete.`。


## 6. 测试服务（验证是否正常运行）
所有服务启动后，可通过网关接口测试核心功能（推荐用 Postman 或 curl 测试）。

### 6.1 测试用户注册（通过网关）
```bash
curl -X POST "http://localhost:8000/api/users/" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "testuser",
    "email": "test@example.com",
    "password": "test123456"  # 密码长度建议≤20位，避免哈希处理问题
  }'
```
- 成功响应：返回用户信息（不含密码），状态码 200。


### 6.2 测试添加好友（通过网关）
```bash
# 先注册第二个用户（user_id=2），再执行添加好友
curl -X POST "http://localhost:8000/api/friends/friendships/" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": 1,  # 第一个用户的ID
    "friend_id": 2  # 第二个用户的ID
  }'
```
- 成功响应：返回好友关系信息，状态码 200。


### 6.3 测试健康检查（直接访问微服务）
- 用户服务健康检查：`http://localhost:8001/health`
- 好友服务健康检查：`http://localhost:8002/health`
- 网关服务健康检查：`http://localhost:8000/health`
- 成功响应：`{"status":"healthy","service":"xxx-service"}`


## 7. 常见问题排查
### 问题1：启动服务时提示“找不到 .env 文件”
- 解决：确保 `.env` 文件在项目**根目录**（`chat-microservices/` 下），而非某个子服务目录。

### 问题2：数据库迁移时报“Access denied for user 'root'@'localhost'”
- 解决：检查 `.env` 中 `MYSQL_USER` 和 `MYSQL_PASSWORD` 是否与本地 MySQL 账号密码一致。

### 问题3：服务启动时提示“Consul 连接失败”
- 解决：确认 Consul 已启动，且 `.env` 中 `CONSUL_HOST` 和 `CONSUL_PORT` 正确（默认 `localhost:8500`）。

### 问题4：注册用户时报“password cannot be longer than 72 bytes”
- 解决：项目已改用 Python 内置 `hashlib` 处理密码，无长度限制，若仍报错，检查 `user-service/crud.py` 中 `get_password_hash` 函数是否为最新逻辑（参考项目代码）。


## 项目目录结构说明
```
python_chat_microservices/
├── pyproject.toml          # 根项目配置（管理共用开发依赖）
├── README.md
├── user-service/           # 用户服务
│   ├── pyproject.toml      # 服务独立依赖
│   └── src/
│       └── user_service/
│           ├── __init__.py
│           ├── main.py     # 服务入口
│           ├── database.py # 数据库连接
│           ├── models.py   # 数据模型
│           ├── schemas.py  # 数据验证
│           └── crud.py     # 数据库操作
├── friend-service/         # 好友服务
├── gateway-service/        # 网关服务（路由配置、请求转发）
└── common/                 # 共用工具库
    ├── pyproject.toml
    └── src/
        └── common/
            ├── __init__.py
            ├── config.py   # 共用配置
            └── http_client.py # 服务间通信工具
```