Apache Lucy 0.6 全文检索实战详解

本文承接前两篇《Apache Lucy 0.6 介绍与核心概念》与《Ubuntu 22.04 编译安装 Apache Lucy 0.6.2 指南》，在 Ubuntu 22.04（内核 5.15、gcc 11.4.0）环境中，用两个完整可编译运行的 C 程序贯通 Lucy 0.6.2 的建索引与检索全链路。Lucy 已于 2019 年 11 月进入 Apache Attic，0.6.2 为其终版，适合学习检索引擎原理与维护存量遗产系统，不建议新项目采用。

一、实战准备与环境确认

1.1 前置产物清单

按安装指南完成三步构建后，服务器上应存在以下产物，本文全部示例依赖它们：

共享库 /usr/local/lib/liblucy.so.0.6.2 与 /usr/local/lib/libclownfish.so.0.6.2，且 ldconfig -p 可检索到；
编译器 /usr/local/bin/cfc；
Lucy 源码树 /opt/src/apache-lucy-0.6.2/，其 c/autogen/include/ 下已生成全套 C 头文件。

用以下命令逐一确认：

$ ldconfig -p | grep -i lucy
        liblucy.so.0.6 (libc6,x86-64) => /usr/local/lib/liblucy.so.0.6
        liblucy.so (libc6,x86-64) => /usr/local/lib/liblucy.so
$ ls /opt/src/apache-lucy-0.6.2/c/autogen/include/
Clownfish  Lucy  LucyX  cfish_hostdefs.h  cfish_parcel.h  cfish_platform.h

1.2 头文件布局与编译命令模板

Lucy 的 C 头文件有两处来源，布局不同，这是实战第一个要注意的点：

构建树布局：/opt/src/apache-lucy-0.6.2/c/autogen/include/，Clownfish/String.h、Lucy/Simple.h 直接位于顶层，本文统一使用该路径；
独立生成布局：手工执行 cfc --include=<share 目录> --parcel=Lucy --dest=autogen 生成的目录中，头文件位于 include/Clownfish/v0.6.2/Clownfish/ 这类带版本号的子目录里，与 #include "Clownfish/String.h" 的书写形式不匹配，直接编译会报 fatal error: Clownfish/String.h: No such file or directory。

本文所有示例统一使用如下编译命令模板：

$ gcc -O2 源文件.c \
    -I /opt/src/apache-lucy-0.6.2/c/autogen/include \
    -L/usr/local/lib -lclownfish -llucy \
    -Wl,-rpath,/usr/local/lib \
    -o 可执行文件

三个链接要素缺一不可：-I 指向构建树 autogen 头文件；-lclownfish -llucy 同时链接 Clownfish 运行库与 Lucy 本体（Clownfish 在前）；-Wl,-rpath,/usr/local/lib 把运行时库搜索路径写进可执行文件，避免每次设置 LD_LIBRARY_PATH。

1.3 C 程序骨架与对象生命周期

Lucy 的 C API 建立在 Clownfish 对象体系之上，每个程序固定遵循四段式骨架：

#define CFISH_USE_SHORT_NAMES
#define LUCY_USE_SHORT_NAMES
#include "Clownfish/String.h"
#include "Lucy/Simple.h"          /* 按需增加其他头文件 */

int main(void) {
    lucy_bootstrap_parcel();      /* 1. 初始化运行时 */
    /* 2. 创建对象、执行建索引与检索 */
    /* 3. 对每个持有对象 DECREF 释放 */
    return 0;
}

lucy_bootstrap_parcel() 必须最先调用，它完成 Clownfish 类层次的注册。此后每个返回 incremented（引用计数已加一）对象的构造函数所得对象，用完都要 DECREF；字符串从 C 串转入用 Str_new_from_utf8(text, strlen(text))，输出转回用 Str_To_Utf8()，后者返回 malloc 出来的 char*，需要 free()。引用计数纪律贯穿全文，任何一处漏放都会在长期运行的服务进程中积累成泄漏。

二、Simple 快速路线：最小闭环程序

2.1 simple_demo.c 完整源码

Lucy::Simple 是 Lucy 提供的门面类，把 Schema、Indexer、IndexSearcher 三件事封装成一个对象。以下程序写入 8 篇文档并执行 3 组查询，保存为 /opt/lucy-demo/mine/simple_demo.c：

/* 自写示例：使用 Lucy::Simple 完成「建索引 + 搜索」最小闭环。 */
#include <stdio.h>
#include <stdlib.h>
#include <string.h>

#define CFISH_USE_SHORT_NAMES
#define LUCY_USE_SHORT_NAMES
#include "Clownfish/String.h"
#include "Lucy/Document/Doc.h"
#include "Lucy/Document/HitDoc.h"
#include "Lucy/Simple.h"

static const char *docs[] = {
    "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
    "Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris.",
    "Duis aute irure dolor in reprehenderit in voluptate velit esse.",
    "Excepteur sint occaecat cupidatat non proident, sunt in culpa.",
    "Sed ut perspiciatis unde omnis iste natus error sit voluptatem laborum.",
    "Nemo enim ipsam voluptatem quia voluptas sit aspernatur aut odit.",
    "Neque porro quisquam est qui dolorem ipsum quia dolor sit amet.",
    "Quis autem vel eum iure reprehenderit qui in ea voluptate velit."
};

int main(void) {
    lucy_bootstrap_parcel();

    String *folder   = Str_newf("%s", "simple_index");
    String *language = Str_newf("%s", "en");
    Simple *lucy     = Simple_new((Obj*)folder, language);

    for (size_t i = 0; i < sizeof(docs) / sizeof(docs[0]); i++) {
        Doc *doc = Doc_new(NULL, 0);
        String *field = Str_newf("content");
        String *value = Str_new_from_utf8(docs[i], strlen(docs[i]));
        Doc_Store(doc, field, (Obj*)value);
        Simple_Add_Doc(lucy, doc);
        DECREF(field);
        DECREF(value);
        DECREF(doc);
    }
    Simple_Finish_Indexing(lucy);
    printf("Indexed %d documents.\n", (int)(sizeof(docs) / sizeof(docs[0])));

    const char *queries[] = { "ullamco", "ut OR laborum", "sit AND amet" };
    for (size_t q = 0; q < sizeof(queries) / sizeof(queries[0]); q++) {
        printf("\nSearching for: %s\n", queries[q]);
        String *query_str = Str_new_from_utf8(queries[q], strlen(queries[q]));
        Simple_Search(lucy, query_str, 0, 10, NULL);
        HitDoc *hit;
        int rank = 1;
        while (NULL != (hit = Simple_Next(lucy))) {
            String *content = (String*)HitDoc_Extract(hit, Str_newf("content"));
            char *content_c = Str_To_Utf8(content);
            printf("Result %d: %.55s\n", rank++, content_c);
            free(content_c);
            DECREF(content);
            DECREF(hit);
        }
        DECREF(query_str);
    }

    DECREF(lucy);
    DECREF(language);
    DECREF(folder);
    return 0;
}

Simple 类对外的写入方法只有三个：Simple_Add_Doc（追加一个 Doc）、Simple_Finish_Indexing（提交收尾）、读取侧的 Simple_Search 与 Simple_Next。注意它没有逐字符串追加文档的 Add_String 之类方法——文档必须先构造成 Doc 对象再入库。

2.2 编译与运行回显

Simple 不负责创建索引目录，先手工建目录再运行：

$ cd /opt/lucy-demo/mine
$ mkdir -p simple_index
$ gcc -O2 simple_demo.c \
    -I /opt/src/apache-lucy-0.6.2/c/autogen/include \
    -L/usr/local/lib -lclownfish -llucy -Wl,-rpath,/usr/local/lib \
    -o simple_demo
$ ./simple_demo
Indexed 8 documents.

Searching for: ullamco
Result 1: Ut enim ad minim veniam, quis nostrud exercitation ulla

Searching for: ut OR laborum
Result 1: Sed ut perspiciatis unde omnis iste natus error sit vol
Result 2: Ut enim ad minim veniam, quis nostrud exercitation ulla

Searching for: sit AND amet
Result 1: Lorem ipsum dolor sit amet, consectetur adipiscing elit
Result 2: Neque porro quisquam est qui dolorem ipsum quia dolor s

三组查询的命中都符合预期：单词 ullamco 只在第 2 篇出现；ut OR laborum 命中含 laborum 的第 5 篇与含 ut 的第 2 篇；sit AND amet 要求两词同时出现，命中的第 1、7 篇均含 sit amet 相邻序列。查询串默认按 OR 布尔关系解析，AND 需要显式书写。

2.3 Simple 路线的三个实测坑

坑一：索引目录必须预先存在。 若不执行 mkdir -p simple_index 直接运行，程序立刻报错退出：

Failed to opendir '/opt/lucy-demo/mine/simple_index': No such file or directory
        lucy_FSFolder_Local_Open_Dir_IMP at ../core/Lucy/Store/FSFolder.c line 138
        lucy_Folder_Open_Dir_IMP at ../core/Lucy/Store/Folder.c line 277
        lucy_IxFileNames_latest_snapshot at ../core/Lucy/Util/IndexFileNames.c line 30

Simple 打开索引时要先扫描既有快照，目录不存在即失败。用 Schema 路线时 Indexer_CREATE 标志会自动建目录，两条路线行为不同。

坑二：Doc 构造的 fields 参数不能传 Vector。 初次实现时曾用 Vec_new/Vec_Push 构造字段名列表传给 Doc_new，编译通过但运行时报错：

Can't downcast from Clownfish::Vector to Clownfish::Hash
        lucy_Doc_init at ../core/Lucy/Document/Doc.c line 37

Doc_new 的 fields 参数在运行期按 Hash（字段名到字段值的映射）处理，传 Vector 直接类型转换失败。正确做法是传 NULL，再用 Doc_Store(doc, field, value) 逐字段填充，这也是官方示例 getting_started.c 的写法。

坑三：文档必须经 Doc 对象入库。 Simple 没有 Add_String 这类便捷方法，任何写入都要先 Doc_new、Doc_Store、Simple_Add_Doc 三步，最后 Simple_Finish_Indexing 才会把内存中的文档真正落盘成段。

三、Schema 精细路线：字段类型与 Indexer

3.1 StringType 与 FullTextType 的语义差异

精细路线的第一个决策是每个字段的类型，两者行为差异必须实测确认：

StringType：字段值整体存储、整体匹配，适合标题、URL、分类标签这类需要精确等值匹配的字段；
FullTextType：字段值经分析器切分为词条后建倒排，适合正文；Set_Highlightable(true) 额外保存原文偏移信息，供后续高亮使用。

分析器选用 EasyAnalyzer，它是 Lucy 内置的复合分析器，按语言组装分词、归一化、停用词与 Snowball 词干化四层处理，本文用 "en"。

3.2 full_demo.c 完整源码

程序对 title 用 StringType、content 用可高亮的 FullTextType，依次演示 TermQuery、QueryParser 四种语法与 Highlighter 摘要，保存为 /opt/lucy-demo/mine/full_demo.c。限于篇幅，8 篇文档的正文数组与 Simple 示例同构（标题数组 titles[] 8 项、正文数组 contents[] 8 项，均为 Lucy 主题英文短文），以下给出主体逻辑：

/* 自写示例：Schema 定义、Indexer 建索引、QueryParser 检索、Highlighter 摘要。 */
#include <stdio.h>
#include <stdlib.h>
#include <string.h>

#define CFISH_USE_SHORT_NAMES
#define LUCY_USE_SHORT_NAMES
#include "Clownfish/String.h"
#include "Clownfish/Vector.h"
#include "Lucy/Analysis/EasyAnalyzer.h"
#include "Lucy/Document/Doc.h"
#include "Lucy/Document/HitDoc.h"
#include "Lucy/Highlight/Highlighter.h"
#include "Lucy/Index/Indexer.h"
#include "Lucy/Plan/FullTextType.h"
#include "Lucy/Plan/Schema.h"
#include "Lucy/Plan/StringType.h"
#include "Lucy/Search/Hits.h"
#include "Lucy/Search/IndexSearcher.h"
#include "Lucy/Search/QueryParser.h"
#include "Lucy/Search/TermQuery.h"

static void
S_add_document(Indexer *indexer, const char *title, const char *content) {
    Doc *doc = Doc_new(NULL, 0);
    String *title_field   = Str_newf("title");
    String *title_value   = Str_new_from_utf8(title, strlen(title));
    String *content_field = Str_newf("content");
    String *content_value = Str_new_from_utf8(content, strlen(content));
    Doc_Store(doc, title_field, (Obj*)title_value);
    Doc_Store(doc, content_field, (Obj*)content_value);
    Indexer_Add_Doc(indexer, doc, 1.0);
    DECREF(title_field);
    DECREF(title_value);
    DECREF(content_field);
    DECREF(content_value);
    DECREF(doc);
}

static void
S_show_hits(Hits *hits) {
    HitDoc *hit;
    int rank = 1;
    while (NULL != (hit = Hits_Next(hits))) {
        String *title_value = (String*)HitDoc_Extract(hit, Str_newf("title"));
        char *title_c = Str_To_Utf8(title_value);
        printf("  Result %d (score %.4f): %s\n", rank++,
               (double)HitDoc_Get_Score(hit), title_c);
        free(title_c);
        DECREF(title_value);
        DECREF(hit);
    }
}

int main(void) {
    lucy_bootstrap_parcel();

    /* 1. Schema: title 用 StringType 精确匹配，content 用 FullTextType 分词 */
    Schema *schema = Schema_new();
    String *language = Str_newf("en");
    EasyAnalyzer *analyzer = EasyAnalyzer_new(language);
    FullTextType *ftt = FullTextType_new((Analyzer*)analyzer);
    FullTextType_Set_Highlightable(ftt, true);
    StringType *st = StringType_new();
    String *title_field   = Str_newf("title");
    String *content_field = Str_newf("content");
    Schema_Spec_Field(schema, title_field, (FieldType*)st);
    Schema_Spec_Field(schema, content_field, (FieldType*)ftt);

    /* 2. Indexer 写入 8 篇文档 */
    String *folder = Str_newf("%s", "full_index");
    Indexer *indexer = Indexer_new(schema, (Obj*)folder, NULL,
                                   Indexer_CREATE | Indexer_TRUNCATE);
    for (size_t i = 0; i < 8; i++) {
        S_add_document(indexer, titles[i], contents[i]);
    }
    Indexer_Commit(indexer);
    printf("Indexed %d documents into full_index\n", (int)(sizeof(titles) / sizeof(titles[0])));
    DECREF(indexer);

    /* 3. IndexSearcher 执行检索 */
    IndexSearcher *searcher = IxSearcher_new((Obj*)folder);

    printf("\n[1] TermQuery(title, \"Schema and field types\")\n");
    Query *tq = (Query*)TermQuery_new(title_field,
                     Str_new_from_utf8("Schema and field types",
                                       strlen("Schema and field types")));
    Hits *hits = IxSearcher_Hits(searcher, (Obj*)tq, 0, 10, NULL);
    S_show_hits(hits);
    DECREF(hits);
    DECREF(tq);

    printf("\n[2] TermQuery(content, \"search\")\n");
    tq = (Query*)TermQuery_new(content_field, (Obj*)Str_newf("search"));
    hits = IxSearcher_Hits(searcher, (Obj*)tq, 0, 10, NULL);
    S_show_hits(hits);
    DECREF(hits);
    DECREF(tq);

    /* 4. QueryParser：默认布尔运算符 OR，检索 title 与 content 两个字段 */
    Vector *fields = Vec_new(2);
    Vec_Push(fields, (Obj*)Str_newf("title"));
    Vec_Push(fields, (Obj*)Str_newf("content"));
    QueryParser *qparser = QParser_new(schema, (Analyzer*)analyzer,
                                       Str_newf("OR"), fields);

    const char *queries[] = {
        "snowball OR highlighter",
        "search AND library",
        "\"search engine\"",
        "index AND NOT highlighter"
    };
    for (size_t q = 0; q < 4; q++) {
        printf("\n[%d] QueryParser: %s\n", (int)(q + 3), queries[q]);
        String *qs = Str_new_from_utf8(queries[q], strlen(queries[q]));
        Query *query = QParser_Parse(qparser, qs);
        Hits *qh = IxSearcher_Hits(searcher, (Obj*)query, 0, 10, NULL);
        S_show_hits(qh);
        DECREF(qh);
        DECREF(query);
        DECREF(qs);
    }

    /* 5. Highlighter 生成摘要 */
    printf("\n[7] Highlighter: query 'search', field 'content'\n");
    Query *hq = QParser_Parse(qparser, Str_newf("search"));
    Hits *hh = IxSearcher_Hits(searcher, (Obj*)hq, 0, 1, NULL);
    HitDoc *hit = Hits_Next(hh);
    if (hit != NULL) {
        Highlighter *hl = Highlighter_new((Searcher*)searcher, (Obj*)hq,
                                          content_field, 120);
        Highlighter_Set_Pre_Tag(hl, Str_newf("<em>"));
        Highlighter_Set_Post_Tag(hl, Str_newf("</em>"));
        String *excerpt = Highlighter_Create_Excerpt(hl, hit);
        char *excerpt_c = Str_To_Utf8(excerpt);
        printf("  Excerpt: %s\n", excerpt_c);
        free(excerpt_c);
        DECREF(excerpt);
        DECREF(hl);
        DECREF(hit);
    }
    DECREF(hh);
    DECREF(hq);

    /* ……省略段：对 qparser、fields、searcher、folder、字段名、
       类型对象、分析器、语言串、schema 逐一 DECREF 后 return 0; */
}

3.3 编译与完整运行回显

$ cd /opt/lucy-demo/mine
$ gcc -O2 full_demo.c \
    -I /opt/src/apache-lucy-0.6.2/c/autogen/include \
    -L/usr/local/lib -lclownfish -llucy -Wl,-rpath,/usr/local/lib \
    -o full_demo
$ ./full_demo
Indexed 8 documents into full_index

[1] TermQuery(title, "Schema and field types")
  Result 1 (score 2.3863): Schema and field types

[2] TermQuery(content, "search")
  Result 1 (score 0.6328): Getting started with Lucy

[3] QueryParser: snowball OR highlighter
  Result 1 (score 0.0565): Analyzers explained
  Result 2 (score 0.0565): Highlighting search results

[4] QueryParser: search AND library
  Result 1 (score 0.2339): Getting started with Lucy

[5] QueryParser: "search engine"
  Result 1 (score 0.2741): Getting started with Lucy

[6] QueryParser: index AND NOT highlighter
  Result 1 (score 0.1421): Building an index
  Result 2 (score 0.1172): Schema and field types

[7] Highlighter: query 'search', field 'content'
  Excerpt: Apache Lucy is a full-text <em>search</em> engine library written in C. It allows you to add powerful <em>search</em> capabilities to&#8230;

3.4 Indexer 的创建与提交语义

Indexer_new(schema, index, manager, flags) 的第四个参数用位标志控制打开行为：Indexer_CREATE 表示索引不存在时创建（Simple 路线缺失的能力），Indexer_TRUNCATE 表示清空既有内容重建。两者按位或即可实现「每次运行从零开始」的幂等建索引。写入侧每篇文档调用一次 Indexer_Add_Doc(indexer, doc, 1.0)，第三个参数是文档级加权系数，影响该文档所有字段词条的最终得分。所有文档入队后必须调用 Indexer_Commit(indexer) 才会生成新段并写快照，未提交即退出的数据不会残留。

四、检索实战：TermQuery 与 QueryParser 的真实语义

4.1 TermQuery 匹配的是「分析后」的词条

这是本次实战最重要的实测发现。TermQuery 构造时直接给定字段与词项，不会对词项执行任何分析，它匹配的是倒排表里已经过「分词 + 词干化」的最终 token。为验证这一点，用同一个索引对三个词做对照实验：

TermQuery(content, "snowball") -> 0 hits
TermQuery(content, "search")   -> 1 hits
TermQuery(content, "index")    -> 2 hits

语料第 4 篇正文明确含有单词 Snowball，但直接查询 snowball 零命中——因为分析链中的 Snowball 词干化把 Snowball 归约为 snowbal，倒排表里存的是 snowbal，而 TermQuery 拿原始词 snowball 去等值比较自然失败。search 的词干形式仍是 search、index 仍是 index，所以能命中（第 5 篇正文中的 IndexSearcher 是一个完整 token，不算 index，故 index 只命中第 2、3 篇）。而 QueryParser 之所以查 snowball 能命中第 4 篇，是因为它把查询串交给字段的分析器重走了同样的归约过程。

工程结论：程序里已知精确词条（如标签、ID、标题）用 TermQuery；自由文本一律走 QueryParser。非要绕过 QueryParser 又想命中原文任意词形时，必须自己先调用分析器把查询词归约成词条形式。

4.2 StringType 字段的精确匹配

第 1 组查询对 StringType 的 title 做整值匹配，命中第 3 篇（score 2.3863，明显偏高，因为单字段单文档整值命中的权重远高于正文单词条命中）。注意构造词项时的长度参数必须与内容完全一致——实测曾把 Str_new_from_utf8("Schema and field types", 23) 的长度多写 1（把结尾 \0 算进去），词条带上了隐藏字节，精确匹配直接零命中。教训是长度一律用 strlen() 计算，不要手写常量。

4.3 QueryParser 四种语法与默认字段

QParser_new(schema, analyzer, default_boolop, fields) 的四个参数分别指定 Schema、分析器、缺省布尔运算符（实测传 "OR"）与默认检索字段列表（实测传 title 与 content 两个字段的 Vector）。QParser_Parse 把查询串解析成 Query 对象后交给检索器执行。实测覆盖了四种语法：

查询串	语义	实测命中
`snowball OR highlighter`	双词任一命中	2 篇
`search AND library`	双词同时命中	1 篇
`"search engine"`	短语相邻匹配	1 篇
`index AND NOT highlighter`	排除式布尔	2 篇

除显式运算符外，QueryParser 还支持 + 必须包含、- 必须排除前缀与 field:term 字段限定写法（AND NOT 是 0.6 系列的排除语法）。短语查询用双引号包裹，解析成 PhraseQuery，按词条位置序列匹配。

4.4 评分观察

回显中的 score 按 BM25 风格权重计算：整值命中 2.3863 最高；"search engine" 短语 0.2741 高于 search AND library 的 0.2339，因为短语约束带来更强的相关性信号；snowball OR highlighter 两个 OR 分支各贡献 0.0565。得分由 HitDoc_Get_Score 读取，迭代 Hits 时逐条打印即可。命中条数由 IxSearcher_Hits(searcher, query, offset, num_wanted, sort_spec) 的第三、四个参数控制分页与截断，NULL 的 sort_spec 表示按得分降序。

五、高亮与结果加工

5.1 Highlighter 的装配与摘要生成

高亮三步：构造、配置标签、生成摘要。Highlighter_new(searcher, query, field, excerpt_length) 需要同一个检索器与查询对象，field 指明对哪个字段做摘要，excerpt_length 限定摘要长度（实测传 120）。Set_Pre_Tag/Set_Post_Tag 设置命中词条的前后包裹标签（实测用 /），Create_Excerpt(hit_doc) 对当前命中文档生成摘要。前提是该字段在 Schema 中设置过 FullTextType_Set_Highlightable(ftt, true)，否则生成阶段拿不到词条偏移。

5.2 摘要输出的两个细节

实测回显第 7 节的摘要中，两个 search 命中点被准确包裹成 search，而截断省略号输出为 XML 实体 … 而非 UTF-8 字符——Lucy 对摘要内容做了 XML 级转义，接入 Web 前端时需要统一做一次反转义。另外摘要对象在取值后同样要 DECREF，Str_To_Utf8 的返回值用完必须 free，这是高亮代码最容易漏掉的两处清理。

六、索引内部结构观察

6.1 目录布局

建索引结束后查看 full_index：

$ ls /opt/lucy-demo/mine/full_index/
locks
schema_1.json
seg_1
snapshot_1.json
$ ls /opt/lucy-demo/mine/full_index/seg_1/
cf.dat  cfmeta.json  segmeta.json

四类对象各司其职：snapshot_N.json 是索引版本指针，指向当前生效的 Schema 与段集合；schema_1.json 记录字段定义；seg_1 是第一个段，内部 cf.dat 存词条数据、segmeta.json 存段元信息；locks/ 存写锁文件。多次增删会滚动出 seg_2、seg_3 等新段，快照随之滚动编号。

6.2 快照与 Schema 文件内容

$ cat /opt/lucy-demo/mine/full_index/snapshot_1.json
{
  "entries": [
    "schema_1.json",
    "seg_1"
  ],
  "format": "2",
  "subformat": "1"
}
$ cat /opt/lucy-demo/mine/full_index/schema_1.json
{
  "_class": "Lucy::Plan::Schema",
  "analyzers": [
    null,
    {
      "_class": "Lucy::Analysis::EasyAnalyzer",
      "language": "en"
    }
  ],
  "fields": {
    "content": {
      "analyzer": "1",
      "highlightable": true,
      "type": "fulltext"
    },
    "title": {
      "type": "string"
    }
  }
}

Schema 文件把 content 记为 fulltext 类型并关联 1 号分析器（EasyAnalyzer en）与高亮开关，title 记为 string 类型。这份 JSON 与第 3.1 节的代码一一对应，排障时可直接对照检查字段定义是否按预期落盘。整个索引（8 篇文档、双字段）实测占用 36K 磁盘空间。

七、工程实践与维护建议

7.1 引用计数与错误处理纪律

实战中所有报错都由 Clownfish 异常机制抛出，表现为「错误消息 + C 调用栈」直接打印并终止进程（如第 2.3 节的两例）。健壮的服务进程应包裹关键调用并利用 Err_error 系列接口捕获，而非依赖进程终止。对象清理上，本文两个示例严格遵循「构造即持有、用毕即 DECREF」的配对原则：字符串、Doc、Hits、HitDoc、Query、Highlighter 逐一释放，HitDoc_Extract 返回的对象同样计数已增，必须释放。遗产系统改造时建议先用内存检测工具跑一遍增删改查全路径再上线。

7.2 并发写与锁

索引目录下的 locks/ 就是写锁的落点。多个进程同时对同一索引开 Indexer 时，后到者拿锁失败会直接报错退出，这是文件级互斥；读操作（IndexSearcher）可任意并发，读到的永远是自己打开时刻的快照，写入方提交后老快照依旧可用，天然实现了读写分离。若需要多进程交替写入，应在应用层排队，或改用 LucyX 提供的后台合并机制。

7.3 多语言与退役背景下的选型边界

EasyAnalyzer 只面向单一语言（英文语料实测表现良好），中文场景需要自行实现 Analyzer 接口接入外部分词器，0.6 系列未内置中文支持。结合退役背景给出明确建议：Lucy 0.6.2 的 C API 完整自洽，适合作为检索引擎教学载体与遗产系统维护工具；新项目应选择仍在活跃维护的检索组件。本文两个程序均可作为理解倒排索引、分析链与布尔检索模型的可运行教材。

八、FAQ

Q1：编译报 fatal error: Clownfish/String.h: No such file or directory 怎么解决？ -I 路径指错了布局。使用构建树头文件 /opt/src/apache-lucy-0.6.2/c/autogen/include（顶层布局）。若用独立 cfc 生成的目录，头文件会落在 include/Clownfish/v0.6.2/Clownfish/ 版本化子目录下，与源码 include 写法不匹配，实测无法直接编译。

Q2：链接期报 undefined reference 到 lucy_ 或 cfish_ 前缀符号？ 库没链全或顺序不对。必须 -lclownfish -llucy 两个都链且 Clownfish 在前，并确保 ldconfig -p | grep lucy 能找到 /usr/local/lib/liblucy.so；运行期找不到库时加 -Wl,-rpath,/usr/local/lib。

Q3：运行报 Can't downcast from Clownfish::Vector to Clownfish::Hash？ Doc_new 的 fields 参数运行期要求 Hash。不要传 Vector，改为传 NULL 后用 Doc_Store 逐字段填值，实测报错点在 Doc.c line 37。

Q4：Simple 路线启动报 Failed to opendir ... No such file or directory？ Simple 不会创建索引目录，运行前先 mkdir -p 索引目录；Schema 路线用 Indexer_CREATE 标志可自动创建。

Q5：TermQuery 查某个明确出现在正文里的词却零命中？ TermQuery 不执行分析，匹配的是分词与词干化后的词条。实测同一索引查 snowball 零命中（索引里存的是词干形式 snowbal），而 search、index 因词干与原形相同可以命中。自由文本查询请改用 QueryParser。

Q6：QueryParser 查询串怎么写短语与排除？ 双引号包裹短语，如实测的 "search engine" 精确命中 1 篇；排除用 AND NOT，如 index AND NOT highlighter 命中 2 篇。还支持 +/- 前缀与 field:term 字段限定。

Q7：高亮摘要里出现 … 这类实体？ Highlighter 对摘要做 XML 转义，省略号输出为实体形式， 标签则原样保留。接入前端前按需反转义即可，命中词包裹标签由 Set_Pre_Tag/Set_Post_Tag 自定义。

Q8：程序退出时段错误或内存持续增长？ 几乎都是引用计数失衡。构造函数返回的对象都要 DECREF，HitDoc_Extract 的返回值、Str_To_Utf8 的返回值（需 free）同样如此。本文示例给出了完整的释放配对模板，照抄即可。

Q9：能直接建中文索引吗？ 不能开箱即用。EasyAnalyzer 按单语言组装，0.6 系列无中文分词器，需实现自定义 Analyzer 接入外部切词组件；本文实测语料选用英文正是此原因。

Q10：索引文件能否手工编辑或跨版本读取？ 快照与 Schema 是纯 JSON 可读（见第 6.2 节实测内容），但段数据 cf.dat 为二进制格式，不应手工修改。跨大版本读取没有兼容承诺——项目已退役，0.6.2 即终版，重要系统应固化该版本并在同版本环境内维护索引。

九、实战小结

两条路线各有定位：Simple 路线十几行代码即可跑通建索引与检索，适合验证安装与教学演示，但目录创建、字段类型全部不可控；Schema 路线暴露完整对象模型，字段类型、分析器、布尔语法、高亮、文档加权逐项可调，是遗产系统二次开发的实际起点。全部命令与回显均在 Ubuntu 22.04 环境真实执行，其中 TermQuery 的词干化匹配语义、Doc 构造参数的 Hash 要求、索引目录预建要求这三处与直觉相悖的行为，建议读者在复现时重点关注。