III 引擎 configuration Worker 完全指南：Schema 校验的响应式配置注册表与热更新实战

III 引擎 configuration Worker 完全指南Schema 校验的响应式配置注册表与热更新实战【免费下载链接】iiiEffortlessly compose, extend, and observe every service in real-time for the first time ever.项目地址: https://gitcode.com/GitHub_Trending/mo/iiiconfiguration是 III 引擎内置的、服务端持有的命名配置注册表每个条目拥有 id、名称、描述、JSON Schema 与经 Schema 校验的 JSON 值Worker 在启动时通过configuration::register声明 Schema通过configuration::set发布值消费方通过configuration::get/configuration::list读取并可用configuration触发器订阅变更而无需轮询。本文以 SKILL.md 为骨架结合引擎源码与测试讲解其适配器、函数面、触发器、TTL 清理机制并给出把 Worker 从config.yaml迁移到该注册表的完整实操。configuration Worker 是什么在 III 引擎中configuration是一个由引擎持有engine-owned的 worker提供类型化、可观测、可响应的配置面。一个条目entry由以下部分组成id稳定标识符例如iii-stream、billing-service必须匹配[a-z0-9_-]{1,64}name / description人类可读的名称与描述schema描述值形状的 JSON Schemavalue经过 Schema 校验的 JSON 值可以包含${VAR:default}模板占位符。Worker 生命周期内的典型交互是启动时调用一次configuration::register声明 Schema随后用configuration::set发布值消费方调用configuration::get/configuration::list读取并绑定configuration触发器在每次变更时被异步唤起——整个读写过程无需任何轮询。从源码结构看该 worker 的职责分层非常清晰mod.rsconfiguration.rsworker 主体实现五个 engine 函数与触发器扇出store.rs内存缓存 Schema 校验层负责${VAR:default}展开与类型强制trigger.rsconfiguration触发器注册/注销与 TTL 倒计时adapters/fs.rs默认文件系统适配器每个 id 一个 YAML 文件并监听目录变更adapters/bridge.rs桥接适配器把调用委托给远端 III 引擎。何时使用与边界适用场景根据 SKILL.md以下场景应当优先考虑该 worker一个 Worker 需要类型化、可被其他 Worker 读取并校验的配置面两个 Worker 需要在不轮询、不硬编码磁盘路径的前提下就同一份配置达成一致运维人员应当能直接编辑单个 YAML 文件或远端控制面变更无需重启 Worker 即可传播到所有订阅方Worker 来来去去沙箱、临时消费者当没有订阅者时应自动清理其配置。明确的边界不是通用的 key/value 存储每个条目都必须注册 JSON Schema需要自由格式值请使用独立的stateworker没有部分更新接口set总是整体替换值新值必须在客户端构建完整后再一次性提交bridge 适配器无法在远端引擎删除条目跨桥清理只能依赖 TTL 或在源引擎直接操作Schema 不做跨重注册的版本检查用不兼容的 Schema 重新注册会直接替换旧 SchemaSchema 迁移需要带外协调。引擎级配置与两种适配器configuration是引擎自有 worker应在受管的worker-compose.yaml中通过engine.workers.configuration配置不要把它作为项目容器添加。默认配置可参考 iii.worker.yaml 中的引擎声明engine: workers: configuration: adapter: name: fs config: directory: ./config ttl_seconds: 0顶层配置项解析逻辑见 config.rs字段类型说明adapterAdapter配置持久化适配器默认fsbridge委托给远端引擎ttl_secondsinteger每 id 清理倒计时秒。0时某条目最后一个订阅触发器注销满该时长后即被删除默认0不清理源码中ConfigurationModuleConfig使用#[serde(deny_unknown_fields)]未知配置字段会直接导致解析失败config.rs 及其测试rejects_unknown_fields可验证。fs 适配器每 id 一个 YAML 文件fs 适配器把每个配置条目存为directory/id.yaml并监听目录中的外部编辑name: fs config: directory: ./config字段类型说明directorystring存放id.yaml的目录启动时自动创建默认./config有几点值得强调的实现细节见 adapters/fs.rsSchema 不落盘磁盘文件只保存id/name/description/value/metadataJSON Schema 由 Worker 每次启动重新注册后在内存中重建write_entry显式移除schema键。因此磁盘加载的条目初始 schema 为 null直到所属 Worker 重注册对应SCHEMA_UNAVAILABLE错误软迁移默认位置此前是./data/configuration。当使用默认./config时启动会做一次性软迁移把旧目录中仍存在的id.yaml移过去INFO 日志若目标已存在同名文件则跳过并告警遗留副本保留供人工协调。显式指定directory:会禁用迁移外部编辑热更新对目录的写/改/删事件做 500ms 防抖后重放为configuration:registered/configuration:updated/configuration:deleted事件走与 SDK 调用相同的触发器扇出。手工编辑若在${VAR}展开后无法通过 Schema 校验会被 WARNING 拒绝保留上一个有效值handle_exchange校验逻辑与测试external_change_rejects_invalid_edit_and_keeps_previous可印证不会自我回环内部set写盘的同时更新适配器缓存watcher 的 diff 看到磁盘 缓存就不再发事件避免保存→重载→再保存死循环测试internal_set_does_not_echo_through_watcher验证绝对路径监听watcher 使用canonicalize后的绝对路径避免 macOS FSEvents 对./config这类相对路径静默丢事件。bridge 适配器委托远端引擎bridge 适配器把每个configuration::*调用经 iii-sdk 转发到远端 III 引擎并在远端注册一个configuration触发器把远端变更镜像进本地扇出name: bridge config: bridge_url: ${REMOTE_III_URL:ws://localhost:49134}字段类型说明bridge_urlstring远端 III 引擎的 WebSocket 地址默认ws://localhost:49134实现上adapters/bridge.rs桥接 worker 以iii-configuration-bridge身份注册到远端注册configuration::__bridge_relay中继函数接收远端事件所有远端调用带 30 秒超时避免远端无响应时挂死本地。如前所述bridge不能在远端删除条目硬删除需直接在源引擎操作或依赖远端 TTL。五个 engine 函数详解五个函数由 configuration.rs 中的#[service(name configuration)]注册。register与set是仅有的两个变更入口读侧函数走缓存、开销低。configuration::register声明一个配置 id携带名称、描述、JSON Schema 与可选的initial_value幂等重复注册会替换 schema、名称、描述与 metadata除非提供了initial_value否则已存值保留initial_value在持久化前会针对 schema 校验首次注册触发configuration:registered后续注册触发configuration:updated。参数idstring、namestring、descriptionstring、schemaobjectJSON Schema、initial_valueany可选、metadataany可选。返回存储的条目{ id, name, description, schema, value, metadata }value中的模板按原样存储展开发生在读取时。一个值得注意的源码细节重注册时若无新值不会对现有值重新校验即使新 schema 更严格这是为了保证schema 收紧时依然能刷新 schema否则控制台会一直渲染过期 schema见 store.rs 与测试register_refreshes_schema_over_now_invalid_existing_value。configuration::set整体替换已注册 id 的值针对注册 schema 校验后触发configuration:updated。参数idstring、valueany。返回old_valueany无旧值时为null、new_valueany。configuration::get按 id 读取配置。参数idstring、rawboolean默认false。raw: false默认字符串字段中的${VAR:default}占位符针对实时进程环境展开raw: true返回存储值的原样模板形式。get会对展开 类型强制后的应用值做校验而不是原始模板。校验失败或引用了无默认值的未设置变量时返回SCHEMA_INVALID/EXPAND_FAILED失败而不是交出坏值——消费方只特判NOT_FOUND其他错误一律视为未加载从而保留上一次/默认配置测试get_fails_schema_invalid_when_applied_value_violates_schema、get_fails_expand_failed_when_required_var_missing验证。configuration::list 与 configuration::schemalist枚举所有已注册条目返回configurations{ id, name, description, schema, metadata }数组按 id 字典序排序绝不返回存储值schema读取单个 id 的 schema/名称/描述/metadata不暴露值。两者都返回ConfigurationSchemaViewstructs.rs即只含 schema、不泄值的视图。错误码错误码含义NOT_REGISTERED对尚未register的 id 调用setINVALID_IDid 不匹配[a-z0-9_-]{1,64}保证可作为 fs 适配器文件名SCHEMA_INVALID值不满足已注册 JSON Schema错误消息逐条列出违规项SCHEMA_UNAVAILABLE对 schema 尚不可知的 id 调用set——所属 Worker 本会话尚未注册fs 适配器不持久化 schema重启后需等 Worker 重注册NOT_FOUND对未注册 id 调用get/schemaADAPTER_ERROR适配器持久化失败磁盘错误、bridge 不可达等EXPAND_FAILEDget时发现引用了无默认值的未设置环境变量该码源自get_fn实现见 configuration.rs响应式触发器configuration当函数需要在每次 register / set / delete包括外部 fs 文件编辑与 bridge 转发来的远端事件时自动运行就绑定一个configuration触发器。引擎在每次成功变更及 TTL 清理后异步唤起匹配的 handlerWorker 无需轮询即可与配置保持同步。适用场景Worker 需要在配置被另一组件或运维直接编辑 YAML 重写时重载内存状态同一个 handler 应不区分变更来源本地 SDK 调用、bridge 转发的远端引擎、文件编辑统一执行。如果你只需要在写入方同一函数内拿到新值configuration::set已经返回old_value/new_value——只有当另一个 Worker需要响应时才注册触发器。绑定方式iii.registerFunction(stream::on-config-change, handler) iii.registerTrigger({ type: configuration, function_id: stream::on-config-change, config: { configuration_id: iii-stream, // 可选。省略则接收所有 id。 event_types: [configuration:updated], // 可选。configuration:registered|configuration:updated|configuration:deleted 的子集。 // condition_function_id 同样受支持——见 get function info。 }, })触发器配置字段解析见 trigger.rs字段类型说明configuration_idstring只对指定 id 的变更触发省略则对所有 id 触发event_typesstring[]configuration:registered/configuration:updated/configuration:deleted子集省略则全部触发condition_function_idstring条件函数 id返回false时跳过 handler会触发触发器的事件configuration::register首次为:registered重注册为:updated、configuration::set:updated、TTL 清理:deleted、外部 fs 创建/编辑/删除事件。读取操作不会触发触发器。事件 payload 字段type恒为configuration、event_type、id、name、description、schema、old_value占位符已展开registered时为null、new_value占位符已展开deleted时为null、metadata注册时提供才有。事件通过fan_out异步派发configuration.rs并先按event_types过滤、再经condition_function_id条件判断。完整 payload 形状可用iii get function info查询触发器类型或 handler 函数 id。TTL 清理为来去无常的临时 Worker 设计worker 为每个配置 id 维护当前绑定的触发器计数。当满足以下条件时启动倒计时ttl_seconds 0已配置某 id 的最后一个触发器被注销。倒计时结束即删除该条目并触发configuration:deleted倒计时结束前有新的触发器注册则中止清理只要 id 上仍有触发器绑定条目就永不过期。ttl_seconds 0默认完全禁用过期——条目一直保留直到通过适配器显式删除fs 适配器即移除底层文件。这正是沙箱、短生命周期消费者这类来了又走、没有显式 teardown的临时 Worker 的清理方案没人订阅时配置应自动消失而不是留下陈旧数据。实现细节trigger.rs每个 id 的TriggerSlot持有expiry: JoinHandle注册新触发器时abort()旧倒计时destroy()时abort_all_expiries()中止全部在途倒计时。相关测试ttl_countdown_fires_when_last_trigger_unregistered与ttl_countdown_aborts_on_re_register覆盖了完整路径。实战把 Worker 从 config.yaml 迁移到 configuration以下完整示例演示三步走声明 Schema → 读取实时值 → 订阅变更。其中configuration::register/configuration::get通过iii.trigger调用也可直接使用 SDK 的专用客户端方法import { registerWorker } from iii-sdk const iii registerWorker(ws://localhost:49134) // 1. 启动时声明一次 Schema。 await iii.trigger({ function_id: configuration::register, payload: { id: iii-stream, name: Stream worker, description: Connection settings for the stream worker., schema: { type: object, required: [port], properties: { port: { type: integer, minimum: 1, maximum: 65535 }, host: { type: string }, }, }, initial_value: { port: 3112, host: 127.0.0.1 }, }, }) // 2. 在任何需要的地方读取实时值占位符已展开。 const { value } await iii.trigger({ function_id: configuration::get, payload: { id: iii-stream }, }) // 3. 在其他地方订阅变更——set / 外部编辑 / bridge 事件都走同一触发器。 const onChange iii.registerFunction(stream::onConfigChange, async (event) { console.log(Stream config now:, event.new_value) return {} }) iii.registerTrigger({ type: configuration, function_id: onChange.id, config: { configuration_id: iii-stream }, })配合${VAR:default}模板运维可以直接编辑./config/iii-stream.yaml或远端控制面变更经 fs watcher500ms 防抖或 bridge 转发后自动触发stream::onConfigChange——整个流程无需重启 Worker符合单一 YAML 文件即控制面的运维模型。模板展开与类型强制一个容易踩的坑${VAR:default}展开发生在读取时get、触发器事件而非写入时因此环境变量变化无需重启即可传播。展开时若字符串整体是单个占位符如port: ${HTTP_PORT:3111}替换结果会按 YAML 1.2 标量重新解析并做类型强制8080→ 整数8080、true→ 布尔true而带前后缀的混合模板如redis://${HOST:6379}始终保持字符串。on/off/yes/no这类 YAML 关键字不会被误转成布尔见 store.rs 及测试expand_value_coerces_lone_placeholder_default_to_integer、expand_value_keeps_yaml_keyword_strings。校验永远针对展开 强制后的应用值所以port: ${HTTP_PORT:3111}会以整数 3111 通过minimum/maximum校验。源码阅读路线图如果你想深入理解该 worker 的完整实现推荐按以下顺序阅读SKILL.md 与 README.md功能总览与全部参数表configuration.rsworker 主体、五个函数、事件扇出、外部变更处理store.rs缓存、Schema 校验、${VAR:default}展开与标量强制trigger.rs触发器注册/注销、TTL 倒计时adapters/fs.rs 与 adapters/bridge.rs两种持久化适配器集成测试 engine/tests/configuration_e2e.rs 以及 configuration.rs / store.rs / trigger.rs 内的单元测试覆盖注册、校验、热更新、TTL 全链路。该 worker 也在引擎引导早期被复用expand_value被早期启动读取持久化iii-observability条目时复用见 mod.rs 注释说明这套模板展开 校验逻辑是整个引擎配置读取的基础设施。小结configurationworker 把类型化配置注册表、Schema 强制校验、磁盘/远端双适配器与响应式触发器整合为引擎级配置面register声明、set发布、get/list/schema读取、configuration触发器订阅变更、TTL 自动清理临时 Worker 的残留条目。运维可通过编辑单个 YAML 文件或远端控制面完成配置下发Worker 之间则通过同一注册表达成一致全程无轮询、无重启、无硬编码路径——这是 III 引擎中替代手写config.yaml解析的首选方案。【免费下载链接】iiiEffortlessly compose, extend, and observe every service in real-time for the first time ever.项目地址: https://gitcode.com/GitHub_Trending/mo/iii创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考