Lynx 引擎共享 API 头文件（core/public）详解：跨 Shell、Runtime 与平台的公共契约层

Lynx 引擎共享 API 头文件core/public详解跨 Shell、Runtime 与平台的公共契约层【免费下载链接】lynxEmpower the Web community and invite more to build across platforms.项目地址: https://gitcode.com/GitHub_Trending/lynx10/lynxcore/public是 Lynx 跨平台渲染引擎Lynx/TASM中位于核心引擎与外部世界之间的“契约层”它是一组 header-only 的 C 接口头文件定义了 shell、renderer、runtime、资源加载、列表处理、devtool 集成和 native module 绑定等各模块之间共享的稳定公共接口。本文基于仓库中的 core/public/AGENTS.md 及其全部头文件源码梳理这组接口的模块划分、具体契约内容、维护规则以及如何按“归属模块”定位回归问题帮助你在阅读或扩展 Lynx 内核时准确把握这条公共 API 边界。一、目录定位稳定的核心对外接口面AGENTS.md 对该目录的职责描述非常明确This directory contains stable core-facing interface headers shared across shell, renderer, runtime, resource loading, list handling, devtool integration, and native module bindings.也就是说凡是 shell引擎宿主壳、renderer渲染端、runtimeJS 运行时、资源加载、列表组件、devtool 以及 native module 需要与核心引擎交互的地方其接口都收敛在这里。从构建配置看core/public/BUILD.gn 用lynx_core_source_set(public)注册了这个目标sources列表全部是.h头文件如lynx_engine_proxy.h、lynx_resource_loader.h、jsb/lynx_native_module.h、devtool/lynx_devtool_proxy.h等没有编译实现单元——这印证了文档中“Keep this directory header-only and dependency-light”的编辑规则。从源码结构看AGENTS.md的 Module Map 与实际目录内容一一对应文档中的分组对应头文件均位于 core/public 下职责shell/runtime/layout 代理lynx_engine_proxy.h、lynx_layout_proxy.h、lynx_runtime_proxy.h引擎/布局/运行时三线程的任务分发与跨线程调用列表契约list_container_proxy.h、list_engine_proxy.h、list_data.h列表滚动控制与懒加载 diff 数据资源加载lynx_resource_loader.h模板、图片、JS 等资源请求/响应的公共契约生命周期与性能perf_controller_proxy.h、runtime_lifecycle_observer.h、vsync_observer_interface.h计时事件上报、运行时生命周期回调、VSync 观察jsb/lynx_native_module.h、lynx_extension_module.h、native_module_factory.h、extension_module_factory.h、lynx_module_callback.hnative module 与扩展模块的 JS 绑定接口devtool/lynx_devtool_proxy.h、lynx_inspector_owner.hdevtool 代理与 inspector 归属管理此外目录中还有大量辅助契约头如pub_value.h跨层传递的pub::Value值类型、page_options.h、pipeline_option.h、ui_delegate.h、gesture_handler.h等它们共同构成lynx_core_source_set(public)的完整头文件清单。二、三大 Proxy 接口shell 与引擎/运行时/布局之间的桥梁Proxy 类是 Lynx 引擎解耦宿主实现与核心逻辑的关键抽象shell 侧持有 proxy具体实现由各平台/宿主提供。2.1 LynxEngineProxy引擎线程的总入口LynxEngineProxy 是职责最广泛的接口命名空间为lynx::shell核心方法可以按功能域分为四类任务分发DispatchTaskToLynxEngine(base::closure task)是所有跨线程进入引擎线程任务的统一入口事件转发SendTouchEvent带tag、坐标与时间戳还有基于pub::Value参数的重载、SendCustomEvent、SendGestureEvent、SendBubbleEvent以及事件管线控制StartEventGenerate/StartEventCapture/StartEventBubble/StartEventFire、伪类状态OnPseudoStatusChanged列表驱动ScrollByListContainer、ScrollToPosition、ScrollStopped以及复用池操作ObtainListChild/RecycleListChild/RenderListChild/UpdateListChild/GetListData布局与渲染钩子TriggerLayout、MarkLayoutDirty、GetDensity、EnableRasterAnimation、OnFirstMeaningfulPaint。值得注意的两个设计细节CustomEventDispatchOptions::emergency文档注释说明紧急任务会在下一个消息循环边界优先于普通 ready 任务被选中但不会抢占正在执行的任务。这是事件派发优先级的公共契约SendCustomEventWithOptions提供了非纯虚的默认实现直接回退到SendCustomEvent——这是一个典型的“additive change over breaking change”示例新增带选项的接口时不破坏既有实现者GetAncestorElements的注释明确要求调用方在“使用 async tasm 时不要调用此函数”说明接口的线程/架构假设直接写进了公共契约。2.2 LynxRuntimeProxy宿主侧对 JS 运行时的调用LynxRuntimeProxy 定义了 shell 向 runtime 线程发起 JS 调用的五个纯虚方法CallJSFunction(module_id, method_id, params)按 module/method 定位并调用 JS 函数CallJSApiCallbackWithValue(callback_id, params)回调 JS 侧注册的 API 回调CallJSIntersectionObserver(observer_id, callback_id, params)Intersection Observer 的专用通道EvaluateScript(url, script, callback_id)动态脚本求值RejectDynamicComponentLoad(url, callback_id, err_code, err_msg)动态组件加载失败时的 reject 通道。参数统一采用std::unique_ptrpub::Value转移所有权体现了“值跨线程、所有权唯一”的契约风格。2.3 LynxLayoutProxy布局线程的最小接口LynxLayoutProxy 只有两个方法DispatchTaskToLynxLayout(base::closure task)与TriggerLayout()。它展示了这组头文件“dependency-light”的原则——布局线程的对外面被刻意压缩到最小。三、列表契约滚动控制与懒加载数据3.1 两级代理结构列表相关的滚动控制被拆成了两级接口ListEngineProxy纯虚接口声明ScrollByListContainer/ScrollToPosition/ScrollStopped三个滚动方法ListContainerProxy持有ListEngineProxy*的具体类标注LYNX_EXPORT实现同名方法并转发给注入的 engine proxy构造函数explicit ListContainerProxy(ListEngineProxy* list_engine_proxy)体现了依赖注入关系。值得注意的是LynxEngineProxy 中也保留了ScrollByListContainer等列表方法源码中留有注释 “TODO(chenyouhui): Split the list interface into its own public API.”——从源码结构看列表接口正处在“从引擎总代理中拆分独立出来”的演进过程中ListContainerProxy/ListEngineProxy就是拆分后的目标形态。3.2 ListData列表懒加载的 diff 契约ListData命名空间lynx::tasm承载list懒加载所需的全部 diff 信息注释指出该信息“由 FE 框架生成”并在 Fiber 架构下已被标记 deprecated。其字段与语义完整如下view_type_names_视图类型名列表SetViewTypeNamesnew_arch_/diffable_架构与 diff 能力开关SetNewArch/SetDiffablefull_span_跨列全宽项索引setter 会内部std::sort保持有序sticky_top_/sticky_bottom_吸顶/吸底项索引同样有序化六组 diff 操作SetInsertions/SetRemovals/SetUpdateFrom/SetUpdateTo/SetMoveFrom/SetMoveTo均为模板接口接受任意 vector-like 容器对应的Get*方法返回const std::vectorint32_tview type 返回const std::vectorstd::string。该类的 getter/setter 全部内联在头文件内符合“目录不移动实现逻辑”的规则——它只是数据载体契约真正的 diff 应用在 renderer/list 模块完成。四、资源加载契约LynxResourceLoaderlynx_resource_loader.h 是资源加载的公共契约核心命名空间lynx::pub包含请求/响应/流式委托四部分4.1 资源类型与请求LynxResourceType枚举定义了 15 种资源类型源码注释标明 “generated by IDL”enum class LynxResourceType : int32_t { kGeneric 0, kImage 1, kFont 2, kLottie 3, kVideo 4, kSvg 5, kTemplate 6, kLazyBundle 7, // LazyBundle from js kLynxCoreJs 8, kExternalJs 9, kAssets 11, kI18nText 12, kGraphics 13, kTheme 14, kFrame 15, kExternalByteCode 16, // external byteCode loaded from outside; };注意枚举值从 9 跳到 11——中间的值已被占用或移除这类“保留空洞”正是“additive change、避免破坏 ABI”原则的直接体现。LynxResourceRequest结构简单url、type以及request_in_current_thread默认true注释标明当前用于 lazy bundle长期会被移除。4.2 响应与计时LynxResourceResponse携带std::vectoruint8_t data、void* bundle用于平台可返回的 template bundle 指针源码留有 “make LynxTemplateBundle a public class” 的 TODO、resource_handle、err_code/err_msg和ResourceLoadTiming。Success()以err_code 0判定成功。ResourceLoadTiming提供了一套微秒级加载计时字段可用于平台侧精细化性能归因字段含义request_start收到客户端请求request_internal_prepare_finish内部准备完成如 URL 检查、fallback 逻辑request_prepare_to_call_fetcher开始准备调用 fetcherrequest_send_to_fetcher实际把请求发给 fetcherresponse_received_from_fetcher实际收到 fetcher 响应response_trigger_callback触发客户端回调图片类请求还有LynxImageResponseOptionsfallback_paths回退路径、file_cache_name、use_highest_priority、mapped_file_cache_key/mapped_memory_cache_key缓存键映射。4.3 加载入口与流式委托LynxResourceLoader继承std::enable_shared_from_this导出LYNX_EXPORT对外提供LoadResource(request, callback)与LoadResourcePath(request, path_callback)非虚的公共入口内部转发给纯虚的LoadResourceInternal/LoadResourcePathInternal并叠加 replay 缓存逻辑SetReplayResourceCache注入tasm::replay::ReplayResourceCacheLoadStream(request, stream_delegate)流式加载配合LynxStreamDelegate的OnStart(size)/OnData(data)/OnEnd()/OnError(msg)四个回调LoadBytecode(request, callback)默认实现直接回包err_code -1、LoadBytecode is not supported.需要时由平台覆写IsLocalResource(url)默认false、ShouldRedirectUrl默认原样返回 URL、ShouldRedirectUrlAsync默认报错-1提示“not supported”——这些带默认实现的虚函数同样是“新增能力不破坏旧实现”的模式。五、生命周期与性能RuntimeLifecycleObserver 与 VSync、Perf 代理5.1 RuntimeLifecycleObserverRuntimeLifecycleObserver命名空间lynx::runtime标注“Triggered on runtime thread”定义 runtime 生命周期回调OnRuntimeCreate(std::shared_ptrIVSyncObserver observer)注意它把 VSync observer 作为参数回传给监听者说明 VSync 通道是在 runtime 创建时注入的OnRuntimeInit(int64_t runtime_id)OnAppEnterForeground()/OnAppEnterBackground()前后台切换OnRuntimeAttach(void* env, const char* runtime_type)/OnRuntimeDetach()运行时附着/脱离。5.2 IVSyncObserverIVSyncObserver 是“exported from lynx.so”的 C VSync 观察接口三个方法分别对应帧时序的三个插入点RequestAnimationFrame(id, callback)帧动画回调RequestBeforeAnimationFrame(id, callback)帧前回调RegisterAfterAnimationFrameListener(callback)帧后监听。回调签名统一为base::MoveOnlyClosurevoid, int64_t, int64_t移动语义闭包。同目录的vsync_monitor_platform_impl.h则是对应的平台实现侧接口二者构成“接口 平台实现”的分层。5.3 PerfControllerProxyPerfControllerProxy 是性能数据上行的公共契约核心方法SetHostPlatformType(const std::string type)设置宿主平台类型文档注释举例windowsClay影响PipelineEntry中HostPlatformTiming的平台类型标签MarkTiming(tasm::TimingKey, const tasm::PipelineID)以 key 管线 ID 打点SetTiming(timing_key, timestamp_us, pipeline_id)直接写入微秒时间戳SetHostPlatformTiming(...)平台侧计时事件写入GetPlatform()返回当前运行平台文档注释举例windows macOS iOS Android LinuxRunTaskInReportThread(base::closure task)向 report 线程投递任务OnEvent(tasm::report::MoveOnlyEvent event)事件上报入口移动语义传递MoveOnlyEvent。这里的TimingKey与PipelineID类型来自 core/public/timing_key.h 和 core/public/pipeline_option.h性能计时的键体系本身就是公共契约的一部分。六、jsb/native module 与扩展模块的绑定接口core/public/jsb/下的五个头文件定义 JS 绑定层JSB的模块接口。以最核心的 lynx_native_module.h 为例LynxNativeModule标注LYNX_EXPORT_FOR_DEVTOOL注释说明 “Upper-level modules can inherit from LynxNativeModule to register their own JSB”即它是所有 native module 的公共基类内部Delegate类提供InvokeCallback(callback, invoke_pre_func)、RunOnJSThread(func)、RunOnPlatformThread(func)三个纯虚方法把“回调 JS”“切 JS 线程”“切平台线程”三件跨层高频动作抽象出来供 module 开发者统一使用NativeModuleMethod { name, args_count }与NativeModuleMethodsstd::unordered_map用于方法名到参数个数的注册表文件头部还有一段 Objective-C 兼容处理用#pragma push_macro保护LynxNativeModule这个与 Objective-C 库同名的宏冲突并在文件尾恢复——这是多平台头文件维护中真实存在的兼容细节。同目录的lynx_extension_module.hextension_module_factory.h与lynx_native_module.hnative_module_factory.h构成 native/extension 两族模块的平行结构lynx_module_callback.h则承载回调句柄。此外 lynx_runtime_proxy.h 被lynx_native_module.h直接包含说明 native module 到 runtime 的调用通道也走这组公共契约。七、维护规则如何安全地修改这组头文件AGENTS.md 的 Edit Rules 给出了三条维护准则它们都有源码层面的对应佐证视同共享 API 面签名、所有权或类型变更通常需要 shell、runtime、资源加载与平台实现协同更新。证据是LynxEngineProxy被jsb/lynx_native_module.h包含、ListContainerProxy依赖ListEngineProxy、RuntimeLifecycleObserver依赖IVSyncObserver——头文件之间已形成一张依赖网改动任何一处都可能波及多模块保持 header-only 与轻依赖BUILD.gn的 source set 只有头文件头文件仅依赖base/include/closure.h、core/base/lynx_export.h等少量基础头优先增量式变更如前文所述的SendCustomEventWithOptions默认实现、LoadBytecode/ShouldRedirectUrlAsync的“默认不支持”实现、LynxResourceType的保留空洞都是“新能力以默认实现/新增枚举值落地不破坏既有派生类”的模式。八、回归症状与验证路径契约变了去哪找问题当一次“看起来很小”的头文件编辑导致多模块构建失败、或“编译通过但运行时坏掉”AGENTS.md 归纳了三个典型症状本质都是公共契约失配多模块构建失败 → 共享契约签名/类型变了proxy 调用编译通过但运行时崩溃 → 所有权如std::unique_ptrpub::Value、回调生命周期如LynxStreamDelegate、base::closure捕获的裸对象或线程假设如OnEvent的线程约定、GetAncestorElements的 async tasm 限制变了但实现侧未同步native module / resource loader / list 集成回归 → 契约失配通常源头在此目录。由于本目录不定义自己的单测 exec文档要求“通过归属实现模块验证”对应到仓库中的构建目标验证目标覆盖的契约定义位置shell_unittests_execproxy 与生命周期契约core/shell/testing/BUILD.gnlist_container_testset_exec列表面向的契约core/list/BUILD.gnlazy_bundle_test_exec或 runtime 资源测试资源加载契约core/resource/BUILD.gn、core/runtime/BUILD.gnruntime_tests_exec或 module-binding 测试jsb/契约core/runtime/BUILD.gn另外 core/renderer/ui_component/list/BUILD.gn 也引用了list_container_testset_exec说明列表契约的验证同时覆盖 renderer 侧的 list 组件。九、小结core/public虽然只是一个“全是头文件”的目录但它承载了 Lynx 引擎最关键的一条边界shell 与引擎/运行时/布局三线程之间、宿主平台与 JS 运行时之间、资源系统与模板加载之间、列表容器与 diff 引擎之间以及 JS 与 native module 之间的全部公共契约。理解这个目录的价值在于读到*proxy*.h时应理解为“shell 侧持有、宿主实现”的注入点读到LynxResourceLoader的默认实现时应理解为平台可覆写的扩展缝修改这里任何签名前先确认“additive over breaking”是否可能并预先规划 shell、runtime、resource、list 四路实现与对应验证 target 的协同更新。掌握这一契约层后你可以在仓库中沿 core/shell、core/runtime、core/renderer、core/list 等实现目录继续深入追踪每一条公共接口在真实引擎中的落点。【免费下载链接】lynxEmpower the Web community and invite more to build across platforms.项目地址: https://gitcode.com/GitHub_Trending/lynx10/lynx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考