docs/插件开发指南.md
PanSou 采用异步插件架构，支持通过插件扩展搜索来源。插件系统基于 Go 接口设计，提供高性能的并发搜索能力和智能缓存机制。
双级超时控制:
渐进式结果返回:
isFinal=false: 部分结果，继续后台处理isFinal=true: 完整结果，停止处理智能缓存更新:
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
}
PanSou支持插件级别的Service层过滤控制，允许插件自主决定是否在Service层进行关键词过滤：
FilterResultsByKeyword() 进行精确过滤search_service.go 的 mergeResultsByType() 中进行二次过滤应该跳过Service层过滤的插件类型:
应该保持Service层过滤的插件类型:
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)
权重分配：
实际效果：
在开发新插件时，应根据以下标准选择合适的优先级：
系统启动时会按优先级排序显示所有已加载的插件：
已加载插件:
- panta (优先级: 1)
- zhizhen (优先级: 1)
- labi (优先级: 1)
- huban (优先级: 2)
- duoduo (优先级: 2)
- pansearch (优先级: 3)
- hunhepan (优先级: 3)
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)
}
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)
}
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"` // 作品标题（重要：用于区分同一消息中多个作品的链接）
}
字段作用:
使用场景示例:
📺 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：
链接数量 ≤ 4：所有链接使用相同的 work_title（即消息标题）
// 示例：一条消息只包含同一部剧的不同网盘链接
// 消息标题："凡人修仙传 第30集"
// 链接1(夸克)、链接2(百度) → work_title 都是 "凡人修仙传 第30集"
链接数量 > 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,
},
}
插件开发建议:
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
}
PanSou 支持插件注册自定义的 HTTP 路由，用于实现插件专属的管理页面、配置接口或其他Web功能。
典型应用场景:
// 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 插件实现了完整的用户管理和频道配置功能：
// 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, "未知的操作")
}
}
// 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
}
路由命名规范: 使用插件名作为路由前缀，避免与其他插件冲突
// ✅ 推荐
router.Group("/myplugin")
// ❌ 避免
router.Group("/config") // 可能与其他插件冲突
安全考虑:
错误处理: 统一错误响应格式
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,
})
}
HTML模板: 可以内嵌HTML模板提供管理界面
const HTMLTemplate = `<!DOCTYPE html>
<html>
<head>
<title>插件管理</title>
</head>
<body>
<h1>{{ .PluginName }} 管理界面</h1>
<!-- ... -->
</body>
</html>`
可选实现: Web路由是可选功能，只有需要自定义HTTP接口的插件才需要实现
// 标准插件构造函数（默认启用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 // 过滤掉不匹配的结果
}
}
// 支持的扩展参数示例
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
}
// 设置缓存TTL
p.SetCacheTTL(2 * time.Hour)
// 手动缓存更新
p.UpdateMainCache(cacheKey, results, ttl, true, keyword)
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
}
// 使用连接池
client := &http.Client{
Timeout: 30 * time.Second,
Transport: &http.Transport{
MaxIdleConns: 100,
MaxIdleConnsPerHost: 10,
IdleConnTimeout: 90 * time.Second,
},
}
// 预分配切片容量
results := make([]model.SearchResult, 0, expectedCount)
// 及时释放大对象
defer func() {
apiResp = APIResponse{}
}()
// 使用插件内置的工作池，避免创建过多goroutine
// BaseAsyncPlugin 已经提供了工作池管理
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)
}
# 使用API测试插件
curl "http://localhost:8888/api/search?kw=测试&plugins=myplugin"
# 使用压力测试脚本
python3 stress_test.py
确保在 init() 函数中注册插件：
func init() {
p := &MyPlugin{
BaseAsyncPlugin: plugin.NewBaseAsyncPlugin("myplugin", 3),
}
plugin.RegisterGlobalPlugin(p)
}
# 异步插件配置
export ASYNC_PLUGIN_ENABLED=true
export ASYNC_RESPONSE_TIMEOUT=4
export ASYNC_MAX_BACKGROUND_WORKERS=40
export ASYNC_MAX_BACKGROUND_TASKS=200
FilterResultsByKeyword 提高结果相关性// ✅ 磁力搜索插件 - 跳过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接口、标准格式标题注意事项:
FilterResultsByKeyword过滤title_en等参数）"." 替换为" "）// ✅ 正确的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 必须为空字符串 ""Channel 才设置为频道名称Links字段处理规则 ⭐ 重要:
Links 为空或长度为0的结果isValidNetworkDriveURL() 函数预先验证链接有效性// ✅ 正确的请求实现
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) // 没有超时控制、没有请求头、没有重试
}
// ✅ 推荐：实现两个方法
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)
}
// ✅ 详细的错误信息
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)
}
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)
}
// 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/")
client.Get(url) - 缺少超时控制和请求头fmt.Errorf("[%s] 错误描述: %w", p.Name(), err)defer resp.Body.Close()title_en搜索但用原keyword过滤