# BadmintonPartner_羽毛球找搭子系统后端

**Repository Path**: lovesource/badminton_partner

## Basic Information

- **Project Name**: BadmintonPartner_羽毛球找搭子系统后端
- **Description**: 本项目是为 Java 后端实习求职打造的实战型项目，针对羽毛球爱好者 “找搭子难、约场地繁” 的核心痛点，设计了同城球馆查询、等级匹配约球、场地时段预约、消息通知等核心功能，同时配套完整的后台管理系统实现业务运营。项目基于 Spring Boot 搭建，严格遵循分层开发思想，落地 Java 后端基础开发规范与核心业务逻辑实现，无过度复杂的中间件依赖，重点体现 “基础扎实、逻辑清晰、可落地” 
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 2
- **Created**: 2026-07-06
- **Last Updated**: 2026-07-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🏸 约球搭子平台 (Badminton Platform)

> 一站式羽毛球社交平台，约球、订场、组队、AI 陪聊，让羽毛球更简单有趣！

## 📋 项目概述

**约球搭子平台**是一个基于微服务架构的羽毛球社交平台，提供用户注册登录、约球组队、场馆预订、订单管理（集成支付宝支付）、通知推送、AI 智能陪聊、文本润色、WebSocket 实时在线等核心功能。

## 🏗️ 架构设计

### 整体架构

```
┌─────────────────────────────────────────────────────────┐
│                   客户端 (微信小程序)                      │
└──────────────────────┬──────────────────────────────────┘
                       │ HTTP/WebSocket
                       ▼
┌─────────────────────────────────────────────────────────┐
│              API Gateway (badminton-gateway)             │
│          端口: 8081 · 认证·路由·跨域·限流                 │
│     ├─ JWT 认证过滤器（白名单路径免认证）                  │
│     ├─ 路由转发（lb:// 负载均衡）                         │
│     └─ WebSocket 路由                                   │
└────┬────┬────┬────┬────┬────┬────┬──────────────────────┘
     │    │    │    │    │    │    │
     ▼    ▼    ▼    ▼    ▼    ▼    ▼
┌─────────────────────────────────────────────────────────┐
│                    微服务集群                            │
├─────────────────────────────────────────────────────────┤
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐  │
│  │  User    │ │  Court   │ │  Order   │ │  Game    │  │
│  │  用户服务 │ │  场馆服务 │ │  订单服务 │ │  约球服务 │  │
│  │ :8086    │ │ :8082    │ │ :8083    │ │ :8084    │  │
│  └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘  │
│  ┌──────────┐ ┌──────────┐ ┌──────────────────────┐   │
│  │Notification│ │PlatformAI│ │  公共模块 (Common)    │   │
│  │  通知服务  │ │ AI 服务  │ │  Core·Database·Minio│   │
│  │ :8085    │ │ :8087    │ │  Redis·RabbitMQ·Security  │   │
│  └──────────┘ └──────────┘ └──────────────────────┘   │
└──────────┬─────────────────────────────────────────────┘
           │
           ▼
┌─────────────────────────────────────────────────────────┐
│                    基础设施层                            │
├─────────────────────────────────────────────────────────┤
│  MySQL  │  Redis  │  RabbitMQ  │  MinIO  │  Nacos      │
│  (分库)  │  (缓存)  │  (消息队列)  │ (文件存储)│ (注册/配置)│
└─────────────────────────────────────────────────────────┘
```

### 服务职责说明

| 服务 | 端口 | 职责 | 数据库 |
|------|------|------|--------|
| **Gateway** | 8081 | API 网关、JWT 认证、路由转发、跨域处理 | 无 |
| **User Service** | 8086 | 用户注册/登录、个人信息、文件上传、WebSocket 在线状态管理 | `badminton_user` |
| **Court Service** | 8082 | 场馆管理、场地 CRUD、场地可预定状态查询 | `badminton_court` |
| **Order Service** | 8083 | 场地订单、支付宝支付、订单状态流转 | `badminton_order` |
| **Game Service** | 8084 | 约球活动、组队、报名、评论、我的约球 | `badminton_game` |
| **Notification Service** | 8085 | 站内通知、未读计数、已读标记、消息推送 | `badminton_notification` |
| **PlatformAI Service** | 8087 | AI 陪聊、文本润色、AI 搜索帖子（基于阿里云百炼/通义千问） | `badminton-platformai` |

### Nacos 共享配置中心

各服务通过 Nacos Config 统一管理中间件配置，避免硬编码。需在 Nacos 控制台创建以下配置：

| Data ID | 用途 | 使用方 | 关键配置项 |
|---------|------|--------|-----------|
| `shared-redis.yml` | Redis 连接 | 全部服务 | `spring.redis.host/port/password` |
| `shared-jwt.yml` | JWT 密钥 | 全部服务 | `jwt.secret/expiration` |
| `shared-minio.yml` | MinIO 配置 | user-service | `minio.endpoint/accessKey/secretKey/bucketName` |
| `shared-rabbitmq.yml` | RabbitMQ 连接 | game-service, notification-service | `spring.rabbitmq.host/port/username/password` |
| `shared-logging.yml` | 日志级别（可选） | 全部服务 | `logging.level.*` |

## 🔧 环境变量清单

所有可配置的环境变量（用于 `.env` 文件和 Docker 部署）：

### 基础设施连接

| 变量名 | 默认值 | 说明 | 使用方 |
|--------|--------|------|--------|
| `NACOS_ADDR` | `175.24.172.13:8848` | Nacos 服务地址（注册中心+配置中心） | 全部服务 |
| `MYSQL_HOST` | `175.24.172.13` | MySQL 主机 | 全部服务 |
| `MYSQL_PORT` | `3306` | MySQL 端口 | 全部服务 |
| `MYSQL_USER` | `root` | MySQL 用户名 | 全部服务 |
| `MYSQL_PASSWORD` | `123456` | MySQL 密码 | 全部服务 |
| `REDIS_HOST` | `175.24.172.13` | Redis 主机 | 全部服务 |
| `REDIS_PORT` | `6379` | Redis 端口 | 全部服务 |
| `RABBITMQ_HOST` | `175.24.172.13` | RabbitMQ 主机 | game, notification |
| `RABBITMQ_PORT` | `5672` | RabbitMQ 端口 | game, notification |
| `RABBITMQ_USER` | `admin` | RabbitMQ 用户名 | game, notification |
| `RABBITMQ_PASSWORD` | — | RabbitMQ 密码 | game, notification |
| `MINIO_ENDPOINT` | `http://175.24.172.13:9000` | MinIO 服务端地址 | user-service |
| `MINIO_PUBLIC_ENDPOINT` | `http://175.24.172.13:9000` | MinIO 公网访问地址 | user-service |

### 业务配置

| 变量名 | 默认值 | 说明 | 使用方 |
|--------|--------|------|--------|
| `JWT_SECRET` | `badminton-platform-secret-key-...` | JWT 签名密钥（所有服务需一致） | 全部服务 |
| `JWT_EXPIRATION` | `86400000` | JWT 过期时间（ms，默认24h） | 全部服务 |
| `DASHSCOPE_API_KEY` | — | 阿里云百炼 API Key | platform-ai-service |

### Docker 部署 JVM 优化（2GB 极限优化）

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `JAVA_OPTS` | `-Xms32m -Xmx64m -XX:+UseSerialGC -XX:MaxMetaspaceSize=64m` | 每个服务 JVM 参数 |

## 🚀 快速开始

### 环境要求

- JDK 17+
- Docker & Docker Compose（推荐部署方式）
- MySQL 8.0+
- Redis 6.0+
- Nacos 2.1.0+

### 本地开发

1. **克隆项目**
   ```bash
   git clone https://github.com/your-repo/badminton-platform.git
   cd badminton-platform
   ```

2. **配置 hosts**（或在各服务 `bootstrap.yml` 中修改 Nacos 地址）
   ```
   127.0.0.1 nacos-server
   ```

3. **启动基础设施**（MySQL、Redis、Nacos、RabbitMQ、MinIO）
   > 注意：`docker-compose.yml` 仅包含 7 个微服务容器，中间件需在宿主机或独立服务器上提前部署。
   ```bash
   # 中间件需单独部署，确保以下服务已启动：
   # - MySQL（端口 3306）
   # - Redis（端口 6379）
   # - Nacos（端口 8848）
   # - RabbitMQ（端口 5672）
   # - MinIO（端口 9000）
   ```

4. **在 Nacos 控制台创建共享配置**
   访问 http://localhost:8848/nacos，创建以下配置：
   - `shared-redis.yml`：Redis 连接信息
   - `shared-jwt.yml`：JWT 密钥和过期时间
   - `shared-minio.yml`：MinIO 连接信息
   - `shared-rabbitmq.yml`：RabbitMQ 连接信息

5. **启动服务**
   使用 IDE 逐个启动各服务，顺序：Gateway → User → Court → Order → Game → Notification → PlatformAI

### Docker 部署（生产环境）

```bash
# 1. 配置环境变量
cp .env.example .env
vi .env  # 修改配置

# 2. 部署基础设施
./deploy-infra.sh

# 3. 部署微服务
./deploy-services.sh
```

## 📂 项目结构

```
badminton-platform/
├── badminton-gateway/              # API 网关 (Spring Cloud Gateway)
│   ├── src/main/java/com/badminton/gateway/
│   │   ├── filter/                 # 网关过滤器
│   │   │   ├── AuthGlobalFilter.java        # JWT 认证全局过滤器
│   │   │   └── CustomGatewayFilter.java     # 自定义网关过滤器
│   │   ├── util/
│   │   │   └── GatewayJwtUtil.java          # 网关 JWT 工具类（WebFlux 环境）
│   │   ├── constant/
│   │   │   └── GatewayAuthConstants.java     # 认证常量
│   │   └── BadmintonGatewayApplication.java
│   └── Dockerfile
│
├── badminton-service-user/         # 用户服务
│   ├── src/main/java/com/badminton/user/
│   │   ├── controller/             # 用户登录/注册/信息/文件上传
│   │   ├── service/                # 登录/注册/个人信息/在线状态
│   │   ├── mapper/                 # MyBatis-Plus Mapper
│   │   └── entity/
│   └── Dockerfile
│
├── badminton-service-court/        # 场馆服务
│   ├── src/main/java/com/badminton/court/
│   │   ├── controller/             # 场馆/场地 CRUD
│   │   ├── service/                # 场馆查询/场地可用性
│   │   └── entity/
│   └── Dockerfile
│
├── badminton-service-order/        # 订单服务
│   ├── src/main/java/com/badminton/order/
│   │   ├── controller/             # 订单创建/支付/取消、内部接口
│   │   ├── service/                # 创建/支付（支付宝集成）/取消/查询
│   │   └── entity/
│   └── Dockerfile
│
├── badminton-service-game/         # 约球服务
│   ├── src/main/java/com/badminton/game/
│   │   ├── controller/             # 约球活动/组队/报名、评论、我的约球
│   │   ├── service/                # 约球发布/加入/取消/评论/查询
│   │   ├── entity/
│   │   └── mq/                     # RabbitMQ 消息生产者
│   └── Dockerfile
│
├── badminton-service-notification/ # 通知服务
│   ├── src/main/java/com/badminton/notification/
│   │   ├── controller/             # 通知列表/未读数/已读标记/删除
│   │   ├── service/                # 通知管理/RabbitMQ 消息消费
│   │   └── mq/                     # RabbitMQ 消息消费者
│   └── Dockerfile
│
├── badminton-service-PlatformAi/   # AI 服务
│   ├── src/main/java/com/badminton/platformai/
│   │   ├── controller/             # AI 聊天/文本润色/搜索帖子
│   │   ├── service/                # 调用阿里云百炼 API（DashScope）
│   │   └── entity/
│   └── Dockerfile
│
├── badminton-common/               # 公共模块
│   ├── badminton-common-core/      # 核心工具类、DTO、全局异常处理、Feign 客户端
│   ├── badminton-common-database/  # MyBatis-Plus 数据库配置与自动填充
│   ├── badminton-common-minio/     # MinIO 文件存储客户端
│   ├── badminton-common-redis/     # Redis 缓存工具
│   ├── badminton-common-rabbitmq/  # RabbitMQ 消息工具
│   └── badminton-common-security/  # 安全认证、JWT、用户上下文
│
├── docker-compose.yml              # Docker Compose 编排（仅微服务）
├── deploy-infra.sh                 # 基础设施部署脚本
├── deploy-services.sh              # 服务部署脚本
├── .env.example                    # 环境变量模板
├── doc/                            # 详细接口文档
├── sql/                            # 数据库初始化脚本
│   ├── nacos.sql                   # Nacos 配置数据库
│   └── all_databases_*.sql         # 业务数据库备份
└── README.md                       # 项目文档
```

## 🌐 接口路由

| 路由 | 目标服务 | 说明 |
|------|----------|------|
| `/client/v1/user/**` | User Service | 用户相关接口 |
| `/client/v1/file/**` | Common MinIO | 文件上传接口（MinIO 存储） |
| `/client/v1/court/**` | Court Service | 场馆相关接口 |
| `/client/v1/order/**` | Order Service | 订单相关接口 |
| `/client/v1/game/invite/**` | Game Service | 约球活动接口 |
| `/client/v1/game/comment/**` | Game Service | 约球评论接口 |
| `/client/v1/my/game/**` | Game Service | 我的约球相关接口 |
| `/client/v1/notification/**` | Notification Service | 通知相关接口 |
| `/client/AI/**` | PlatformAI Service | AI 聊天、润色、搜索接口 |
| `/websocket` | User Service | WebSocket 实时通信连接 |

> **认证说明**：除 `/client/v1/user/login`、`/client/v1/user/register`、`/client/v1/user/send-code`、`/websocket` 等白名单路径外，其余接口均需在请求头携带 `Authorization: Bearer <token>`。

## 🔐 JWT Token 解析流程

网关的 `AuthGlobalFilter` 会拦截所有请求（白名单除外），执行以下流程：

1. **获取 Token**：从 `Authorization` 请求头提取 Bearer Token
2. **解析 Token**：使用 `GatewayJwtUtil` 解析 JWT，提取用户信息
3. **传递用户信息**：将 `userId`、`userKey`、`phone`、`nickname`、`avatarUrl`、`badmintonLevel` 放入请求头转发给下游服务
4. **下游服务**：通过 `common-core` 中的 `UserContext` 拦截器从请求头读取用户信息

> **注意**：网关使用独立的 `GatewayJwtUtil`（WebFlux 环境），与公共模块的 `JwtUtil`（Servlet 环境）不共用。

## 🔗 微服务间通信 (Feign)

各微服务通过 **OpenFeign** 进行内部 RPC 调用，Feign 客户端定义在 `badminton-common-core` 公共模块中：

| Feign 客户端 | 提供方 | 调用方 | 功能 |
|-------------|--------|--------|------|
| `UserFeignClient` | user-service | platform-ai | 根据 userKey/ID 查询用户信息 |
| `CourtFeignClient` | court-service | order-service | 查询球馆/场地信息 |
| `OrderFeignClient` | order-service | user-service | 查询用户预约记录 |
| `GameFeignClient` | game-service | platform-ai | 查询约球列表/详情/发布 |
| `WebSocketFeignClient` | user-service | notification-service | 向指定用户推送 WebSocket 消息 |
| `GameNotificationFeignClient` | notification-service | game-service | 发送约球相关通知 |

> 所有内部接口路由以 `/internal/` 为前缀，网关白名单对其放行，不经过 JWT 认证。

## 🔌 WebSocket 实时通信

用户服务内置 WebSocket 支持，用于在线状态管理和实时消息推送：

- **连接端点**：`ws://host/websocket?token=<JWT_TOKEN>`
- **连接认证**：通过 URL 参数传递 JWT Token 进行身份验证
- **心跳检测**：定期检测连接存活状态，自动清理断线连接
- **在线状态同步**：用户上线/离线时自动更新数据库中 `online_status` 和 `last_heartbeat_time` 字段
- **消息推送**：其他微服务可通过 `WebSocketFeignClient` 向指定在线用户实时推送消息

## 🛡️ 安全机制

| 安全措施 | 实现方式 | 说明 |
|---------|---------|------|
| JWT 认证 | 网关 `AuthGlobalFilter` + 白名单机制 | 统一在网关层拦截验证，白名单路径免认证 |
| 密码加密 | BCrypt (at.favre.lib) | 用户密码经过 BCrypt 哈希后存储，不可逆 |
| XSS 防护 | JSOUP + `XssFilter` | 对所有请求参数进行 HTML 清洗，移除 `<script>`、`onclick` 等危险标签 |
| 请求头透传 | `UserContext` 拦截器 | 网关解析 JWT 后将用户信息透传到下游服务，下游从请求头读取 |
| 内部接口隔离 | `/internal/**` 路径 | 内部 Feign 调用接口与 C 端接口分离，网关白名单放行但对外不暴露 |

## 📦 数据库说明

项目采用**按服务分库**设计，共 6 个数据库：

| 数据库 | 所属服务 | 核心表 |
|--------|----------|--------|
| `badminton_user` | User Service | 用户表、用户等级、文件记录 |
| `badminton_court` | Court Service | 场馆表、场地表 |
| `badminton_order` | Order Service | 订单表、支付记录 |
| `badminton_game` | Game Service | 约球活动表、报名表、评论表 |
| `badminton_notification` | Notification Service | 通知表 |
| `badminton-platformai` | PlatformAI Service | 聊天记录表 |

> **Nacos 数据库**：`sql/nacos.sql` 创建的数据库名为 `nacos`，实际部署时需确保与 Nacos 配置中的数据库名一致。

## 📄 其它文档

项目 `doc/` 目录下提供以下详细接口文档：

| 文档 | 说明 |
|------|------|
| `AI聊天服务接口文档.md` | AI 陪聊、聊天列表、聊天历史接口详情 |
| `AI搜索帖子接口文档.md` | AI 搜索帖子接口详情 |
| `JWT_CONFIG_README.md` | JWT 配置说明 |

## 🛠️ 技术栈

| 技术 | 版本 | 用途 |
|-----|------|------|
| Spring Cloud Gateway | 2021.0.8 | API 网关 |
| Spring Boot | 2.7.14 | 微服务基础框架 |
| Spring Cloud Alibaba | 2021.0.5.0 | Nacos 注册/配置、负载均衡 |
| MyBatis-Plus | 3.5.3.1 | ORM 框架 |
| MySQL | 8.0.33 | 关系型数据库 |
| Redis | 6.0+ | 缓存 |
| Redisson | 3.17.7 | 分布式锁 |
| RabbitMQ | 3.x | 异步消息（订单超时、通知推送） |
| MinIO | 8.5.7 | 文件存储（头像、图片） |
| Nacos | 2.1.0+ | 服务注册发现、配置中心 |
| 阿里云 DashScope | 最新 | AI 聊天（通义千问百炼平台） |
| JJWT | 0.11.5 | JWT Token 生成与解析 |
| Druid | 1.2.8 | 数据库连接池 |
| PageHelper | 1.4.6 | 分页插件 |
| FastJSON2 | 2.0.25 | JSON 序列化 |
| BCrypt (favre) | 0.10.2 | 密码加密 |
| JSOUP | 1.17.2 | XSS 防护（HTML 清洗） |
| Apache POI | 4.1.2 | Excel 文件处理 |
| OpenFeign | — | 微服务间 RPC 调用 |

---
*本内容由 DeepSeek 大模型基于项目分析进行编写*

> **版本：v2.0**