# cart_api

**Repository Path**: chichi-chichi/cart_api

## Basic Information

- **Project Name**: cart_api
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-27
- **Last Updated**: 2025-11-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 点餐系统购物车API

一个支持多人协作点餐的购物车系统，基于Spring Boot和Redis实现，提供RESTful API接口。

## 项目简介

本项目实现了一个完整的点餐系统购物车功能，支持多用户协作点餐，相同菜品会自动合并数量。系统采用分布式锁确保并发安全，使用Redis存储购物车数据，提供完整的RESTful API接口。

## 功能特性

- ✅ 多人协作点餐（相同菜品数量合并）
- ✅ 加菜功能（支持单个/批量添加）
- ✅ 减菜功能（支持单个/批量减少）
- ✅ 查询购物车（按菜品合并展示）
- ✅ 清空购物车
- ✅ 并发安全控制
- ✅ 完善的异常处理
- ✅ RESTful API设计

## 技术栈

- **后端框架**: Spring Boot 3.x
- **数据存储**: Redis
- **并发控制**: Redis分布式锁
- **API文档**: OpenAPI 3.0.3
- **构建工具**: Maven

## 项目结构

```
src/main/java/com/example/
├── CartSystemApplication.java     # 应用程序入口
├── controller/
│   └── CartController.java         # 购物车控制器
├── dto/                            # 数据传输对象
│   ├── AddCartItemsRequest.java
│   ├── CartItemResponse.java
│   ├── CartResponse.java
│   ├── CartItemForRemove.java
│   ├── RemoveCartItemsRequest.java
│   └── UserDetail.java
├── entity/                         # 实体类
│   ├── CartItem.java
│   └── User.java
├── exception/                      # 异常处理
│   ├── CartException.java
│   ├── CartNotFoundException.java
│   ├── GlobalExceptionHandler.java
│   ├── InvalidParameterException.java
│   ├── ItemNotFoundException.java
│   └── JsonProcessingException.java
├── service/
│   ├── CartService.java            # 服务接口
│   └── impl/
│       └── CartServiceImpl.java    # 服务实现
└── util/
    └── RedisLockUtil.java          # Redis分布式锁工具
```

## 快速开始

### 环境要求

- JDK 17+
- Maven 3.6+
- Redis 6.0+

### 安装步骤

1. 克隆项目到本地
2. 启动Redis服务器
3. 修改`src/main/resources/application.properties`中的Redis连接配置
4. 运行以下命令启动应用：

```bash
mvn spring-boot:run
```

或者先打包再运行：

```bash
mvn clean package
java -jar target/cart-system-0.0.1-SNAPSHOT.jar
```

### 配置说明

在`application.properties`中配置Redis连接信息：

```properties
# Redis配置
spring.redis.host=localhost
spring.redis.port=6379
spring.redis.password=
spring.redis.database=0
```

## API文档

完整的API文档请参考`cart-api.yaml`文件，以下是主要接口概览：

### 1. 加菜

**请求**: `POST /api/cart/{sessionId}/items`

```json
{
  "user": {
    "userId": "user-001",
    "nickname": "张三"
  },
  "items": [
    {
      "dishId": "dish-001",
      "dishName": "宫保鸡丁",
      "count": 2
    }
  ]
}
```

### 2. 减菜

**请求**: `DELETE /api/cart/{sessionId}/items`

```json
{
  "user": {
    "userId": "user-001",
    "nickname": "张三"
  },
  "items": [
    {
      "dishId": "dish-001",
      "count": 1
    }
  ]
}
```

### 3. 查询购物车

**请求**: `GET /api/cart/{sessionId}`

**响应**:
```json
{
  "sessionId": "session-12345",
  "items": [
    {
      "dishId": "dish-001",
      "dishName": "宫保鸡丁",
      "totalCount": 5,
      "userDetails": [
        {
          "userId": "user-001",
          "nickname": "张三",
          "count": 2
        },
        {
          "userId": "user-002",
          "nickname": "李四",
          "count": 3
        }
      ]
    }
  ]
}
```

### 4. 清空购物车

**请求**: `DELETE /api/cart/{sessionId}`

## 使用示例

### JavaScript示例

```javascript
// 添加菜品
fetch('http://localhost:8080/api/cart/session-12345/items', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    user: {
      userId: 'user-001',
      nickname: '张三'
    },
    items: [
      {
        dishId: 'dish-001',
        dishName: '宫保鸡丁',
        count: 2
      }
    ]
  })
})
.then(response => response.json())
.then(data => console.log(data));

// 查询购物车
fetch('http://localhost:8080/api/cart/session-12345')
.then(response => response.json())
.then(data => console.log(data));
```

## 核心设计

### 数据模型

购物车数据使用Redis Hash存储，键格式为`app:cart:v1:{sessionId}`，每个菜品存储为JSON字符串，包含菜品信息和用户点餐详情。

### 并发控制

使用Redis分布式锁确保并发操作的安全性，防止数据不一致。锁键格式为`app:lock:cart:{sessionId}`。

### 多人协作

通过sessionId关联同一个购物车，购物车中记录每个用户对每个菜品的点餐数量，查询时按菜品ID合并，显示总数量和用户明细列表。

## 异常处理

系统实现了完善的异常处理机制：

- `CartException`: 购物车操作异常
- `CartNotFoundException`: 购物车未找到
- `ItemNotFoundException`: 菜品未找到
- `InvalidParameterException`: 无效参数
- `JsonProcessingException`: JSON处理异常

所有异常通过`GlobalExceptionHandler`统一处理，返回格式化的错误响应。

## 性能优化

1. **Redis事务**: 减少网络往返次数，提高性能
2. **分布式锁超时**: 防止死锁，设置合理的锁超时时间
3. **动态过期策略**: 默认24小时，访问后延长至48小时
4. **批量操作**: 支持单个和批量添加/减少菜品

## 测试

项目已通过全面测试，包括：
- 功能测试
- 并发测试
- 错误场景测试

可以使用Postman或其他API测试工具进行测试。

## 文档

- [API文档](cart-api.yaml) - 完整的OpenAPI 3.0.3规范

## 许可证

本项目仅供学习和研究使用。

## 贡献

欢迎提交Issue和Pull Request来改进这个项目。