企业官网建设流程全解析

• 后端
• AI 应用
• NLP

导读：本文围绕 Xberg C# 绑定的XbergConverter.ListValidators()接口，讲解如何在 .NET 应用中查询当前已注册的全部 Validator（文档校验插件），并梳理其背后的 Rust 注册表实现、FFI 调用链与配套的插件生命周期管理方法，帮助读者快速掌握 Validator 插件体系的查询与自检能力。读完本文，你将能够：在 C# 中安全地枚举 Validator 注册表、判断插件注册状态、并结合ClearValidators()等接口完成插件管理闭环。

一、功能定位：为什么需要"列出 Validator"

Xberg 的插件体系支持注册自定义文档校验器（Validator），用于在提取管线中对ExtractedDocument结果执行后置校验（例如检查内容是否为空、MIME 类型是否符合预期等）。当系统中动态注册了多个 Validator 时，开发者需要一种只读、无副作用的方式来查询当前注册状态——这正是validators_list接口（即list_validators）的用途。

该接口由 fixtures/plugin_api/validators_list.json 定义为契约测试用例，其关键元数据如下：

从源码结构看，validators_list与validators_clear、validators_list同属validator_management管理组，是插件管理 API 中"查询"一侧的核心能力，与 fixtures/plugin_api/validators_clear.json 的"清空"形成互补。

二、C# 侧调用：XbergConverter.ListValidators()

关联文档 docs-site/src/snippets-generated/csharp/plugin_api/validators_list.md 给出了最简调用方式：

using System; using Xberg; var result = XbergConverter.ListValidators(); Console.WriteLine(result);

该文档由 alef 工具自动生成（alef e2e generate），对应的 C# 实现位于 packages/csharp/src/Xberg/XbergConverter.cs：

/// <summary> /// List names of all registered validators. /// </summary> public static List<string> ListValidators() { var nativeResult = NativeMethods.ListValidators(); if (NativeMethods.LastErrorCode() != 0) { throw GetLastError(); } var json = global::System.Runtime.InteropServices.Marshal.PtrToStringUTF8(nativeResult); NativeMethods.FreeString(nativeResult); var returnValue = JsonSerializer.Deserialize<List<string>>(json ?? "null", JsonOptions)!; return returnValue; }

实现要点如下：

1. FFI 调用：通过NativeMethods.ListValidators()进入原生层，返回一个 UTF-8 JSON 字符串指针；
2. 错误检查：调用后立即检查NativeMethods.LastErrorCode() != 0，非零则抛出GetLastError()包装的异常，保证原生层错误能被安全地映射为 C# 异常；
3. 内存管理：使用Marshal.PtrToStringUTF8将指针转为托管字符串后，立即调用NativeMethods.FreeString释放原生内存，避免泄漏；
4. 反序列化：将 JSON 反序列化为List<string>，即返回的是Validator 名称列表（而非对象），每个元素对应一个已注册插件的名称。

实际返回内容由原生注册表决定。在默认情况下（未注册任何自定义 Validator 时），列表可能为空；注册插件后，列表会包含对应插件名称（如测试中的mock-validator，见下文）。

三、底层实现：Rust 侧 list_validators 与注册表

Rust 侧对应实现位于 crates/xberg/src/plugins/validator/mod.rs：

/// List names of all registered validators. pub fn list_validators() -> crate::Result<Vec<String>> { use crate::plugins::registry::get_validator_registry; let registry = get_validator_registry(); let registry = registry.read(); Ok(registry.list()) }

关键点：

• 通过 crates/xberg/src/plugins/registry/mod.rs 中的get_validator_registry()获取全局注册表的Arc<RwLock<ValidatorRegistry>>；
• 以读锁（read()）方式访问，保证并发安全且不阻塞其他读取者——这与clear_validators()使用写锁形成对比；
• 直接调用registry.list()返回名称集合，是无副作用操作，对应契约中side_effects: safe的声明。

在插件生命周期中，Validator 注册表的同类操作还包括（见 crates/xberg/src/plugins/validator/mod.rs）：

这些函数通过#[cfg_attr(alef, alef(skip))]标注，在 alef 生成 FFI 与绑定代码时会被跳过（不重复导出）。

四、Validator 插件是什么：trait 与执行管线中的位置

要理解查询结果的业务含义，需先了解 Validator 的定义。Validatortrait 位于crates/xberg/src/plugins/validator/下，其核心签名可从前文模块文档与测试代码推断：实现者需同时满足Plugintrait（提供name()、version()、initialize()、shutdown()）与Validatortrait 的validate(&ExtractedDocument, &ExtractionConfig)异步方法。模块内测试（crates/xberg/src/plugins/validator/mod.rs）展示了典型实现：

struct MockValidator { should_fail: bool } impl Plugin for MockValidator { fn name(&self) -> &str { "mock-validator" } fn version(&self) -> String { "1.0.0".to_string() } // initialize / shutdown ... } #[async_trait] impl Validator for MockValidator { async fn validate(&self, _result: &ExtractedDocument, _config: &ExtractionConfig) -> Result<()> { if self.should_fail { Err(XbergError::validation("Validation failed".to_string())) } else { Ok(()) } } }

在提取管线中，Validator 注册表被 crates/xberg/src/core/pipeline/execution.rs 引用，于提取完成后对结果执行校验；因此ListValidators()的查询结果可以直接用于在运行时确认校验插件是否已就位，是插件调试与启动自检的重要依据。

五、C# 侧配套管理接口：ClearValidators 与完整生命周期

除了列出，C# 绑定还提供配套的管理入口。同名文件 packages/csharp/src/Xberg/XbergConverter.cs 附近定义了ClearValidators()，用于清空全部已注册 Validator：

public static void ClearValidators() { var nativeResult = NativeMethods.ClearValidators(); // ... 错误检查与资源释放逻辑 }

对应的 Rust 实现（crates/xberg/src/plugins/validator/mod.rs）在清空前调用registry.shutdown_all()，确保每个插件的shutdown()被触发，完成优雅关停——这体现了 Xberg 插件管理对资源释放的严谨设计。

完整的 Validator 生命周期因此为：

1. 注册（Rust 侧register_validator）→ 2.查询（ListValidators()，本文主题）→ 3.执行（管线内validate）→ 4.注销/清空（unregister_validator/ClearValidators()）。

六、E2E 测试验证：契约如何被机器校验

为了确保各语言绑定的行为一致，Xberg 通过 alef 生成了跨语言 E2E 测试。C# 侧测试位于 e2e/csharp/tests/ValidatorManagementTests.cs，其中Test_ValidatorsList直接验证了本文接口：

[Fact] public void Test_ValidatorsList() { // List all registered validators var result = XbergConverter.ListValidators(); Assert.NotNull(result); }

要点：

• 断言result非空（NotNull），确保调用不抛错、返回结构正确，对应契约中assertions: not_error；
• 同文件的Test_ValidatorsClear先调用ClearValidators()并断言无异常，说明"清空"与"查询"常组合使用，形成管理闭环；
• 该测试文件同样由 alef 自动生成，保证文档片段、FFI 声明与测试三者保持同步（文件头部的alef:hash用于校验新鲜度，可通过alef verify检查）。

七、实战建议与使用注意事项

1. 调用前无需初始化：ListValidators()是纯查询，可在应用启动后任意时刻调用，用于日志输出或插件自检；
2. 结合错误码判断环境：若ListValidators()抛出异常，通常意味着原生库加载失败或 FFI 通道异常（而非注册表为空），应检查NativeMethods.LastErrorCode()相关信息；
3. 区分"空列表"与"异常"：返回空列表是合法结果（表示无自定义校验器），不应误判为错误；
4. 配对使用生命周期方法：在测试或动态插件场景中，常先ClearValidators()再注册、最后ListValidators()验证注册数，与 e2e/csharp/tests/ValidatorManagementTests.cs 的用法一致；
5. 文档可再生成：本文引用的文档片段由 alef 管理，若仓库 API 演进，可通过alef e2e generate重新生成、alef verify校验新鲜度，保证示例与实现始终同步。

参考路径速查

• 关联文档：docs-site/src/snippets-generated/csharp/plugin_api/validators_list.md
• 契约用例：fixtures/plugin_api/validators_list.json
• C# 绑定实现：packages/csharp/src/Xberg/XbergConverter.cs
• Rust 核心实现：crates/xberg/src/plugins/validator/mod.rs
• 注册表访问入口：crates/xberg/src/plugins/registry/mod.rs
• 管线调用位置：crates/xberg/src/core/pipeline/execution.rs
• E2E 测试：e2e/csharp/tests/ValidatorManagementTests.cs

• 后端
• AI 应用
• NLP