Bitzsoft.Integrations.Search.Lucene 1.0.0-alpha.10

Bitzsoft.Integrations.Search.Lucene

Lucene.NET 全文检索引擎实现 — 拼音分词、NGram、索引生命周期、三段式检索编排。

功能特性

• 拼音分词器：PinyinConverter（中文→拼音转换、多音字笛卡尔积全拼、首字母缩写）+ PinyinNameDetector（贪婪最长音节匹配、姓在前/姓在后/复姓三种姓名结构识别），底层数据为 416 个标准音节 + 120 个高频姓氏
• 智能多语言分析器：SmartTextAnalyzer 检测中文/拼音/拉丁/英文人名/中英混合 6 种语言类型，分别走 HMM 分词、StandardAnalyzer、姓名变体生成等处理路径
• 弱词过滤体系：LegalSuffix（实体法定后缀剥离，如"有限公司"）、OrgWeak（弱组织词，如"集团"）、GeoWeak（弱地理词，如"上海"，含拼音变体），提升人名召回与降噪
• Analyzer 链：NGramAnalyzer（bigram 索引）、LowercaseKeywordAnalyzer（整词小写）、SearchPerFieldAnalyzer（按字段路由）、ExtensionFilter（扩展词强制保留为完整 token）
• 多字段文档布局：每个文本字段生成 4 个 Lucene 字段（raw StringField + _search TextField + _ngram TextField + _superlong 超长标记），关键词字段（身份证/统一社会信用代码）仅 StringField
• 索引生命周期：LuceneIndexWriter 延迟批量提交（阈值 1000 + 定时 2s + 提交锁串行化），AtomicIndexRebuilder 原子目录替换重建（Index → Temp → Bak），全程不中断检索服务
• 三阶段检索编排：构建租户感知分析器 → SafeQueryBuilder 多路径召回 → StreamingConflictCollector 流式全量召回 → SearchPipeline 按 BusinessId 聚合
• 安全查询构建：SafeQueryBuilder 对每字段同时构建 ngram PhraseQuery + TermQuery + WildcardQuery 三路径 OR 最大化召回，ConstantScoreQuery 包装降低 CPU 开销，clause 爆裂防护（阈值 600 / 上限 1000）
• 目录穿越防护：LuceneIndexDirectoryProvider 对 tenantId / directoryName 做白名单校验（仅字母数字下划线连字符），并校验全路径必须位于 basePath 之下
• 多租户隔离：文档写入 TenantId 字段，查询期 MUST 子句按租户过滤

安装

上游兼容性说明：本包使用 Lucene.NET 4.8.0-beta00016。Apache 仍将现代 4.8 版本线标记为 Beta；这里保留 beta00016，是因为更新的 4.8 beta 已把部分传递依赖 提升到不正式支持 .NET 5 的版本。旧稳定版 3.0.3 也不适合作为本实现基础。采用本包前 应把 Lucene 版本、索引格式与回滚方案纳入部署验收，升级后通过重建索引迁移，不要 直接假定旧索引兼容。

.NET CLI

dotnet add package Bitzsoft.Integrations.Search.Lucene

PackageReference

<PackageReference Include="Bitzsoft.Integrations.Search.Lucene" Version="1.0.0" />

配置

appsettings.json

{
  "LuceneSearch": {
    "BasePath": "/data/lucene"
  }
}

注册服务

using Bitzsoft.Integrations.Search.Lucene.Indexing;

// 委托配置
builder.Services.AddBitzsoftLuceneSearch(opt =>
{
    opt.BasePath = "/data/lucene";
});

从 IConfiguration 节点绑定参数后传入委托：

var section = builder.Configuration.GetSection("LuceneSearch");

builder.Services.AddBitzsoftLuceneSearch(opt =>
{
    opt.BasePath = section["BasePath"];
});

引擎注册后，可选注册宿主实现的弱词/停用词/扩展词存储，引擎将自动启用对应的弱词过滤与查询扩展；未注册时使用空集合：

builder.Services.AddScoped<Bitzsoft.Integrations.Search.ISegmentWordStore, MySegmentWordStore>();
builder.Services.AddScoped<Bitzsoft.Integrations.Search.IStopWordProvider, MyStopWordProvider>();
builder.Services.AddScoped<Bitzsoft.Integrations.Search.IExtensionWordProvider, MyExtensionWordProvider>();

注册的服务生命周期：LuceneIndexWriter / LuceneSearchExecutor / AtomicIndexRebuilder / SafeQueryBuilder 为单例（进程级资源），ISearchEngine 为 Scoped（按请求构建含租户弱词的分析器）。

使用示例

写入与删除文档（实时增量）

using Bitzsoft.Integrations.Search;

public sealed class ConflictIndexService(ISearchEngine engine)
{
    public Task UpsertAsync(string caseId, string tenantId, string name, string foreignName,
        CancellationToken ct)
        => engine.UpsertAsync(
            indexKey: "conflict",
            tenantId: tenantId,
            documentId: caseId,
            fields: new Dictionary<string, string?>
            {
                ["Name"] = name,
                ["ForeignName"] = foreignName,
                ["EntityType"] = "CaseMatter"
            },
            cancellationToken: ct);

    public Task DeleteAsync(string caseId, string tenantId, CancellationToken ct)
        => engine.DeleteAsync("conflict", tenantId, caseId, ct);
}

有效的 indexKey 值："conflict"（利冲索引）、"keyword-search"（关键字检索索引）。

全量重建索引（原子替换，不中断服务）

public sealed class RebuildService(ISearchEngine engine, ISearchIndexDataSource dataSource)
{
    public async Task<RebuildResult> RebuildAsync(string tenantId, CancellationToken ct)
    {
        // keyset 分页写入 → 提交 → 原子目录替换（IndexNew → Index，旧索引移至 IndexBak）
        var result = await engine.RebuildAsync("conflict", tenantId, dataSource, ct);
        Console.WriteLine($"已处理 {result.ProcessedCount}/{result.TotalCount}，完成={result.Completed}");
        return result;
    }
}

三段式检索（利冲审查）

public sealed class ConflictSearchService(ISearchEngine engine)
{
    public async Task<IReadOnlyList<SearchHitItem>> SearchAsync(
        string tenantId, string keyword, CancellationToken ct)
    {
        var input = new SearchPerformInput
        {
            IndexKey = "conflict",
            TenantId = tenantId,
            BusinessName = "ConflictCheck",
            Query = new SearchQueryContext
            {
                // 字段 → 关键字映射驱动多路径召回
                SearchFieldWordsDict = new()
                {
                    ["Name"] = new() { keyword },
                    ["FormerName"] = new() { keyword }
                },
                Mode = SearchMode.Fuzzy,                  // ngram 快速路径 + wildcard 回退
                MultiFieldCombineMode = FieldCombineMode.Should  // 多字段 OR
            },
            Filter = new SearchFilterContext
            {
                ExcludeSourceBusinessId = true,            // 排除检索来源自身
                ExcludePartyCategories = { "ThirdParty" }  // 排除第三方
            },
            Rule = new SearchRuleContext
            {
                Scenario = SearchScenario.ProcessRoleOpposing,
                Categories = new PartyCategories
                {
                    OurPartyCategories = { "Client" },
                    OppositePartyCategories = { "Opponent" },
                    ThirdPartyCategories = { "ThirdParty" }
                }
            }
        };

        var output = await engine.SearchAsync(input, ct);
        // 结果已按 HitLevel 降序：3=红(我方 vs 对方)、2=黄、1=绿、0=无
        return output.Hits;
    }
}

索引统计

var stats = await engine.GetStatisticsAsync("conflict", tenantId, ct);
Console.WriteLine($"当前文档总数: {stats.DocumentCount}");

核心类型一览

依赖

相关包

• Bitzsoft.Integrations.Search -- 全文检索引擎抽象层（统一接口定义、三段式检索上下文、业务规则矩阵、弱词过滤抽象）