# spring-cloud-points-system-complete

**Repository Path**: hndg/spring-cloud-points-system-complete

## Basic Information

- **Project Name**: spring-cloud-points-system-complete
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-07
- **Last Updated**: 2026-01-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Spring Cloud 高可用分布式积分接口系统

## 项目简介

这是一个基于 **Spring Cloud** 技术栈构建的高可用分布式积分接口系统，实现了完整的企业级积分管理功能。

## 技术栈

- **Spring Boot 3.2.0** - 核心框架
- **Spring Cloud 2023.0.0** - 微服务框架
- **Spring Cloud Netflix Eureka** - 服务注册与发现
- **Spring Cloud Gateway** - API 网关
- **Spring Cloud OpenFeign** - 服务间调用
- **Resilience4j** - 熔断降级
- **Spring Data JPA** - 数据持久化
- **H2 Database** - 内存数据库（开发环境）
- **Lombok** - 简化代码

## 项目结构

```
points-cloud-system/
├── eureka-server/          # 服务注册中心（端口：8761）
├── points-service/         # 积分服务（端口：8081）
├── user-service/           # 用户服务（端口：8082）
├── gateway-service/        # API网关（端口：8080）
├── pom.xml                 # 父级 Maven 配置
├── start-all.sh            # 启动脚本
├── stop-all.sh            # 停止脚本
└── test-api.sh            # API测试脚本
```

## 核心功能

### 1. 积分账户管理
- 创建积分账户
- 查询积分余额
- 查询积分统计（累计获得、累计消费）

### 2. 积分交易
- **增加积分**：注册奖励、活动奖励等
- **消费积分**：订单支付、商品兑换等
- **退回积分**：订单退款等
- **积分转账**：用户间积分互转

### 3. 高可用特性
- **服务注册与发现**：Eureka 自动服务注册
- **负载均衡**：Spring Cloud LoadBalancer
- **熔断降级**：Resilience4j 实现服务熔断
- **服务限流**：防止服务雪崩
- **重试机制**：自动重试失败请求
- **幂等性保证**：防止重复提交

### 4. 并发安全
- **乐观锁**：JPA @Version 实现并发控制
- **自动重试**：乐观锁冲突自动重试
- **悲观锁**：关键操作可加锁（预留）

## 快速开始

### 前置要求

- JDK 17 或更高版本
- Maven 3.6+
- Linux/Mac/Windows（需要 Git Bash）

### 1. 克隆项目

```bash
git clone <repository-url>
cd points-cloud-system
```

### 2. 编译项目

```bash
mvn clean package -DskipTests
```

### 3. 启动服务

**方式一：使用启动脚本（推荐）**

```bash
# Linux/Mac
chmod +x start-all.sh stop-all.sh test-api.sh
./start-all.sh

# Windows (Git Bash)
bash start-all.sh
```

**方式二：手动启动**

```bash
# 启动 Eureka Server
java -jar eureka-server/target/eureka-server-1.0.0.jar

# 启动积分服务
java -jar points-service/target/points-service-1.0.0.jar

# 启动用户服务
java -jar user-service/target/user-service-1.0.0.jar

# 启动网关服务
java -jar gateway-service/target/gateway-service-1.0.0.jar
```

### 4. 验证服务

访问以下地址确认服务启动成功：

- Eureka控制台：http://localhost:8761
- API网关：http://localhost:8080
- 积分服务：http://localhost:8081
- 用户服务：http://localhost:8082
- H2控制台：http://localhost:8081/h2-console

### 5. 测试 API

```bash
chmod +x test-api.sh
./test-api.sh
```

## API 接口文档

所有接口通过 API 网关访问：`http://localhost:8080`

### 积分服务接口

#### 1. 创建积分账户
```http
POST /api/points/account
Content-Type: application/json

{
  "userId": "user001"
}
```

#### 2. 查询积分账户
```http
GET /api/points/account/{userId}
```

#### 3. 增加积分
```http
POST /api/points/earn
Content-Type: application/json

{
  "userId": "user001",
  "pointsAmount": 1000,
  "businessType": "REGISTER_REWARD",
  "businessOrderNo": "ORDER20241201001",
  "description": "注册奖励积分"
}
```

#### 4. 消费积分
```http
POST /api/points/spend
Content-Type: application/json

{
  "userId": "user001",
  "pointsAmount": 200,
  "businessType": "ORDER_PAY",
  "businessOrderNo": "ORDER20241201001",
  "description": "订单支付消费积分"
}
```

#### 5. 退回积分
```http
POST /api/points/refund
Content-Type: application/json

{
  "userId": "user001",
  "pointsAmount": 100,
  "businessType": "ORDER_REFUND",
  "businessOrderNo": "ORDER20241201001",
  "description": "订单退款"
}
```

#### 6. 积分转账
```http
POST /api/points/transfer?fromUserId=user001&toUserId=user002&amount=300&description=转账
```

#### 7. 查询交易记录
```http
GET /api/points/transactions/{userId}?page=0&size=20
```

### 用户服务接口

#### 1. 查询用户积分（远程调用）
```http
GET /api/user/points/{userId}
```

#### 2. 用户注册（自动奖励积分）
```http
POST /api/user/register
Content-Type: application/json

{
  "userId": "user001",
  "username": "张三",
  "email": "zhangsan@example.com"
}
```

#### 3. 用户下单支付
```http
POST /api/user/order/pay
Content-Type: application/json

{
  "userId": "user001",
  "orderNo": "ORDER20241201001",
  "points": 100
}
```

## 高可用特性说明

### 1. 服务注册与发现

- **Eureka Server**：作为服务注册中心，所有微服务启动时自动注册
- **服务发现**：通过服务名调用，无需硬编码 IP 地址
- **心跳检测**：定期检测服务健康状态

### 2. 负载均衡

- **Spring Cloud LoadBalancer**：默认使用轮询策略
- **多实例部署**：同一服务可启动多个实例，自动负载均衡

### 3. 熔断降级

- **Resilience4j Circuit Breaker**：失败率达到阈值时熔断
- **降级响应**：服务不可用时返回友好提示
- **自动恢复**：熔断一段时间后尝试半开状态

配置示例：
```yaml
resilience4j:
  circuitbreaker:
    instances:
      pointsService:
        failure-rate-threshold: 50    # 失败率50%
        wait-duration-in-open-state: 10s  # 熔断持续10秒
        sliding-window-size: 10      # 滑动窗口大小
```

### 4. 重试机制

- **自动重试**：网络抖动自动重试
- **指数退避**：重试间隔递增
- **最多重试3次**

### 5. 并发安全

- **乐观锁**：JPA @Version 注解实现
- **自动重试**：乐观锁冲突自动重试（最多3次）
- **幂等性**：通过 businessOrderNo 防止重复提交

## 部署到生产环境

### 1. 修改数据库配置

修改 `points-service/src/main/resources/application.yml`：

```yaml
spring:
  datasource:
    url: jdbc:mysql://your-host:3306/points_db
    username: your-username
    password: your-password
    driver-class-name: com.mysql.cj.jdbc.Driver
```

添加 MySQL 依赖：
```xml
<dependency>
    <groupId>mysql</groupId>
    <artifactId>mysql-connector-java</artifactId>
</dependency>
```

### 2. 修改 Eureka 配置（集群部署）

```yaml
eureka:
  client:
    service-url:
      defaultZone: http://eureka1:8761/eureka/,http://eureka2:8762/eureka/
```

### 3. 多实例部署

```bash
# 启动多个积分服务实例
java -jar points-service-1.0.0.jar --server.port=8081
java -jar points-service-1.0.0.jar --server.port=8082
java -jar points-service-1.0.0.jar --server.port=8083
```

### 4. 使用 Docker 部署

```dockerfile
FROM openjdk:17-jdk-slim
COPY target/points-service-1.0.0.jar app.jar
ENTRYPOINT ["java", "-jar", "app.jar"]
```

## 监控与运维

### 1. 健康检查

所有服务提供健康检查接口：

```bash
curl http://localhost:8081/api/points/health
curl http://localhost:8082/api/user/health
```

### 2. 查看日志

```bash
# 查看各服务日志
tail -f logs/eureka-server.log
tail -f logs/points-service.log
tail -f logs/user-service.log
tail -f logs/gateway-service.log
```

### 3. 监控指标

访问 Spring Boot Actuator：

```bash
http://localhost:8081/actuator/health
http://localhost:8081/actuator/metrics
http://localhost:8081/actuator/circuitbreakers
```

## 常见问题

### Q1: 启动失败，提示端口被占用

修改对应服务的 `application.yml` 中的 `server.port` 配置。

### Q2: 服务注册失败

检查 Eureka Server 是否启动，以及 `defaultZone` 配置是否正确。

### Q3: 数据库连接失败

检查数据库是否启动，连接配置是否正确。

### Q4: 服务调用超时

调整 Feign 和 Resilience4j 的超时配置。

## 技术亮点

1. **完整的微服务架构**：服务注册、发现、网关、调用全流程
2. **高可用设计**：熔断、降级、重试、负载均衡
3. **并发安全**：乐观锁 + 自动重试机制
4. **幂等性保证**：防止重复提交
5. **优雅降级**：服务不可用时友好提示
6. **日志追踪**：完整的请求日志记录

## 许可证

MIT License

## 联系方式

如有问题，请提交 Issue 或 Pull Request。