1818web-hoduan/docs/search-api.md

内容搜索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

请求示例

GET /user/search?keyword=AI图像处理&type=all&freeOnly=false&page=1&size=20

响应示例

{
  "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

请求体

{
  "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	是否仅显示免费内容

请求示例

GET /user/search/stats?keyword=AI图像处理&type=all

响应示例

{
  "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. 创建者信息可能为空（对于已删除的用户账户）