129 lines
3.7 KiB
Markdown
129 lines
3.7 KiB
Markdown
# 产品列表接口订阅状态功能说明
|
||
|
||
## 概述
|
||
|
||
产品列表接口（`/api/v1/products`）现已支持可选认证和订阅状态功能。用户可以选择是否登录，登录后可以查看产品的订阅状态，并可以按订阅状态进行筛选。
|
||
|
||
## 功能特性
|
||
|
||
### 1. 可选认证
|
||
- 未登录用户：可以正常获取产品列表，但不会显示订阅状态
|
||
- 已登录用户：可以获取产品列表，并显示每个产品的订阅状态
|
||
|
||
### 2. 订阅状态显示
|
||
- 对于已登录用户，每个产品响应中会包含 `is_subscribed` 字段
|
||
- 该字段为 `true` 表示用户已订阅该产品，`false` 表示未订阅，`null` 表示未登录
|
||
|
||
### 3. 订阅状态筛选
|
||
- 已登录用户可以通过 `is_subscribed` 参数筛选产品
|
||
- `is_subscribed=true`：只显示已订阅的产品
|
||
- `is_subscribed=false`：只显示未订阅的产品
|
||
- 不传该参数：显示所有产品
|
||
|
||
## API 接口
|
||
|
||
### 请求地址
|
||
```
|
||
GET /api/v1/products
|
||
```
|
||
|
||
### 请求参数
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| page | int | 否 | 页码，默认1 |
|
||
| page_size | int | 否 | 每页数量，默认10 |
|
||
| keyword | string | 否 | 搜索关键词 |
|
||
| category_id | string | 否 | 分类ID |
|
||
| is_enabled | bool | 否 | 是否启用 |
|
||
| is_visible | bool | 否 | 是否可见 |
|
||
| is_package | bool | 否 | 是否组合包 |
|
||
| is_subscribed | bool | 否 | 是否已订阅（需要认证） |
|
||
| sort_by | string | 否 | 排序字段 |
|
||
| sort_order | string | 否 | 排序方向（asc/desc） |
|
||
|
||
### 响应格式
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "获取产品列表成功",
|
||
"data": {
|
||
"total": 100,
|
||
"page": 1,
|
||
"size": 10,
|
||
"items": [
|
||
{
|
||
"id": "product-id",
|
||
"name": "产品名称",
|
||
"code": "PRODUCT001",
|
||
"description": "产品描述",
|
||
"price": 99.99,
|
||
"is_enabled": true,
|
||
"is_visible": true,
|
||
"is_package": false,
|
||
"is_subscribed": true, // 新增字段：订阅状态
|
||
"category": {
|
||
"id": "category-id",
|
||
"name": "分类名称"
|
||
},
|
||
"created_at": "2024-01-01T00:00:00Z",
|
||
"updated_at": "2024-01-01T00:00:00Z"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
## 使用示例
|
||
|
||
### 1. 未登录用户获取产品列表
|
||
```bash
|
||
curl -X GET "http://localhost:8080/api/v1/products?page=1&page_size=10"
|
||
```
|
||
|
||
### 2. 已登录用户获取产品列表
|
||
```bash
|
||
curl -X GET "http://localhost:8080/api/v1/products?page=1&page_size=10" \
|
||
-H "Authorization: Bearer your-jwt-token"
|
||
```
|
||
|
||
### 3. 筛选已订阅的产品
|
||
```bash
|
||
curl -X GET "http://localhost:8080/api/v1/products?is_subscribed=true" \
|
||
-H "Authorization: Bearer your-jwt-token"
|
||
```
|
||
|
||
### 4. 筛选未订阅的产品
|
||
```bash
|
||
curl -X GET "http://localhost:8080/api/v1/products?is_subscribed=false" \
|
||
-H "Authorization: Bearer your-jwt-token"
|
||
```
|
||
|
||
## 技术实现
|
||
|
||
### 1. 数据库查询优化
|
||
- 使用 `EXISTS` 子查询来筛选订阅状态
|
||
- 批量查询用户订阅状态，减少数据库查询次数
|
||
|
||
### 2. 缓存策略
|
||
- 订阅状态查询结果会被缓存，提高查询性能
|
||
- 缓存时间设置为10分钟，可根据业务需求调整
|
||
|
||
### 3. 向后兼容
|
||
- 新功能完全向后兼容
|
||
- 未登录用户的使用体验不受影响
|
||
- 现有前端代码无需修改即可正常工作
|
||
|
||
## 注意事项
|
||
|
||
1. **认证要求**：`is_subscribed` 筛选功能需要用户登录
|
||
2. **性能考虑**：订阅状态查询会增加一定的数据库负载，建议合理使用
|
||
3. **缓存更新**：当用户订阅/取消订阅产品时，需要清除相关缓存
|
||
4. **错误处理**：如果用户ID无效，会返回空的产品列表
|
||
|
||
## 更新日志
|
||
|
||
- 2024-01-01：新增可选认证和订阅状态功能
|
||
- 2024-01-01：新增订阅状态筛选功能
|
||
- 2024-01-01：优化数据库查询性能 |