Ladybird LibWeb 代码规范与工程模式：目录结构、错误处理与 Web 接口设计详解

Ladybird LibWeb 代码规范与工程模式目录结构、错误处理与 Web 接口设计详解【免费下载链接】ladybirdTruly independent web browser项目地址: https://gitcode.com/GitHub_Trending/la/ladybird本文基于 Ladybird 浏览器仓库的官方文档 LibWeb Code Style Patterns系统讲解其 Web 引擎库 LibWeb 的核心工程约定按 Web 规范spec组织目录与命名空间、五种错误类型的职责划分、强制性的规范链接与步骤注释风格以及 IDL 到 C 接口的映射规则。读完后你将能够理解 LibWeb 的代码组织逻辑知道在贡献代码时该使用哪种错误类型、如何为 Web 规范的抽象操作AO编写注释以及新接口文件应放在哪里。一、按 Web 规范组织目录与命名空间LibWeb 的基础布局原则是每个独立的 Web 规范对应一个子目录并因此对应一个 C 命名空间。以 XHR 规范xhr.spec.whatwg.org为例代码位于 Libraries/LibWeb/XHR/使用 C 命名空间Web::XHR这一点在当前仓库中可以直接验证。Libraries/LibWeb/XHR/ 目录下包含XMLHttpRequest.cpp、XMLHttpRequest.h、XMLHttpRequest.idl、FormData.*、ProgressEvent.*等文件覆盖了 XHR 规范定义的全部接口。目录结构本身可以从 Libraries/LibWeb/ 的顶层目录得到印证DOM/、CSS/、Fetch/、HTML/、WebIDL/、WebSockets/、IndexedDB/、SVG/、WebGL/、Worker/等子目录几乎与 Web 平台规范一一对应这是理解整个 LibWeb 代码库的“地图”。此外还有两条补充规则子-子目录必要时可以进一步细分例如Libraries/LibWeb/HTML/Scripting/仓库中真实存在包含ClassicScript、ModuleScript、Script、Agent、Fetching等脚本加载相关实现用于容纳 HTML 规范中体积较大的 Scripting 章节。跨规范特性的归属当一份规范同时影响 Web 平台的多个区域时用最佳判断决定代码位置。文档给出的例子是 CSSOM——其中属于 CSS 的部分放在LibWeb/CSS//Web::CSS而对 HTML 规范中Window的扩展则放在Window相关位置。二、错误处理五种错误类型及其职责边界这是本文档最核心、也最容易写错的部分。LibWeb 中常见五种错误类型各管一段混用会破坏可维护性。2.1AK::ErrorOrT只用于传播 OOMErrorOr是 AK 基础库的错误类型在 LibWeb 中原则上只用来传播来自 AK 及其他基础库的内存耗尽OOM错误不应用它传播其他类型的错误。关键实践是AK::ErrorOr应尽可能向上传播直到接近 JS 边界时才通过TRY_OR_THROW_OOM宏转成 JS 错误对象。这样做的目的是避免“几乎所有函数都返回WebIDL::ExceptionOrT”的局面——如果一遇到 OOM 就立即抛 JS 异常错误会被过早包装、丢失上下文且中间层函数签名会被迫全部改为ExceptionOr返回类型。2.2Web::WebIDL::ExceptionOrT与 JS 绑定交互的通用错误类型这是 LibWeb 中最常用、也最宽泛的错误类型。其源码实现位于 Libraries/LibWeb/WebIDL/ExceptionOr.h文档中描述的“内部存储受支持错误的 variant”对应实现为第 136 行// https://webidl.spec.whatwg.org/#idl-exceptions VariantValueType, SimpleException, GC::RefDOMException, JS::Completion m_result_or_exception;即内部实际是一个四路Variant成功值 三种错误。文档列举的三种错误与之逐一对应错误类型含义SimpleExceptionECMA 内置错误轻量包装见 2.3GC::RefDOMExceptionWebIDL 定义的 DOM 异常对象见 2.4JS::Completion来自JS::ThrowCompletionOrT的完成记录且断言其Type必为Throw实现上还有一个值得注意的细节ExceptionOr在构造时接收JS::Completion会VERIFY该 completion 确实是错误第 82 行VERIFY(completion.is_error())与文档“assumed to be ofType::Throw”的要求一致。选择原则凡是函数需要与 JS 绑定层交互都应返回ExceptionOr因为绑定层知道如何把上述任何一种内部错误转成真正的 JS 对象。2.3Web::WebIDL::SimpleExceptionECMA 内置错误的轻量包装SimpleException是对 ECMAScript 内置错误的薄封装。源码 Libraries/LibWeb/WebIDL/ExceptionOr.h 中的定义与文档描述完全吻合#define ENUMERATE_SIMPLE_WEBIDL_EXCEPTION_TYPES(E) \ E(EvalError) \ E(RangeError) \ E(ReferenceError) \ E(TypeError) \ E(URIError) enum class SimpleExceptionType { ENUMERATE_SIMPLE_WEBIDL_EXCEPTION_TYPES(E) }; struct SimpleException { SimpleExceptionType type; Utf16String message; };规则是不要直接构造EvalError/RangeError/TypeError等 JS 对象而是当 Web 规范要求时构造一个带正确类型和消息的SimpleException由绑定层负责将其转换为真实的 JS 错误对象。这保持了“规范语义错误在 C 层只是数据真正的 JS 对象由绑定层统一生成”的边界。参考WebIDL 规范中的 simple exception 定义webidl.spec.whatwg.org/#dfn-simple-exception。2.4Web::WebIDL::DOMExceptionJS 内置错误都不够用时DOMException是 WebIDL 规范中定义的一类异常用于 Web 抽象操作Abstract OperationAO中 JS 五种内置错误都不足以表达的场景例如NotFoundError、SecurityError、QuotaExceededError等仓库中 Libraries/LibWeb/WebIDL/DOMException.idl 定义了该接口另有QuotaExceededError的具体实现位于 Libraries/LibWeb/WebIDL/QuotaExceededError.idl。与SimpleException相同的使用原则只有当 Web 规范明确指示时才使用并按规范指定的名称抛出。参考WebIDL 规范中的 DOMException 定义webidl.spec.whatwg.org/#idl-DOMException。2.5JS::ThrowCompletionOrTLibJS 的完成记录非必要不使用ThrowCompletionOrT来自 LibJS使用 ECMAScript 规范中的 “completion record” 机制传播错误和其他 AO 结果。文档明确要求在 LibWeb 中除非绝对必要否则不要使用它——典型必要场景是重写某个返回该类型的JS::Object虚函数。使用纪律在调用点应尽快将其包装成WebIDL::ExceptionOrT继续传播不要让ThrowCompletionOr在 LibWeb 层裸奔。参考ECMAScript 规范中的 Completion Record 定义tc39.es/ecma262/#sec-completion-record-specification-type。2.6 错误类型选择速查函数会分配内存、调用 AK → 用 AK::ErrorOr尽量向上传播边界处 TRY_OR_THROW_OOM 函数需要与 JS 绑定交互 → 用 Web::WebIDL::ExceptionOrT 规范要求抛 TypeError 等内置错 → 构造 Web::WebIDL::SimpleException 规范要求抛 NotFoundError 等 → 构造/抛出 Web::WebIDL::DOMException 重写 JS::Object 虚函数被迫返回 → JS::ThrowCompletionOrT调用点立即包成 ExceptionOr三、注释规范规范链接 逐步注释与 LibJS 的要求一致所有代表 Web 规范中的操作AO或 JS 函数的函数都必须满足以下注释要求3.1 函数上方的规范链接函数定义上方必须写明对应的 spec 链接。文档给出的 Fetch 规范示例// https://fetch.spec.whatwg.org/#concept-fetch WebIDL::ExceptionOrGC::RefInfrastructure::FetchController fetch(JS::Realm realm, Infrastructure::Request request, Infrastructure::FetchAlgorithms const algorithms, UseParallelQueue use_parallel_queue) { // ... }可以对照仓库验证这一风格Libraries/LibWeb/WebIDL/Types.h 中每个 WebIDL 基础类型别名Boolean、Byte、Octet、Long、Double等上方都有一行 webidl.spec.whatwg.org 的链接注释例如using Long Infra::Signed32BitInteger;上方标注// https://webidl.spec.whatwg.org/#idl-long。3.2 每个算法步骤的注释规范算法的每一步都要有对应注释注释与代码之间空一行// 1. Assert: requests mode is navigate or processEarlyHintsResponse is null. VERIFY(request.mode() Infrastructure::Request::Mode::Navigate || !algorithms.process_early_hints_response().has_value()); // 2. Let taskDestination be null. GC::PtrJS::Object task_destination; // ...配套细则某一步暂时无法实现时在该注释前加FIXME前缀明确标记未完成步骤注释与代码之间保持空行使“哪段代码实现哪一步”一目了然优化如快速路径要用// OPTIMIZATION:注释标记并说明理由为某个本身已有良好规范的特性加入非标准代码时应显式标注为非标准该要求并非普遍适用例如布局与绘制相关代码只有粗略规范若规范在算法步骤前后还有额外的散文prose说明不需要把那些散文复制进代码。这套规范注释模式的价值在于LibWeb 的实现与 W3C/WHATWG 规范是“逐步骤对照实现”的注释即映射表任何一步的实现与规范不一致都能在 code review 中被快速发现。四、JS 接口IDL、命名与文件摆放4.1 IDL 书写尽量逐字照抄规范IDLWeb IDL 接口定义语言文件应尽量 verbatim 地从规范拷贝仅在确有必要时修改——例如 IDL 解析器的已知短板、或需要添加非标准的扩展属性。具体包括不要重新排序函数、不要改参数名。与规范唯一的系统性差异缩进使用四个空格与其他代码保持一致规范示例普遍是两空格。仓库中的真实 IDL 文件可以验证这种“接口名与文件同名”的组织方式如 Libraries/LibWeb/XHR/XMLHttpRequest.idl、Libraries/LibWeb/WebIDL/DOMException.idl 等。4.2 C 命名贴近接口的精确名称类名和文件名应尽可能使用接口的精确名称注意与 LibJS 的做法不同——LibJS 喜欢加Object之类的后缀LibWeb 不加。出现命名冲突时优先引入嵌套命名空间解决文档给出的例子是Fetch::Request与Fetch::Infrastructure::Request并存。这种“同文件三件套同目录、冲突用命名空间隔离”的方式避免了大量别名alias或重命名带来的混乱。4.3 文件摆放规则给定一个接口其.cpp、.h、.idl三个文件应放在同一目录。唯一的例外当实现是手写的、无法从 IDL 生成时——这种情况下该接口没有 IDL 文件代码应放在Libraries/LibWeb/Bindings/目录中该目录在仓库中真实存在专门容纳绑定层代码。结合 4.1 的 IDL 原则可以总结 LibWeb 接口文件的完整生命周期从规范拷贝 IDL四空格缩进不改名不排序→ 放入对应规范子目录由 IDL 生成器产生绑定代码接口类名与文件名使用规范原名无法生成的部分手写放入Bindings/接口实现的公开方法遵循第三节的注释规范spec 链接 步骤注释。五、小结这套模式解决什么问题LibWeb Code Style Patterns 文档虽不长但每一条都在回答同一个问题如何让 C 实现与 Web 规范保持可追踪的同步关系。目录/命名空间 规范spec目录跨规范特性靠判断五种错误类型各司其职ExceptionOr是与 JS 世界的唯一通用异常通道规范链接 步骤注释使每个 AO 的实现都可以与规范逐行对照未完成部分用FIXME显式留痕IDL 逐字照抄 原名命名 三件套同目录保证 WebIDL 接口层零损耗。如果你是准备为 Ladybird 的 LibWeb 贡献代码建议先通读这份文档再到对应的规范子目录如 Libraries/LibWeb/XHR/ 或 Libraries/LibWeb/WebIDL/对照阅读一个完整接口即可快速建立起与代码库一致的编码习惯。【免费下载链接】ladybirdTruly independent web browser项目地址: https://gitcode.com/GitHub_Trending/la/ladybird创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考