FlashSaleSystem/CLAUDE.md

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）

常用开发命令

构建和运行

# 编译项目
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

数据库初始化

# 创建数据库
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依赖和构建配置

重要配置项

# 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