pansou/docs/插件开发指南.md

PanSou 插件开发指南

概述

PanSou 采用异步插件架构，支持通过插件扩展搜索来源。插件系统基于 Go 接口设计，提供高性能的并发搜索能力和智能缓存机制。

系统架构

核心组件

• 插件管理器 (PluginManager): 管理所有插件的注册和调度
• 异步插件 (AsyncSearchPlugin): 实现异步搜索接口的插件
• 基础插件 (BaseAsyncPlugin): 提供通用功能的基础结构
• 工作池: 管理并发请求和资源限制
• 缓存系统: 二级缓存提供高性能数据存储

异步处理机制

1. 双级超时控制:

   • 短超时 (4秒): 确保快速响应用户
   • 长超时 (30秒): 允许完整数据处理

2. 渐进式结果返回:

   • isFinal=false: 部分结果，继续后台处理
   • isFinal=true: 完整结果，停止处理

3. 智能缓存更新:

   • 实时更新主缓存 (内存+磁盘)
   • 结果合并去重
   • 用户无感知数据更新

插件接口规范

AsyncSearchPlugin 接口

type AsyncSearchPlugin interface {
    // Name 返回插件名称 (必须唯一)
    Name() string
    
    // Priority 返回插件优先级 (1-4，数字越小优先级越高，影响搜索结果排序)
    Priority() int
    
    // AsyncSearch 异步搜索方法 (核心方法)
    AsyncSearch(keyword string, searchFunc func(*http.Client, string, map[string]interface{}) ([]model.SearchResult, error), mainCacheKey string, ext map[string]interface{}) ([]model.SearchResult, error)
    
    // SetMainCacheKey 设置主缓存键 (由系统调用)
    SetMainCacheKey(key string)
    
    // SetCurrentKeyword 设置当前搜索关键词 (用于日志显示)
    SetCurrentKeyword(keyword string)
    
    // Search 同步搜索方法 (兼容性方法)
    Search(keyword string, ext map[string]interface{}) ([]model.SearchResult, error)
    
    // SkipServiceFilter 返回是否跳过Service层的关键词过滤 (新增功能)
    // 对于磁力搜索等需要宽泛结果的插件，应返回true
    SkipServiceFilter() bool
}

参数说明

• keyword: 搜索关键词
• searchFunc: HTTP搜索函数，处理实际的网络请求
• mainCacheKey: 主缓存键，用于缓存管理
• ext: 扩展参数，支持自定义搜索选项

Service层过滤控制 (新功能)

PanSou支持插件级别的Service层过滤控制，允许插件自主决定是否在Service层进行关键词过滤：

过滤机制说明

1. 插件层过滤: 在插件内部使用 FilterResultsByKeyword() 进行精确过滤
2. Service层过滤: 在 search_service.go 的 mergeResultsByType() 中进行二次过滤
3. 双层过滤问题: 某些插件（如磁力搜索）需要更宽泛的搜索结果，二次过滤会误删有效结果

适用场景

应该跳过Service层过滤的插件类型:

• ✅ 磁力搜索插件: 如 thepiratebay，标题格式特殊（点号分隔），需要宽泛匹配
• ✅ 国外资源插件: 英文资源标题与中文关键词匹配度低
• ✅ 特殊格式插件: 标题包含大量符号或编码，标准过滤可能失效
• ✅ 聚合搜索插件: 需要保留所有相关结果供用户筛选

应该保持Service层过滤的插件类型:

• ⚠️ 网盘搜索插件: 标准中文资源，过滤有助于提高精确度
• ⚠️ API接口插件: 结构化数据，关键词匹配准确
• ⚠️ 论坛爬取插件: 标题格式标准，过滤效果良好

插件优先级系统

优先级等级

PanSou 采用4级插件优先级系统，直接影响搜索结果的排序权重：

等级	得分	适用场景	示例插件
等级1	1000分	高质量、稳定可靠的数据源	panta, zhizhen, labi
等级2	500分	质量良好、响应稳定的数据源	huban, shandian, duoduo
等级3	0分	普通质量的数据源	pansearch, hunhepan, pan666
等级4	-200分	质量较低或不稳定的数据源	-

排序算法影响

插件优先级在PanSou的多维度排序算法中占据主导地位：

总得分 = 插件得分(1000/500/0/-200) + 时间得分(最高500) + 关键词得分(最高420)

权重分配：

• 🥇 插件等级: ~52% (主导因素)
• 🥈 关键词匹配: ~22% (重要因素)
• 🥉 时间新鲜度: ~26% (重要因素)

实际效果：

• 等级1插件的结果通常排在前列
• 即使是较旧的等级1插件结果，也会优于新的等级3插件结果
• 包含优先关键词的等级2插件可能超越等级1插件

如何选择优先级

在开发新插件时，应根据以下标准选择合适的优先级：

选择等级1的条件

• ✅ 数据源质量极高，很少出现无效链接
• ✅ 服务稳定性好，响应时间短
• ✅ 数据更新频率高，内容新颖
• ✅ 链接有效性高（>90%）

选择等级2的条件

• ✅ 数据源质量良好，偶有无效链接
• ✅ 服务相对稳定，响应时间适中
• ✅ 数据更新较为及时
• ✅ 链接有效性中等（70-90%）

选择等级3的条件

• ⚠️ 数据源质量一般，存在一定比例无效链接
• ⚠️ 服务稳定性一般，可能偶有超时
• ⚠️ 数据更新不够及时
• ⚠️ 链接有效性较低（50-70%）

选择等级4的条件

• ❌ 数据源质量较差，大量无效链接
• ❌ 服务不稳定，经常超时或失败
• ❌ 数据更新缓慢或过时
• ❌ 链接有效性很低（<50%）

启动时显示

系统启动时会按优先级排序显示所有已加载的插件：

已加载插件:
  - panta (优先级: 1)
  - zhizhen (优先级: 1)  
  - labi (优先级: 1)
  - huban (优先级: 2)
  - duoduo (优先级: 2)
  - pansearch (优先级: 3)
  - hunhepan (优先级: 3)

开发新插件

1. 基础结构

package myplugin

import (
    "context"
    "io"
    "net/http"
    "time"
    "pansou/model"
    "pansou/plugin"
    "pansou/util/json"  // 使用项目统一的高性能JSON工具
)

type MyPlugin struct {
    *plugin.BaseAsyncPlugin
}

func init() {
    p := &MyPlugin{
        BaseAsyncPlugin: plugin.NewBaseAsyncPlugin("myplugin", 3), // 优先级3 = 普通质量数据源
    }
    plugin.RegisterGlobalPlugin(p)
}

// 对于需要跳过Service层过滤的插件（如磁力搜索插件）
func init() {
    p := &MyMagnetPlugin{
        BaseAsyncPlugin: plugin.NewBaseAsyncPluginWithFilter("mymagnet", 4, true), // 跳过Service层过滤
    }
    plugin.RegisterGlobalPlugin(p)
}

// Search 执行搜索并返回结果（兼容性方法）
func (p *MyPlugin) Search(keyword string, ext map[string]interface{}) ([]model.SearchResult, error) {
    result, err := p.SearchWithResult(keyword, ext)
    if err != nil {
        return nil, err
    }
    return result.Results, nil
}

// SearchWithResult 执行搜索并返回包含IsFinal标记的结果（推荐方法）
func (p *MyPlugin) SearchWithResult(keyword string, ext map[string]interface{}) (model.PluginSearchResult, error) {
    return p.AsyncSearchWithResult(keyword, p.searchImpl, p.MainCacheKey, ext)
}

2. 实现搜索逻辑（⭐ 推荐实现模式）

func (p *MyPlugin) searchImpl(client *http.Client, keyword string, ext map[string]interface{}) ([]model.SearchResult, error) {
    // 1. 构建请求URL
    searchURL := fmt.Sprintf("https://api.example.com/search?q=%s", url.QueryEscape(keyword))
    
    // 2. 处理扩展参数
    if titleEn, ok := ext["title_en"].(string); ok && titleEn != "" {
        searchURL += "&title_en=" + url.QueryEscape(titleEn)
    }
    
    // 3. 创建带超时的上下文 ⭐ 重要：避免请求超时
    ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
    defer cancel()
    
    // 4. 创建请求对象 ⭐ 重要：使用context控制超时
    req, err := http.NewRequestWithContext(ctx, "GET", searchURL, nil)
    if err != nil {
        return nil, fmt.Errorf("[%s] 创建请求失败: %w", p.Name(), err)
    }
    
    // 5. 设置完整请求头 ⭐ 重要：避免反爬虫检测
    req.Header.Set("User-Agent", "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36")
    req.Header.Set("Accept", "application/json, text/plain, */*")
    req.Header.Set("Accept-Language", "zh-CN,zh;q=0.9,en;q=0.8")
    req.Header.Set("Connection", "keep-alive")
    req.Header.Set("Referer", "https://api.example.com/")
    
    // 6. 发送HTTP请求（带重试机制）⭐ 重要：提高稳定性
    resp, err := p.doRequestWithRetry(req, client)
    if err != nil {
        return nil, fmt.Errorf("[%s] 搜索请求失败: %w", p.Name(), err)
    }
    defer resp.Body.Close()
    
    // 7. 检查状态码
    if resp.StatusCode != 200 {
        return nil, fmt.Errorf("[%s] 请求返回状态码: %d", p.Name(), resp.StatusCode)
    }
    
    // 8. 解析响应
    var apiResp APIResponse
    if err := json.NewDecoder(resp.Body).Decode(&apiResp); err != nil {
        return nil, fmt.Errorf("[%s] JSON解析失败: %w", p.Name(), err)
    }
    
    // 9. 转换为标准格式
    results := make([]model.SearchResult, 0, len(apiResp.Data))
    for _, item := range apiResp.Data {
        result := model.SearchResult{
            UniqueID:  fmt.Sprintf("%s-%s", p.Name(), item.ID),
            Title:     item.Title,
            Content:   item.Description,
            Datetime:  item.CreateTime,
            Tags:      item.Tags,
            Links:     convertLinks(item.Links), // 转换链接格式
        }
        results = append(results, result)
    }
    
    // 10. 关键词过滤
    return plugin.FilterResultsByKeyword(results, keyword), nil
}

// doRequestWithRetry 带重试机制的HTTP请求 ⭐ 重要：提高稳定性
func (p *MyPlugin) doRequestWithRetry(req *http.Request, client *http.Client) (*http.Response, error) {
    maxRetries := 3
    var lastErr error
    
    for i := 0; i < maxRetries; i++ {
        if i > 0 {
            // 指数退避重试
            backoff := time.Duration(1<<uint(i-1)) * 200 * time.Millisecond
            time.Sleep(backoff)
        }
        
        // 克隆请求避免并发问题
        reqClone := req.Clone(req.Context())
        
        resp, err := client.Do(reqClone)
        if err == nil && resp.StatusCode == 200 {
            return resp, nil
        }
        
        if resp != nil {
            resp.Body.Close()
        }
        lastErr = err
    }
    
    return nil, fmt.Errorf("重试 %d 次后仍然失败: %w", maxRetries, lastErr)
}

3. 链接转换与 work_title 字段

Link 结构定义

type Link struct {
    Type      string    `json:"type"`                                    // 网盘类型
    URL       string    `json:"url"`                                     // 链接地址
    Password  string    `json:"password"`                                // 提取码/密码
    Datetime  time.Time `json:"datetime,omitempty"`                      // 链接更新时间（可选）
    WorkTitle string    `json:"work_title,omitempty"`                    // 作品标题（重要：用于区分同一消息中多个作品的链接）
}

work_title 字段详解

字段作用:

• 用于区分同一条消息/结果中包含的多个不同作品的链接
• 特别适用于论坛帖子、TG频道消息等一次性发布多部影视资源的场景

使用场景示例:

📺 TG频道消息示例：
【今日更新】多部热门剧集
1. 凡人修仙传 第30集
   夸克：https://pan.quark.cn/s/abc123
2. 唐朝诡事录 第20集
   夸克：https://pan.quark.cn/s/def456
3. 庆余年2 全集
   百度：https://pan.baidu.com/s/xyz789?pwd=abcd

不使用 work_title 的问题:

• 所有链接的标题都是 "【今日更新】多部热门剧集"
• 用户无法区分哪个链接对应哪部剧集

使用 work_title 后的效果:

links := []model.Link{
    {
        Type:      "quark",
        URL:       "https://pan.quark.cn/s/abc123",
        WorkTitle: "凡人修仙传 第30集",  // 独立作品标题
    },
    {
        Type:      "quark", 
        URL:       "https://pan.quark.cn/s/def456",
        WorkTitle: "唐朝诡事录 第20集",  // 独立作品标题
    },
    {
        Type:      "baidu",
        URL:       "https://pan.baidu.com/s/xyz789?pwd=abcd",
        Password:  "abcd",
        WorkTitle: "庆余年2 全集",       // 独立作品标题
    },
}

PanSou系统的智能处理:

PanSou 会根据消息中的链接数量自动决定是否提取 work_title：

1. 链接数量 ≤ 4：所有链接使用相同的 work_title（即消息标题）

   // 示例：一条消息只包含同一部剧的不同网盘链接
   // 消息标题："凡人修仙传 第30集"
   // 链接1(夸克)、链接2(百度) → work_title 都是 "凡人修仙传 第30集"
   

2. 链接数量 > 4：系统智能识别每个链接对应的作品标题

   // 示例：一条消息包含5个不同作品的链接
   // 系统会分析消息文本，为每个链接提取独立的 work_title
   

插件实现 work_title 的两种方式:

方式1: 依赖系统自动提取（适用于TG频道、论坛等）

// 直接返回链接，系统会自动调用 extractWorkTitlesForLinks 进行处理
links := []model.Link{
    {Type: "quark", URL: "https://pan.quark.cn/s/abc123"},
    {Type: "baidu", URL: "https://pan.baidu.com/s/xyz789"},
}
// PanSou会根据消息文本自动为每个链接提取work_title

方式2: 插件手动设置（适用于API插件、磁力搜索等）

// 插件直接设置 work_title（如feikuai、thepiratebay等）
links := []model.Link{
    {
        Type:      "magnet",
        URL:       magnetURL,
        WorkTitle: buildWorkTitle(keyword, fileName), // 插件自己构建
        Datetime:  publishedTime,
    },
}

插件开发建议:

• 网盘API插件: 如果API直接返回单一作品，可以不设置 work_title（留空）
• 磁力搜索插件: 建议设置 work_title，特别是文件名不含中文时需要拼接关键词
• 爬虫插件: 如果能从页面提取每个链接的独立标题，建议设置 work_title

支持的网盘类型

PanSou系统支持以下网盘类型的自动识别（完整列表）：

网盘类型	类型标识	域名特征	说明
夸克网盘	quark	pan.quark.cn	主流网盘
UC网盘	uc	drive.uc.cn	主流网盘
百度网盘	baidu	pan.baidu.com	主流网盘
阿里云盘	aliyun	aliyundrive.com, alipan.com	主流网盘
迅雷网盘	xunlei	pan.xunlei.com	主流网盘
天翼云盘	tianyi	cloud.189.cn	主流网盘
115网盘	115	115.com,115cdn.com,anxia.com	主流网盘
123网盘	123	123pan.com,123684.com,123685.com,123912.com,123pan.cn,123592.com	主流网盘
移动云盘	mobile	caiyun.139.com	其他网盘
PikPak	pikpak	mypikpak.com	其他网盘
磁力链接	magnet	magnet:?xt=urn:btih:	磁力链接
ED2K链接	ed2k	ed2k://	磁力链接

func convertLinks(apiLinks []APILink) []model.Link {
    links := make([]model.Link, 0, len(apiLinks))
    for _, apiLink := range apiLinks {
        link := model.Link{
            Type:     determineCloudType(apiLink.URL), // 自动识别网盘类型
            URL:      apiLink.URL,
            Password: apiLink.Password,
        }
        links = append(links, link)
    }
    return links
}

func determineCloudType(url string) string {
    switch {
    case strings.Contains(url, "pan.quark.cn"):
        return "quark"
    case strings.Contains(url, "drive.uc.cn"):
        return "uc"
    case strings.Contains(url, "pan.baidu.com"):
        return "baidu"
    case strings.Contains(url, "aliyundrive.com") || strings.Contains(url, "alipan.com"):
        return "aliyun"
    case strings.Contains(url, "pan.xunlei.com"):
        return "xunlei"
    case strings.Contains(url, "cloud.189.cn"):
        return "tianyi"
    case strings.Contains(url, "115.com") || strings.Contains(url, "115cdn.com") || strings.Contains(url, "anxia.com"):
        return "115"
    case strings.Contains(url, "123684.com") || strings.Contains(url, "123685.com") || 
		strings.Contains(url, "123912.com") || strings.Contains(url, "123pan.com") || 
		strings.Contains(url, "123pan.cn") || strings.Contains(url, "123592.com"): 
		return "123"
    case strings.Contains(url, "caiyun.139.com"):
        return "mobile"
    case strings.Contains(url, "mypikpak.com"):
        return "pikpak"
    case strings.Contains(url, "magnet:"):
        return "magnet"
    case strings.Contains(url, "ed2k://"):
        return "ed2k"
    default:
        return "others"
    }
}

// 使用示例
func convertAPILinks(apiLinks []APILink) []model.Link {
    links := make([]model.Link, 0, len(apiLinks))
    for _, apiLink := range apiLinks {
        // 自动识别网盘类型
        cloudType := determineCloudType(apiLink.URL)
        
        // 只添加识别成功的链接
        if cloudType != "others" || strings.HasPrefix(apiLink.URL, "http") {
            link := model.Link{
                Type:     cloudType,
                URL:      apiLink.URL,
                Password: apiLink.Password,
            }
            links = append(links, link)
        }
    }
    return links
}

高级特性

1. 插件Web路由注册（自定义HTTP接口）

概述

PanSou 支持插件注册自定义的 HTTP 路由，用于实现插件专属的管理页面、配置接口或其他Web功能。

典型应用场景:

• 插件配置管理界面（如 QQPD 的用户登录和频道管理）
• 插件数据查询接口
• 插件状态监控页面
• OAuth回调接口

接口定义

// PluginWithWebHandler 支持Web路由的插件接口
// 插件可以选择实现此接口来注册自定义的HTTP路由
type PluginWithWebHandler interface {
    AsyncSearchPlugin // 继承搜索插件接口
    
    // RegisterWebRoutes 注册Web路由
    // router: gin的路由组，插件可以在此注册自己的路由
    RegisterWebRoutes(router *gin.RouterGroup)
}

实现步骤

步骤1: 插件结构实现接口

package myplugin

import (
    "github.com/gin-gonic/gin"
    "pansou/plugin"
    "pansou/model"
)

type MyPlugin struct {
    *plugin.BaseAsyncPlugin
    // ... 其他字段
}

// 确保插件实现了 PluginWithWebHandler 接口
var _ plugin.PluginWithWebHandler = (*MyPlugin)(nil)

步骤2: 实现 RegisterWebRoutes 方法

// RegisterWebRoutes 注册Web路由
func (p *MyPlugin) RegisterWebRoutes(router *gin.RouterGroup) {
    // 创建插件专属的路由组
    myGroup := router.Group("/myplugin")
    
    // 注册GET路由
    myGroup.GET("/status", p.handleGetStatus)
    
    // 注册POST路由
    myGroup.POST("/config", p.handleUpdateConfig)
    
    // 支持动态路径参数
    myGroup.GET("/:id", p.handleGetByID)
    myGroup.POST("/:id/action", p.handleAction)
}

步骤3: 实现路由处理函数

// handleGetStatus 获取插件状态
func (p *MyPlugin) handleGetStatus(c *gin.Context) {
    c.JSON(200, gin.H{
        "status": "ok",
        "plugin": p.Name(),
        "version": "1.0.0",
    })
}

// handleUpdateConfig 更新插件配置
func (p *MyPlugin) handleUpdateConfig(c *gin.Context) {
    var config map[string]interface{}
    
    if err := c.BindJSON(&config); err != nil {
        c.JSON(400, gin.H{"error": "Invalid JSON"})
        return
    }
    
    // 处理配置更新逻辑
    // ...
    
    c.JSON(200, gin.H{
        "success": true,
        "message": "配置已更新",
    })
}

// handleGetByID 根据ID获取数据
func (p *MyPlugin) handleGetByID(c *gin.Context) {
    id := c.Param("id")
    
    // 根据ID查询数据
    // ...
    
    c.JSON(200, gin.H{
        "id": id,
        "data": "...",
    })
}

实际案例: QQPD 插件

QQPD 插件实现了完整的用户管理和频道配置功能：

// RegisterWebRoutes 注册Web路由
func (p *QQPDPlugin) RegisterWebRoutes(router *gin.RouterGroup) {
    qqpd := router.Group("/qqpd")
    
    // GET /:param - 显示管理页面（HTML）
    qqpd.GET("/:param", p.handleManagePage)
    
    // POST /:param - 处理管理操作（JSON API）
    qqpd.POST("/:param", p.handleManagePagePOST)
}

// handleManagePage 渲染管理页面
func (p *QQPDPlugin) handleManagePage(c *gin.Context) {
    param := c.Param("param")
    
    // 生成用户专属的管理页面
    html := strings.ReplaceAll(HTMLTemplate, "HASH_PLACEHOLDER", param)
    
    c.Header("Content-Type", "text/html; charset=utf-8")
    c.String(200, html)
}

// handleManagePagePOST 处理管理操作
func (p *QQPDPlugin) handleManagePagePOST(c *gin.Context) {
    param := c.Param("param")
    
    var req struct {
        Action   string   `json:"action"`
        Channels []string `json:"channels,omitempty"`
        Keyword  string   `json:"keyword,omitempty"`
    }
    
    if err := c.BindJSON(&req); err != nil {
        respondError(c, "无效的请求格式")
        return
    }
    
    // 根据不同的 action 执行不同的操作
    switch req.Action {
    case "get_status":
        p.handleGetStatus(c, param)
    case "set_channels":
        p.handleSetChannels(c, param, req.Channels)
    case "test_search":
        p.handleTestSearch(c, param, req.Keyword)
    case "logout":
        p.handleLogout(c, param)
    default:
        respondError(c, "未知的操作")
    }
}

实际案例: Gying 插件

// RegisterWebRoutes 注册Web路由
func (p *GyingPlugin) RegisterWebRoutes(router *gin.RouterGroup) {
    gying := router.Group("/gying")
    gying.GET("/:param", p.handleManagePage)
    gying.POST("/:param", p.handleManagePagePOST)
}

路由访问示例

插件注册的路由可以通过以下方式访问：

# QQPD 插件管理页面
GET  http://localhost:8888/qqpd/user123

# QQPD 插件配置接口
POST http://localhost:8888/qqpd/user123
Content-Type: application/json
{
  "action": "set_channels",
  "channels": ["pd97631607", "kuake12345"]
}

# 自定义插件接口
GET  http://localhost:8888/myplugin/status
POST http://localhost:8888/myplugin/config
GET  http://localhost:8888/myplugin/resource123

系统集成

PanSou 在启动时会自动扫描并注册所有实现了 PluginWithWebHandler 接口的插件路由：

// api/router.go 中的自动注册逻辑
func SetupRouter(searchService *service.SearchService) *gin.Engine {
    r := gin.Default()
    
    // ... 其他路由配置 ...
    
    // 注册插件的Web路由（如果插件实现了PluginWithWebHandler接口）
    allPlugins := plugin.GetRegisteredPlugins()
    for _, p := range allPlugins {
        if webPlugin, ok := p.(plugin.PluginWithWebHandler); ok {
            webPlugin.RegisterWebRoutes(r.Group(""))
        }
    }
    
    return r
}

开发建议

1. 路由命名规范: 使用插件名作为路由前缀，避免与其他插件冲突

   // ✅ 推荐
   router.Group("/myplugin")
   
   // ❌ 避免
   router.Group("/config")  // 可能与其他插件冲突
   

2. 安全考虑:

   • 对敏感操作进行身份验证
   • 验证用户输入，防止注入攻击
   • 使用哈希或加密保护敏感参数

3. 错误处理: 统一错误响应格式

   func respondError(c *gin.Context, message string) {
       c.JSON(400, gin.H{
           "success": false,
           "message": message,
       })
   }
   
   func respondSuccess(c *gin.Context, message string, data interface{}) {
       c.JSON(200, gin.H{
           "success": true,
           "message": message,
           "data":    data,
       })
   }
   

4. HTML模板: 可以内嵌HTML模板提供管理界面

   const HTMLTemplate = `<!DOCTYPE html>
   <html>
   <head>
       <title>插件管理</title>
   </head>
   <body>
       <h1>{{ .PluginName }} 管理界面</h1>
       <!-- ... -->
   </body>
   </html>`
   

5. 可选实现: Web路由是可选功能，只有需要自定义HTTP接口的插件才需要实现

2. Service层过滤控制详解

构造函数选择

// 标准插件构造函数（默认启用Service层过滤）
func NewStandardPlugin() *StandardPlugin {
    return &StandardPlugin{
        BaseAsyncPlugin: plugin.NewBaseAsyncPlugin("standard", 3), // 默认skipServiceFilter=false
    }
}

// 磁力搜索插件构造函数（跳过Service层过滤）
func NewMagnetPlugin() *MagnetPlugin {
    return &MagnetPlugin{
        BaseAsyncPlugin: plugin.NewBaseAsyncPluginWithFilter("magnet", 4, true), // skipServiceFilter=true
    }
}

实际应用示例

ThePirateBay插件示例:

// thepiratebay插件的实际实现
func NewThePirateBayPlugin() *ThePirateBayPlugin {
    return &ThePirateBayPlugin{
        BaseAsyncPlugin: plugin.NewBaseAsyncPluginWithFilter("thepiratebay", 4, true), // 跳过Service层过滤
        optimizedClient: createOptimizedHTTPClient(),
    }
}

func (p *ThePirateBayPlugin) searchImpl(client *http.Client, keyword string, ext map[string]interface{}) ([]model.SearchResult, error) {
    // 支持英文搜索优化
    searchKeyword := keyword
    if ext != nil {
        if titleEn, exists := ext["title_en"]; exists {
            if titleEnStr, ok := titleEn.(string); ok && titleEnStr != "" {
                searchKeyword = titleEnStr
            }
        }
    }
    
    // 获取搜索结果
    allResults := p.fetchAllResults(client, searchKeyword)
    
    // 标题格式优化：将'.'替换为空格，提高关键词匹配准确度
    for i := range allResults {
        allResults[i].Title = strings.ReplaceAll(allResults[i].Title, ".", " ")
    }
    
    // 插件层过滤（使用处理后的搜索关键词）
    filteredResults := plugin.FilterResultsByKeyword(allResults, searchKeyword)
    
    return filteredResults, nil
    // 注意：Service层会通过SkipServiceFilter()方法跳过二次过滤
}

过滤策略对比

过滤类型	标准插件	磁力搜索插件
插件层过滤	✅ 使用原始关键词	✅ 使用searchKeyword（支持title_en）
Service层过滤	✅ 再次过滤	❌ 跳过过滤
结果特点	精确匹配	宽泛搜索
适用场景	中文网盘资源	英文磁力资源

动态过滤检测机制

Service层通过以下机制动态判断是否需要过滤：

// service/search_service.go 中的实现
func mergeResultsByType(...) {
    // 检查插件是否需要跳过Service层过滤
    var skipKeywordFilter bool = false
    if result.UniqueID != "" && strings.Contains(result.UniqueID, "-") {
        parts := strings.SplitN(result.UniqueID, "-", 2)
        if len(parts) >= 1 {
            pluginName := parts[0]
            // 通过插件注册表动态获取过滤设置
            if pluginInstance, exists := plugin.GetPluginByName(pluginName); exists {
                skipKeywordFilter = pluginInstance.SkipServiceFilter()
            }
        }
    }
    
    // 根据插件设置决定是否过滤
    if !skipKeywordFilter && keyword != "" && !strings.Contains(strings.ToLower(title), lowerKeyword) {
        continue // 过滤掉不匹配的结果
    }
}

2. 扩展参数处理

// 支持的扩展参数示例
ext := map[string]interface{}{
    "title_en": "English Title",     // 英文标题
    "is_all":   true,               // 全量搜索标志
    "year":     2023,               // 年份限制
    "type":     "movie",            // 内容类型
}

// 在插件中处理
func (p *MyPlugin) handleExtParams(ext map[string]interface{}) searchOptions {
    opts := searchOptions{}
    
    if titleEn, ok := ext["title_en"].(string); ok {
        opts.TitleEn = titleEn
    }
    
    if isAll, ok := ext["is_all"].(bool); ok {
        opts.IsAll = isAll
    }
    
    return opts
}

2. 缓存策略

// 设置缓存TTL
p.SetCacheTTL(2 * time.Hour)

// 手动缓存更新
p.UpdateMainCache(cacheKey, results, ttl, true, keyword)

3. 错误处理

func (p *MyPlugin) searchImpl(client *http.Client, keyword string, ext map[string]interface{}) ([]model.SearchResult, error) {
    // 网络错误处理
    resp, err := client.Get(url)
    if err != nil {
        return nil, fmt.Errorf("[%s] 网络请求失败: %w", p.Name(), err)
    }
    
    // HTTP状态码检查
    if resp.StatusCode != 200 {
        return nil, fmt.Errorf("[%s] HTTP错误: %d", p.Name(), resp.StatusCode)
    }
    
    // JSON解析错误 - 推荐使用项目统一的JSON工具
    body, err := io.ReadAll(resp.Body)
    if err != nil {
        return nil, fmt.Errorf("[%s] 读取响应失败: %w", p.Name(), err)
    }
    
    var apiResp APIResponse
    if err := json.Unmarshal(body, &apiResp); err != nil {
        return nil, fmt.Errorf("[%s] JSON解析失败: %w", p.Name(), err)
    }
    
    // 业务逻辑错误
    if apiResp.Code != 0 {
        return nil, fmt.Errorf("[%s] API错误: %s", p.Name(), apiResp.Message)
    }
    
    return results, nil
}

性能优化

1. HTTP客户端优化

// 使用连接池
client := &http.Client{
    Timeout: 30 * time.Second,
    Transport: &http.Transport{
        MaxIdleConns:        100,
        MaxIdleConnsPerHost: 10,
        IdleConnTimeout:     90 * time.Second,
    },
}

2. 内存优化

// 预分配切片容量
results := make([]model.SearchResult, 0, expectedCount)

// 及时释放大对象
defer func() {
    apiResp = APIResponse{}
}()

3. 并发控制

// 使用插件内置的工作池，避免创建过多goroutine
// BaseAsyncPlugin 已经提供了工作池管理

测试和调试

1. 单元测试

func TestMyPlugin_Search(t *testing.T) {
    plugin := &MyPlugin{
        BaseAsyncPlugin: plugin.NewBaseAsyncPlugin("test", 3),
    }
    
    results, err := plugin.Search("测试关键词", nil)
    assert.NoError(t, err)
    assert.NotEmpty(t, results)
}

2. 集成测试

# 使用API测试插件
curl "http://localhost:8888/api/search?kw=测试&plugins=myplugin"

3. 性能测试

# 使用压力测试脚本
python3 stress_test.py

部署和配置

1. 插件注册

确保在 init() 函数中注册插件：

func init() {
    p := &MyPlugin{
        BaseAsyncPlugin: plugin.NewBaseAsyncPlugin("myplugin", 3),
    }
    plugin.RegisterGlobalPlugin(p)
}

2. 环境配置

# 异步插件配置
export ASYNC_PLUGIN_ENABLED=true
export ASYNC_RESPONSE_TIMEOUT=4
export ASYNC_MAX_BACKGROUND_WORKERS=40
export ASYNC_MAX_BACKGROUND_TASKS=200

3. 生产部署注意事项

1. 资源限制: 根据服务器配置调整工作池大小
2. 监控告警: 监控插件响应时间和错误率
3. 日志管理: 合理设置日志级别，避免日志过多
4. 缓存配置: 根据数据更新频率调整缓存TTL

现有插件参考

标准网盘搜索插件

• jikepan - 标准网盘插件，启用Service层过滤
• pan666 - 标准网盘插件，启用Service层过滤
• hunhepan - 标准网盘插件，启用Service层过滤
• pansearch - 标准网盘插件，启用Service层过滤
• qupansou - 标准网盘插件，启用Service层过滤
• panta - 高质量网盘插件，启用Service层过滤

特殊搜索插件

• thepiratebay - 磁力搜索插件，跳过Service层过滤，支持title_en参数，标题格式化处理

插件开发最佳实践 ⭐

核心原则

1. 命名规范: 插件名使用小写字母和数字
2. 优先级设置: 1-2为高优先级，3为标准，4-5为低优先级
3. 关键词过滤: 使用 FilterResultsByKeyword 提高结果相关性
4. 缓存友好: 合理设置缓存TTL，避免频繁请求
5. 资源清理: 及时关闭连接和释放资源
6. 过滤策略: 根据插件类型选择合适的Service层过滤策略

必须实现的优化点

1. Service层过滤策略选择 ⭐ 新功能

// ✅ 磁力搜索插件 - 跳过Service层过滤
func NewMagnetSearchPlugin() *MagnetSearchPlugin {
    return &MagnetSearchPlugin{
        BaseAsyncPlugin: plugin.NewBaseAsyncPluginWithFilter("magnet", 4, true), // skipServiceFilter=true
    }
}

// ✅ 标准网盘插件 - 启用Service层过滤  
func NewPanSearchPlugin() *PanSearchPlugin {
    return &PanSearchPlugin{
        BaseAsyncPlugin: plugin.NewBaseAsyncPlugin("pansearch", 3), // 默认skipServiceFilter=false
    }
}

选择指南:

• 跳过过滤 (true): 磁力搜索、英文资源、特殊格式标题、聚合搜索
• 启用过滤 (false): 网盘搜索、中文资源、API接口、标准格式标题

注意事项:

• 跳过Service层过滤的插件必须在插件内部进行FilterResultsByKeyword过滤
• 插件层过滤使用的关键词应与实际搜索关键词一致（支持title_en等参数）
• 标题格式化处理应在过滤之前进行（如将"." 替换为" "）

2. SearchResult字段设置规范 ⭐ 重要

// ✅ 正确的SearchResult设置
result := model.SearchResult{
    UniqueID: fmt.Sprintf("%s-%s", p.Name(), itemID),  // 插件名-资源ID
    Title:    title,                                   // 资源标题
    Content:  description,                             // 资源描述
    Links:    downloadLinks,                           // 下载链接列表
    Tags:     tags,                                    // 分类标签
    Channel:  "",                                      // ⭐ 重要：插件搜索结果必须为空字符串
    Datetime: time.Now(),                              // 发布时间
}

// ❌ 错误的Channel设置
result.Channel = p.Name()  // 不要设置为插件名！

Channel字段使用规则:

• 插件搜索结果: Channel 必须为空字符串 ""
• Telegram频道: Channel 才设置为频道名称
• 目的: 区分搜索来源，便于前端展示和后端统计

Links字段处理规则 ⭐ 重要:

• 必须有链接: 系统会自动过滤掉 Links 为空或长度为0的结果
• 链接质量: 确保返回的链接都是有效的网盘链接，避免返回无效链接
• 链接验证: 建议使用 isValidNetworkDriveURL() 函数预先验证链接有效性

2. HTTP请求最佳实践 ⭐ 重要

// ✅ 正确的请求实现
func (p *MyPlugin) makeRequest(url string, client *http.Client) (*http.Response, error) {
    // 使用context控制超时
    ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
    defer cancel()
    
    // 创建请求
    req, err := http.NewRequestWithContext(ctx, "GET", url, nil)
    if err != nil {
        return nil, err
    }
    
    // 设置完整的请求头（避免反爬虫）
    req.Header.Set("User-Agent", "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36")
    req.Header.Set("Accept", "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8")
    req.Header.Set("Accept-Language", "zh-CN,zh;q=0.9,en;q=0.8")
    req.Header.Set("Connection", "keep-alive")
    req.Header.Set("Referer", "https://example.com/")
    
    // 使用重试机制
    return p.doRequestWithRetry(req, client)
}

// ❌ 错误的简单实现
func (p *MyPlugin) badRequest(url string, client *http.Client) (*http.Response, error) {
    return client.Get(url) // 没有超时控制、没有请求头、没有重试
}

2. 实现高级搜索接口 ⭐ 推荐

// ✅ 推荐：实现两个方法
func (p *MyPlugin) Search(keyword string, ext map[string]interface{}) ([]model.SearchResult, error) {
    result, err := p.SearchWithResult(keyword, ext)
    if err != nil {
        return nil, err
    }
    return result.Results, nil
}

func (p *MyPlugin) SearchWithResult(keyword string, ext map[string]interface{}) (model.PluginSearchResult, error) {
    return p.AsyncSearchWithResult(keyword, p.searchImpl, p.MainCacheKey, ext)
}

3. 错误处理增强 ⭐ 重要

// ✅ 详细的错误信息
if resp.StatusCode != 200 {
    return nil, fmt.Errorf("[%s] 请求失败，状态码: %d", p.Name(), resp.StatusCode)
}

// ✅ 包装外部错误
if err := json.NewDecoder(resp.Body).Decode(&data); err != nil {
    return nil, fmt.Errorf("[%s] JSON解析失败: %w", p.Name(), err)
}

4. 重试机制模板 ⭐ 复制可用

func (p *MyPlugin) doRequestWithRetry(req *http.Request, client *http.Client) (*http.Response, error) {
    maxRetries := 3
    var lastErr error
    
    for i := 0; i < maxRetries; i++ {
        if i > 0 {
            backoff := time.Duration(1<<uint(i-1)) * 200 * time.Millisecond
            time.Sleep(backoff)
        }
        
        reqClone := req.Clone(req.Context())
        resp, err := client.Do(reqClone)
        if err == nil && resp.StatusCode == 200 {
            return resp, nil
        }
        
        if resp != nil {
            resp.Body.Close()
        }
        lastErr = err
    }
    
    return nil, fmt.Errorf("重试 %d 次后仍然失败: %w", maxRetries, lastErr)
}

5. 请求头模板 ⭐ 复制可用

// HTML页面请求头
req.Header.Set("User-Agent", "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36")
req.Header.Set("Accept", "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8")
req.Header.Set("Accept-Language", "zh-CN,zh;q=0.9,en;q=0.8")
req.Header.Set("Connection", "keep-alive")
req.Header.Set("Upgrade-Insecure-Requests", "1")
req.Header.Set("Cache-Control", "max-age=0")
req.Header.Set("Referer", "https://example.com/")

// JSON API请求头
req.Header.Set("User-Agent", "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36")
req.Header.Set("Accept", "application/json, text/plain, */*")
req.Header.Set("Accept-Language", "zh-CN,zh;q=0.9,en;q=0.8")
req.Header.Set("Connection", "keep-alive")
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Referer", "https://example.com/")

常见问题避免

1. 不要使用 client.Get(url) - 缺少超时控制和请求头
2. 不要忘记设置 User-Agent - 很多网站会阻止空UA请求
3. 不要忘记错误上下文 - 使用 fmt.Errorf("[%s] 错误描述: %w", p.Name(), err)
4. 不要忘记关闭响应体 - defer resp.Body.Close()
5. 不要在循环中创建大量goroutine - 使用信号量控制并发数
6. Service层过滤常见问题:
   • ❌ 跳过Service层过滤但不在插件内过滤 - 会返回大量无关结果
   • ❌ 磁力搜索插件使用默认构造函数 - 会被Service层误过滤
   • ❌ 过滤关键词不一致 - 插件用title_en搜索但用原keyword过滤
   • ❌ 标题格式化在过滤之后 - 格式化不会改善过滤效果