199 lines
6.9 KiB
Markdown
199 lines
6.9 KiB
Markdown
# CLAUDE.md
|
||
|
||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
||
## 项目概述
|
||
|
||
FlashSaleSystem 是一个基于 Spring Boot 2.7.6 和 Redis 集群构建的社区生鲜团购系统。系统采用分布式架构设计，通过 Redis 集群实现高并发处理，使用 Lua 脚本保证原子性操作，采用分布式锁防止超卖。
|
||
|
||
## 核心架构
|
||
|
||
### 技术栈
|
||
- **后端框架**: Spring Boot 2.7.6, Java 1.8
|
||
- **数据库**: MySQL 5.7+ (JPA/Hibernate)
|
||
- **缓存系统**: Redis 6.0+ (支持单节点/集群/哨兵模式)
|
||
- **分布式锁**: Redisson 3.24.3
|
||
- **前端技术**: JSP + JSTL + Bootstrap 5 + jQuery
|
||
- **API文档**: Knife4j 4.1.0 (增强版Swagger)
|
||
- **构建工具**: Maven 3.6+
|
||
|
||
### 包结构
|
||
```
|
||
com.org.flashsalesystem/
|
||
├── controller/ # 控制器层（REST API和页面控制）
|
||
├── service/ # 业务逻辑层（核心业务和Redis操作）
|
||
├── repository/ # 数据访问层（JPA接口）
|
||
├── entity/ # 实体类（User, Product, Order, FlashSale）
|
||
├── dto/ # 数据传输对象
|
||
├── config/ # 配置类（RedissonConfig, SwaggerConfig, WebConfig）
|
||
└── util/ # 工具类（JSPFunctions, PasswordGenerator）
|
||
```
|
||
|
||
## 常用开发命令
|
||
|
||
### 构建和运行
|
||
```bash
|
||
# 编译项目
|
||
mvn clean compile
|
||
|
||
# 单元测试编译
|
||
mvn test-compile
|
||
|
||
# 运行测试
|
||
mvn test
|
||
mvn test -Dtest=FlashSaleServiceTest
|
||
|
||
# 打包（跳过测试）
|
||
mvn clean package -DskipTests
|
||
|
||
# 本地运行（默认单节点Redis）
|
||
mvn spring-boot:run
|
||
|
||
# 运行指定profile
|
||
mvn spring-boot:run -Dspring.profiles.active=dev # 开发环境
|
||
mvn spring-boot:run -Dspring.profiles.active=cluster # 集群环境
|
||
|
||
# 运行JAR包
|
||
java -jar target/FlashSaleSystem-0.0.1-SNAPSHOT.jar
|
||
java -jar target/FlashSaleSystem-0.0.1-SNAPSHOT.jar --spring.profiles.active=cluster
|
||
```
|
||
|
||
### 数据库初始化
|
||
```bash
|
||
# 创建数据库
|
||
mysql -u root -p -e "CREATE DATABASE flash_sale_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
|
||
|
||
# 导入表结构（JPA自动创建，可选）
|
||
mysql -u root -p flash_sale_db < src/main/resources/sql/schema.sql
|
||
|
||
# 导入演示用户
|
||
mysql -u root -p flash_sale_db < src/main/resources/sql/demo-users.sql
|
||
|
||
# 导入测试数据
|
||
mysql -u root -p flash_sale_db < src/main/resources/sql/test-data.sql
|
||
```
|
||
|
||
## Redis架构设计
|
||
|
||
### 支持模式
|
||
1. **单节点模式**（默认）: localhost:6379，适用于开发环境
|
||
2. **集群模式**: 6节点集群（42.192.62.91:7000-7005），生产环境推荐
|
||
3. **哨兵模式**: 高可用配置，支持主从切换
|
||
|
||
### Redis数据结构使用
|
||
- **String**: 分布式锁、会话存储、库存计数
|
||
- **Hash**: 用户信息、商品信息、购物车数据
|
||
- **List**: 订单队列、消息队列
|
||
- **Set**: 秒杀成功用户集合
|
||
- **ZSet**: 商品排行榜、热门活动
|
||
|
||
### Key前缀规范
|
||
- `flashsale:` - 秒杀活动数据
|
||
- `flashsale_stock:` - 实时库存信息
|
||
- `flashsale_lock:` - 秒杀分布式锁
|
||
- `flashsale_success:` - 成功用户集合
|
||
- `user:` - 用户信息缓存
|
||
- `product:` - 商品信息缓存
|
||
- `cart:` - 购物车数据
|
||
- `rate_limit:` - API限流计数器
|
||
|
||
### Lua脚本（src/main/resources/lua/）
|
||
1. **flashsale.lua**: 原子性库存扣减，防止超卖
|
||
2. **distributed_lock.lua**: 分布式锁获取
|
||
3. **unlock.lua**: 安全释放分布式锁
|
||
4. **rate_limit.lua**: 滑动窗口限流
|
||
5. **cart_operation.lua**: 购物车原子操作
|
||
|
||
## 核心业务流程
|
||
|
||
### 秒杀流程
|
||
1. **库存预热**: 活动前30分钟通过 `FlashSaleService.preloadStock()` 预加载库存到Redis
|
||
2. **限流检查**: `RateLimitService.checkFlashSaleRateLimit()` 检查用户请求频率（10次/分钟）
|
||
3. **分布式锁**: `RedissonLockService.tryLock()` 获取分布式锁，防止并发超卖
|
||
4. **库存扣减**: 执行 `flashsale.lua` 脚本原子性扣减库存
|
||
5. **订单创建**: 数据库创建订单，Redis记录成功用户
|
||
6. **消息发布**: 通过Pub/Sub发布秒杀结果通知
|
||
|
||
### 关键服务类
|
||
- **FlashSaleService**: 秒杀核心逻辑，包含库存预热、分布式锁、Lua脚本执行
|
||
- **RedisService**: Redis基础操作封装，支持各种数据类型和TTL设置
|
||
- **RedissonLockService**: Redisson分布式锁实现，支持自动续期
|
||
- **RateLimitService**: 基于Redis的滑动窗口限流
|
||
- **CartService**: 购物车服务，基于Redis Hash实现
|
||
- **RedisPipelineService**: 批量Redis操作优化
|
||
- **MessageListenerService**: Redis Pub/Sub消息监听处理
|
||
|
||
## 配置说明
|
||
|
||
### 核心配置文件
|
||
- `application.yml`: 主配置文件（数据库、Redis、业务配置）
|
||
- `pom.xml`: Maven依赖和构建配置
|
||
|
||
### 重要配置项
|
||
```yaml
|
||
# Redis模式切换（application.yml）
|
||
spring.redis.host: localhost # 单节点配置
|
||
spring.redis.cluster.nodes: ... # 集群配置（取消注释启用）
|
||
|
||
# 秒杀业务配置
|
||
flashsale.seckill.rate-limit.max-requests-per-minute: 10 # 限流
|
||
flashsale.seckill.max-quantity-per-user: 1 # 每人限购
|
||
flashsale.seckill.stock-preload.advance-minutes: 30 # 预热时间
|
||
|
||
# 缓存过期时间
|
||
flashsale.cache.user-expire-minutes: 30 # 用户信息
|
||
flashsale.cache.product-expire-minutes: 60 # 商品信息
|
||
flashsale.cache.flashsale-expire-minutes: 10 # 秒杀活动
|
||
```
|
||
|
||
## 性能优化策略
|
||
|
||
1. **连接池优化**: HikariCP数据库连接池(20)，Jedis连接池(20)
|
||
2. **批量操作**: 使用 `RedisPipelineService` 进行批量Redis操作
|
||
3. **多级缓存**: 本地缓存 + Redis缓存，合理设置TTL
|
||
4. **Lua脚本**: 减少网络往返，保证原子性
|
||
5. **库存预热**: 提前加载热点数据到缓存
|
||
|
||
## 监控和运维
|
||
|
||
### 访问地址
|
||
- **应用首页**: http://localhost:8080
|
||
- **API文档**: http://localhost:8080/doc.html
|
||
- **健康检查**: http://localhost:8080/actuator/health
|
||
- **Prometheus监控**: http://localhost:8080/actuator/prometheus
|
||
|
||
### 日志配置
|
||
- **日志文件**: logs/flash-sale-system.log
|
||
- **日志级别**: DEBUG (com.org.flashsalesystem, Redis, SQL)
|
||
|
||
## 测试策略
|
||
|
||
### 单元测试
|
||
- 核心服务测试: FlashSaleServiceTest (已创建框架)
|
||
- 建议补充: RedisServiceTest, CartServiceTest
|
||
- Mock策略: 使用Mockito模拟Redis和数据库操作
|
||
|
||
### 性能测试
|
||
- 推荐工具: JMeter, Gatling
|
||
- 测试场景: 高并发秒杀、库存扣减准确性、分布式锁效果
|
||
|
||
## 安全考虑
|
||
|
||
1. **密码加密**: BCrypt (strength=10)
|
||
2. **Redis认证**: 集群模式使用密码认证
|
||
3. **SQL注入防护**: JPA参数化查询
|
||
4. **限流保护**: API级别限流防止恶意请求
|
||
5. **会话管理**: Redis存储，30分钟超时
|
||
|
||
## 故障排查
|
||
|
||
### 常见问题
|
||
1. **Redis连接失败**: 检查网络、端口、密码配置
|
||
2. **库存超卖**: 验证Lua脚本加载、分布式锁配置
|
||
3. **高延迟**: 检查Redis集群状态、网络延迟
|
||
4. **内存溢出**: 监控Redis内存、调整缓存TTL
|
||
|
||
### 调试技巧
|
||
- 启用DEBUG日志查看详细Redis操作
|
||
- 使用Redis CLI监控命令: `MONITOR`
|
||
- 检查Lua脚本执行: `SCRIPT EXISTS` |