在 Xberg Dart 绑定中查询验证器插件注册表：listValidators 用法与底层原理

后端AI 应用NLP【免费下载链接】xbergPolyglot document intelligence with a Rust core: extract text, metadata, images, tables, and structured data from 106 formats across 140 file extensions, plus code intelligence for 371 languages. Fifteen bindings, with CLI, REST API, and MCP server.项目地址https://gitcode.com/gh_mirrors/kr/xberg点击查看免费下载本篇技术指南以 Xberg 仓库自动生成的 Dart 测试片段 list_validators.md 为主线讲解如何通过 Dart 绑定调用XbergBridge.listValidators()列出当前已注册的验证器Validator插件并结合 Rust 核心源码剖析验证器注册表的内部结构、生命周期管理与优先级机制。读完本文你将掌握在 Dart/Flutter 项目中查询、注册、注销与清空验证器插件的完整套路并理解这些 API 在 Rust 侧的真实实现路径。一、验证器Validator插件是什么在 Xberg 的插件体系里验证器是一种「硬性检查」插件它针对一次文档提取得到的ExtractedDocument结果做质量、完整性或合规性校验一旦校验失败整次提取立即失败并向上层抛出错误。Rust 侧对Validatortrait 的定义位于 crates/xberg/src/plugins/validator/trait.rs其文档明确给出了典型使用场景质量闸门Quality Gates确保提取内容满足最低质量要求合规检查Compliance验证内容满足监管或业务要求内容过滤Content Filtering拒绝包含违禁内容的文档格式校验Format Validation验证提取结果的结构安全检查Security Checks扫描恶意内容。关键语义是验证器的错误是致命的会向上冒泡导致提取失败如果是非致命检查应当使用后处理器Post-Processor而非验证器。验证器必须满足线程安全Send Sync。二、核心用法用 Dart 列出所有已注册验证器原文档给出了一个可直接运行的完整 Dart 程序它初始化 Rust 运行时、调用listValidators、打印结果并释放资源import dart:io; import package:xberg/xberg.dart; import package:xberg/src/xberg_bridge_generated/frb_generated.dart show RustLib; Futurevoid main() async { await RustLib.init(); try { final result await XbergBridge.listValidators(); stdout.writeln(result); } finally { RustLib.dispose(); } }逐步拆解这段代码await RustLib.init()flutter_rust_bridgefrb生成的运行时初始化。RustLib来自frb_generated.dart所有通过XbergBridge发起的 Rust 调用都依赖它先行启动。await XbergBridge.listValidators()XbergBridge是 Dart 侧的静态门面类定义在 packages/dart/lib/src/xberg.dartalef 生成勿手改。该方法经 FFI 桥接到 Rust 侧list_validators返回当前注册表中全部验证器的名称列表。stdout.writeln(result)将名称列表打印到标准输出便于在测试或命令行场景直接观察。finally { RustLib.dispose(); }无论调用成功与否都在退出前释放 Rust 运行时资源避免泄漏。这是所有 Dart 绑定的标准收尾写法。需要说明的是该片段是 alef 为 e2e 测试自动生成的 fixture头部 frontmatter 标记了side_effect: safe纯读操作、无副作用与requires: []无需预置依赖因此可以直接在测试环境中安全执行。三、底层实现从 Dart 桥接到 Rust 全局注册表listValidators并不是一个孤立函数它的真实执行路径如下Dart 侧调用XbergBridge.listValidators()经 frb 生成的桥接层packages/dart/lib/src/xberg_bridge_generated/frb_generated.dart转发到 Rust。Rust 侧入口是 crates/xberg/src/plugins/validator/mod.rs 中的list_validators()pub fn list_validators() - crate::ResultVecString { use crate::plugins::registry::get_validator_registry; let registry get_validator_registry(); let registry registry.read(); Ok(registry.list()) }get_validator_registry()返回的正是全局单例VALIDATOR_REGISTRY定义在 crates/xberg/src/plugins/registry/mod.rspub static VALIDATOR_REGISTRY: LazyLockArcRwLockValidatorRegistry LazyLock::new(|| Arc::new(RwLock::new(ValidatorRegistry::new())));它用RwLock包装支持多线程并发读写读取时拿read()锁注册/注销时拿write()锁。最终落到ValidatorRegistry::list()实现在 crates/xberg/src/plugins/registry/validator.rspub fn list(self) - VecString { let mut names std::collections::HashSet::new(); for validators in self.validators.values() { names.extend(validators.keys().cloned()); } names.into_iter().collect() }这里值得注意的实现细节注册表内部用BTreeMapi32, IndexMapString, Arcdyn Validator组织外层以优先级i32为键、内层以插件名为键而list()收集名字时使用的是HashSet因此返回的名称列表不保证有序。如果你的 Dart 业务代码需要对名称排序展示应自行sort()不能依赖返回顺序。四、验证器注册表的完整管理 APIlistValidators只是注册表管理面的一角。同一模块还提供了配套的三个操作全部在 crates/xberg/src/plugins/validator/mod.rs 中定义并经 crates/xberg/src/plugins/mod.rs 的pub use统一导出函数作用锁register_validator(Arcdyn Validator)注册验证器调用其initialize()后按优先级插入写锁unregister_validator(name: str)按名称移除并调用其shutdown()释放资源写锁clear_validators()逐个注销并清空全部验证器写锁list_validators()返回所有已注册验证器的名称列表读锁注册时的两道防线见ValidatorRegistry::register名称校验validate_plugin_namecrates/xberg/src/plugins/registry/mod.rs要求名称非空、不含空白字符并建议遵循 kebab-case 惯例。空的或含空格的名字会直接返回Validation错误并被拒绝注册——对应测试test_validator_registry_invalid_name_empty/test_validator_registry_invalid_name_whitespace。初始化校验注册时会先调用validator.initialize()初始化失败则注册中止保证注册表里不存在半初始化的插件。注销时的资源回收remove使用IndexMap::shift_remove找到目标验证器并调用其shutdown()若shutdown失败会返回错误并记录告警日志但注册表仍会清理该条目。在 Dart 侧这四个能力都有对应桥接方法registerValidator/unregisterValidator/clearValidators/listValidators并且仓库的 e2e 测试给出了完整调用样例见 e2e/dart/test/plugin_api_test.dart注册→注销流程与 e2e/dart/test/validator_management_test.dart清空后列表为空、列出全部已注册验证器。五、编写自定义验证器的关键点要注册一个验证器需要实现Plugin与Validator两个 trait。Validatortrait 在 crates/xberg/src/plugins/validator/trait.rs 中定义了三个方法方法默认值说明validate(result, config) - Result()必须实现校验提取结果返回Err即整体提取失败should_validate(result, config) - booltrue始终执行条件化开关可按 MIME 类型等决定是否运行priority() - i3250优先级数值越大越先执行一个内容最短长度校验器的最小实现来自 trait 文档示例use xberg::plugins::{Plugin, Validator}; use xberg::{Result, ExtractedDocument, ExtractionConfig, XbergError}; use async_trait::async_trait; struct MinimumLengthValidator { min_length: usize, } impl Plugin for MinimumLengthValidator { fn name(self) - str { min-length-validator } fn version(self) - String { 1.0.0.to_string() } fn initialize(self) - Result() { Ok(()) } fn shutdown(self) - Result() { Ok(()) } } #[async_trait] impl Validator for MinimumLengthValidator { async fn validate(self, result: ExtractedDocument, config: ExtractionConfig) - Result() { if result.content.len() self.min_length { return Err(XbergError::validation(format!( Content too short: {} {} characters, result.content.len(), self.min_length ))); } Ok(()) } }关于优先级与条件执行的几个由源码测试确认的行为优先级排序注册表get_all()按优先级降序遍历BTreeMapiter().rev()测试test_validator_registry与test_validator_priority_ordering_reversed验证了无论注册先后高优先级验证器总是排在前、先执行。同优先级共存同一优先级下允许多个验证器共存test_validator_multiple_same_priority。条件跳过should_validate返回false时验证器被跳过。测试test_validator_should_validate_conditional中的PdfOnlyValidator只在 MIME 为application/pdf时执行校验。错误语义验证失败返回XbergError::Validation测试test_validator_failure与test_validator_error_message确认错误消息可精确断言。六、验证器相关的测试与 fixture仓库围绕验证器注册表提供了三层验证证据Rust 单元测试crates/xberg/src/plugins/registry/validator.rs 内含十余个测试覆盖注册/注销/清空、名称非法、初始化失败、优先级排序、同优先级共存、移除后再注册等场景crates/xberg/src/plugins/validator/mod.rs 的测试则覆盖成功/失败校验、空内容、带元数据、带表格、多种 MIME、超长内容等边界情况。Dart e2e 测试e2e/dart/test/registry_test.dart 中的List validators用例直接调用XbergBridge.listValidators()并断言结果e2e/dart/test/validator_management_test.dart 验证清空后列表为空、列出全部已注册验证器。契约 fixturefixtures/registry/list_validators.json 与 fixtures/plugin_api/validators_list.json 是跨语言契约测试的基准数据保证 Dart 之外的各语言绑定对列出验证器返回一致的结果fixtures/plugin_api/register_validator_trait_bridge.json 与 fixtures/plugin_api/unregister_validator_after_register.json 则锁定注册→注销的完整生命周期。七、运行前提与注意事项本文的 Dart 片段依赖package:xberg绑定需先按仓库说明构建 Dart 绑定包并在pubspec.yaml中引入RustLib.init()必须在任何XbergBridge调用之前完成。listValidators是只读操作fixture 标记side_effect: safe可以在测试中反复调用但注册、注销、清空会修改全局单例VALIDATOR_REGISTRY在多测试并发场景下需注意测试隔离。返回的名称列表基于HashSet收集顺序不保证依赖顺序的业务代码应自行排序。若列表为空说明当前进程内尚未注册任何验证器——这是合法的初始状态list()对空注册表返回空列表而非错误对应test_validator_shutdown_empty_registry。该 fixture 文档头部注明由 alef 自动生成alef e2e generate可重新生成alef verify可校验新鲜度如需修改契约内容应更新生成源而非手工编辑此文件。赞分享后端AI 应用NLP【免费下载链接】xbergPolyglot document intelligence with a Rust core: extract text, metadata, images, tables, and structured data from 106 formats across 140 file extensions, plus code intelligence for 371 languages. Fifteen bindings, with CLI, REST API, and MCP server.项目地址https://gitcode.com/gh_mirrors/kr/xberg点击查看免费下载相关推荐OpenProject开源项目管理从零到上线指南OpenProject开源项目管理从零到上线指南 OpenProject 是可自建部署的开源项目管理软件覆盖从立项、拆任务、甘特图排期到工时跟踪的完整流程。后端AI 应用NLP使用 C 绑定列出 Xberg 已注册验证器Validator 插件注册表实战指南使用 C 绑定列出 Xberg 已注册验证器Validator 插件注册表实战指南 导读 本文以 Xberg 开源仓库中的 C 绑定能力为核心讲解如何通过一后端AI 应用NLP终极游戏库革命5分钟学会用Playnite统一管理所有游戏平台终极游戏库革命5分钟学会用Playnite统一管理所有游戏平台 你是否曾经为了玩不同平台的游戏不得不在Steam、Epic、GOG、EA App、Battl后端AI 应用NLP上一篇微信数据安全警示从GoWxDump下架看个人信息保护的重要性下一篇Geolocator.js距离与ETA工具集秒算两点距离、旅行时长与时区信息的3种方法创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考