262 lines
6.5 KiB
Markdown
262 lines
6.5 KiB
Markdown
# 内容搜索API接口文档
|
||
|
||
## 概述
|
||
|
||
本系统提供了统一的内容搜索功能，支持搜索工作流和课程两种类型的内容。所有搜索接口均支持匿名访问，无需登录认证。
|
||
|
||
## 接口列表
|
||
|
||
### 1. 基础搜索接口
|
||
|
||
**GET** `/user/search`
|
||
|
||
#### 请求参数
|
||
|
||
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|
||
|--------|------|------|--------|------|
|
||
| keyword | String | 是 | - | 搜索关键词，至少2个字符 |
|
||
| type | String | 否 | all | 内容类型：all/course/workflow |
|
||
| category | String | 否 | - | 分类过滤 |
|
||
| freeOnly | Boolean | 否 | false | 是否仅显示免费内容 |
|
||
| sortBy | String | 否 | relevance | 排序方式：relevance/createTime/updateTime/viewCount/likeCount |
|
||
| sortOrder | String | 否 | desc | 排序方向：asc/desc |
|
||
| page | Integer | 否 | 1 | 页码，从1开始 |
|
||
| size | Integer | 否 | 20 | 每页数量，最大100 |
|
||
|
||
#### 请求示例
|
||
|
||
```http
|
||
GET /user/search?keyword=AI图像处理&type=all&freeOnly=false&page=1&size=20
|
||
```
|
||
|
||
#### 响应示例
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "操作成功",
|
||
"data": {
|
||
"total": 156,
|
||
"page": 1,
|
||
"size": 20,
|
||
"totalPages": 8,
|
||
"keyword": "AI图像处理",
|
||
"items": [
|
||
{
|
||
"id": 1,
|
||
"type": "course",
|
||
"title": "AI图像处理入门课程",
|
||
"description": "学习AI图像处理的基础知识和实践技巧",
|
||
"coverUrl": "https://example.com/cover1.jpg",
|
||
"price": "29.99",
|
||
"category": "人工智能",
|
||
"isFree": false,
|
||
"likeCount": 2300,
|
||
"level": 1,
|
||
"duration": "15:30",
|
||
"viewCount": 12500,
|
||
"commentCount": 856,
|
||
"vipType": "normal",
|
||
"creator": {
|
||
"id": "17543607206742139",
|
||
"username": "张三",
|
||
"avatarUrl": "https://example.com/avatar1.jpg"
|
||
},
|
||
"createTime": "2024-01-15T10:30:00",
|
||
"updateTime": "2024-01-15T10:30:00"
|
||
},
|
||
{
|
||
"id": 2,
|
||
"type": "workflow",
|
||
"title": "智能图像生成工作流",
|
||
"description": "基于AI的智能图像生成工作流，支持多种图像风格转换",
|
||
"coverUrl": "https://example.com/cover2.jpg",
|
||
"price": "19.99",
|
||
"category": "人工智能",
|
||
"isFree": false,
|
||
"likeCount": 1250,
|
||
"rating": 5,
|
||
"creator": {
|
||
"id": "17543607206742140",
|
||
"username": "李四",
|
||
"avatarUrl": "https://example.com/avatar2.jpg"
|
||
},
|
||
"createTime": "2024-01-16T14:20:00",
|
||
"updateTime": "2024-01-16T14:20:00"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2. 高级搜索接口
|
||
|
||
**POST** `/user/search`
|
||
|
||
#### 请求体
|
||
|
||
```json
|
||
{
|
||
"keyword": "AI图像处理",
|
||
"type": "all",
|
||
"category": "人工智能",
|
||
"freeOnly": false,
|
||
"sortBy": "relevance",
|
||
"sortOrder": "desc",
|
||
"page": 1,
|
||
"size": 20
|
||
}
|
||
```
|
||
|
||
#### 响应格式
|
||
|
||
与GET接口相同。
|
||
|
||
### 3. 搜索统计接口
|
||
|
||
**GET** `/user/search/stats`
|
||
|
||
#### 请求参数
|
||
|
||
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|
||
|--------|------|------|--------|------|
|
||
| keyword | String | 是 | - | 搜索关键词 |
|
||
| type | String | 否 | all | 内容类型 |
|
||
| category | String | 否 | - | 分类过滤 |
|
||
| freeOnly | Boolean | 否 | false | 是否仅显示免费内容 |
|
||
|
||
#### 请求示例
|
||
|
||
```http
|
||
GET /user/search/stats?keyword=AI图像处理&type=all
|
||
```
|
||
|
||
#### 响应示例
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "操作成功",
|
||
"data": {
|
||
"courseCount": 89,
|
||
"workflowCount": 67,
|
||
"totalCount": 156,
|
||
"categoryStats": [
|
||
{
|
||
"categoryName": "人工智能",
|
||
"count": 45
|
||
},
|
||
{
|
||
"categoryName": "图像处理",
|
||
"count": 32
|
||
},
|
||
{
|
||
"categoryName": "机器学习",
|
||
"count": 28
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
## 数据结构说明
|
||
|
||
### SearchResultItem
|
||
|
||
| 字段名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| id | Long | 内容ID |
|
||
| type | String | 内容类型：course/workflow |
|
||
| title | String | 标题/名称 |
|
||
| description | String | 描述 |
|
||
| coverUrl | String | 封面图URL |
|
||
| price | String | 价格 |
|
||
| category | String | 分类 |
|
||
| isFree | Boolean | 是否免费 |
|
||
| likeCount | Integer | 点赞数 |
|
||
| level | Integer | 访问级别（仅课程） |
|
||
| duration | String | 课程时长（仅课程） |
|
||
| viewCount | Integer | 观看次数（仅课程） |
|
||
| commentCount | Integer | 评论数（仅课程） |
|
||
| vipType | String | VIP类型（仅课程） |
|
||
| rating | Integer | 评分（仅工作流） |
|
||
| creator | CreatorInfo | 创建者信息 |
|
||
| createTime | String | 创建时间 |
|
||
| updateTime | String | 更新时间 |
|
||
|
||
### CreatorInfo
|
||
|
||
| 字段名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| id | String | 创建者ID |
|
||
| username | String | 创建者用户名 |
|
||
| avatarUrl | String | 创建者头像URL |
|
||
|
||
### VIP类型说明
|
||
|
||
| level值 | vipType | 说明 |
|
||
|---------|---------|------|
|
||
| 0 | free | 免费用户 |
|
||
| 1 | normal | 普通用户 |
|
||
| 2 | vip | VIP用户 |
|
||
| 3+ | svip | 超级VIP用户 |
|
||
|
||
## 功能特性
|
||
|
||
### 1. 多类型内容支持
|
||
- 支持同时搜索课程和工作流
|
||
- 可通过`type`参数过滤特定类型内容
|
||
- 返回结果中明确标识内容类型
|
||
|
||
### 2. 智能搜索
|
||
- 支持标题、描述、分类的模糊匹配
|
||
- 相关度排序算法优化搜索结果
|
||
- 支持多种排序方式
|
||
|
||
### 3. 高级过滤
|
||
- 分类过滤：按内容分类筛选
|
||
- 免费内容过滤：仅显示免费内容
|
||
- 创建者信息：显示内容创建者详情
|
||
|
||
### 4. 分页支持
|
||
- 灵活的分页参数控制
|
||
- 返回完整的分页信息
|
||
- 支持大数据量搜索
|
||
|
||
### 5. 统计信息
|
||
- 提供搜索结果统计
|
||
- 分类分布统计
|
||
- 各类型内容数量统计
|
||
|
||
## 使用建议
|
||
|
||
### 1. 搜索优化
|
||
- 使用具体的关键词获得更准确的结果
|
||
- 结合分类过滤提高搜索精度
|
||
- 合理使用排序参数优化用户体验
|
||
|
||
### 2. 性能考虑
|
||
- 建议使用适当的页面大小（10-50）
|
||
- 避免过于宽泛的搜索关键词
|
||
- 优先使用GET接口进行基础搜索
|
||
|
||
### 3. 前端集成
|
||
- 实现搜索建议和自动补全
|
||
- 提供搜索历史记录
|
||
- 支持搜索结果的多种展示方式
|
||
|
||
## 错误码说明
|
||
|
||
| 错误码 | 说明 |
|
||
|--------|------|
|
||
| 400 | 请求参数错误（如关键词过短、类型无效等） |
|
||
| 500 | 服务器内部错误 |
|
||
|
||
## 注意事项
|
||
|
||
1. 所有搜索接口均支持匿名访问，无需身份认证
|
||
2. 搜索关键词最少需要2个字符
|
||
3. 搜索结果仅包含已审核通过的公开内容
|
||
4. 接口返回的价格字段为字符串格式
|
||
5. 创建者信息可能为空（对于已删除的用户账户）
|