如何用Confluence API复现手动搜索效果？CQL搜索结果不符问题

一、复现手动搜索效果的具体方案 #

Confluence 手动搜索与CQL默认搜索的核心差异在于匹配逻辑：手动搜索是全文分词匹配，而CQL使用双引号时会做精确短语匹配，这也是长搜索词无结果、短词结果少的原因。按以下步骤调整即可对齐手动搜索效果：

1. 修改CQL匹配语法

   • 移除搜索词的双引号：使用 text ~ '搜索词1 搜索词2' 而非 text ~ "搜索词1 搜索词2"。前者会将搜索词拆分为独立词汇，匹配包含任意/多个词汇的页面；后者仅匹配包含完整短语的页面。
   • 开启模糊匹配（可选）：如果需要兼容拼写误差，可在词汇后加~，例如 text ~ 'searchterm~ anotherterm~'，允许单个字符的差异匹配。

2. 分页获取全部结果
   API默认单次返回结果数量有限（通常为20条），手动搜索会展示所有结果，因此需要通过start和limit参数分页遍历：

   from atlassian import Confluence
   
   confluence = Confluence(
       url="https://your-confluence-domain",
       username="your-account",
       password="your-api-token"
   )
   
   search_terms = "你的搜索关键词组合"
   start = 0
   limit = 100  # 单次最大可返回100条
   all_results = []
   
   while True:
       # 无引号的分词匹配语法
       response = confluence.cql(f'text ~ \'{search_terms}\'', start=start, limit=limit)
       results = response.get("results", [])
       if not results:
           break
       all_results.extend(results)
       start += limit
   
   print(f"总计匹配结果：{len(all_results)} 条")
   

3. 对齐权限与搜索范围

   • 确保API使用的账号与手动搜索账号权限完全一致，避免因权限不足导致私密页面不返回。
   • 如果手动搜索限定了特定空间，需在CQL中添加空间条件，例如 space = "SPACE_KEY" and text ~ '搜索词'。

4. 扩展搜索字段（可选）
   若手动搜索包含更多维度（如附件、标签），可扩展CQL条件：

   text ~ '搜索词' OR label = '标签名' OR attachment.content ~ '搜索词'
   

二、Confluence "简单"手动搜索的核心算法 #

Confluence 手动搜索基于Lucene全文检索引擎，核心逻辑包括：

• 分词处理：将搜索词拆分为独立词汇，支持多语言分词规则（中文按词、英文按空格/标点）。
• 词干提取：自动将词汇转换为词根形式（如"running"→"run"、"cats"→"cat"），实现同词根词汇的匹配。
• 同义词扩展：匹配预设的同义词库（如"FAQ"与"常见问题"），扩大匹配范围。
• 相关性排序：根据词汇出现频率、位置（标题权重高于正文）、页面更新时间等因素排序结果，优先展示最相关内容。
• 模糊匹配：默认支持轻微拼写错误的近似匹配，提升搜索容错性。

内容的提问来源于stack exchange，提问作者Kristada673