Yew 框架贡献指南从开发环境搭建到测试、Lint 与基准测试的完整工作流【免费下载链接】yewRust / Wasm framework for creating reliable and efficient web applications项目地址: https://gitcode.com/gh_mirrors/ye/yew本篇指南以仓库根目录 CONTRIBUTING.md 为主线系统梳理 YewRust / Wasm 前端框架的本地开发环境搭建、测试矩阵原生测试、浏览器测试、宏测试、文档测试、拼写检查、Clippy/Rustfmt 静态检查、基准测试以及官网文档维护的完整流程。读完本文你将掌握如何基于cargo-make任务编排运行 Yew 的全部质量检查流水线理解各测试类型的底层实现与常见坑点并具备向 Yew 仓库提交高质量 PR 的实操能力。一、搭建本地开发环境1.1 添加 Wasm 编译目标Yew 的应用代码最终编译为 WebAssembly 并在浏览器中运行因此第一步是为 Rust 工具链添加wasm32-unknown-unknown目标rustup target add wasm32-unknown-unknown该目标是未知操作系统、未知环境的裸 wasm 编译目标不依赖任何系统库是 Rust 生态在浏览器端运行的标准编译目标。添加后即可用cargo build --target wasm32-unknown-unknown将 Yew 组件树编译为 wasm 模块。1.2 安装 cargo-make 任务编排工具Yew 将测试、Lint、格式化等常用操作封装为cargo-make任务需要先安装cargo install cargo-make安装完成后可以通过以下命令查看 Yew 工作区中定义的全部任务及其说明cargo make --list-all-steps从根目录 Makefile.toml 的头部注释可以看到任务被组织为两条主流程checks-flow由lint、lint-release、format三个任务组成并行 fork 执行负责 Clippy 检查debug 与 release 两种构建以及 nightly 格式化test-flow由test、doc-test、website-test三个任务组成并行执行负责全量测试。此外packages/yew还提供了clippy-feature-soundness任务依赖 cargo-hack用于对 yew、yew-agent、yew-router 做 feature 组合幂等检查。1.3 根 Makefile 的关键配置解读根目录 Makefile.toml 中有几个对贡献者影响直接的配置min_version 0.32.4要求本地 cargo-make 不低于该版本default_to_workspace false任务默认不在整个 workspace 上执行需要在任务级显式声明workspace true例如test、doc-test任务CARGO_MAKE_WORKSPACE_SKIP_MEMBERS执行 workspace 级命令时跳过examples/*与tools/*避免示例和工具影响核心包的检查速度CARGO_MAKE_CLIPPY_ARGS -- --denywarnings所有 Clippy 调用默认把警告升级为错误保证 CI 零告警。二、运行全部测试cargo make test-flow文档推荐的统一入口是cargo make test-flow根据根 Makefile.toml 中test-flow的定义该命令会并行 fork执行三个任务任务实际命令说明testcargo test --all-targetsworkspace编译并运行全部 target单元测试、集成测试等doc-testcargo test --doc --all-featuresworkspace以全部 feature 组合运行文档注释中的 doctestwebsite-testcargo test -p website-test将官网文档中的 Rust 代码块作为 doctest 运行三个任务互不依赖并行执行可以显著缩短全量验证时间。需要注意的是workspace 级任务会按照CARGO_MAKE_WORKSPACE_SKIP_MEMBERS跳过examples/*与tools/*。2.1 浏览器测试与 Geckodrivercargo make test在执行时会调用浏览器驱动。文档明确指出如果 PATH 中找不到 Geckodrivercargo-make 会自动把它下载到临时目录。Geckodriver 是 Firefox 的 WebDriver 实现Yew 的 wasm 测试通过它驱动真实浏览器运行。一个常见的坑Geckodriver 按firefox这个名字在 PATH 中查找浏览器可执行文件。如果你安装的是 Firefox Developer Edition其二进制名是firefox-developer-edition会导致测试报错。解决办法二选一安装标准版 Firefox创建符号链接ln -s $(which firefox-developer-edition) /usr/local/bin/firefox将firefox链接到开发者版二进制。在 packages/yew/Makefile.toml 中可以看到浏览器测试的真实形态wasm-test任务调用wasm-pack test --firefox --headless并携带csr,hydration,ssr,test等 feature即在无头 Firefox 中运行 Yew 的 CSR客户端渲染与 hydration水合测试而native-test任务则以cargo test --features csr,ssr,hydration,test跑原生非 wasm侧测试。两者共同构成test任务的依赖链。2.2 Fetch service 测试与 httpbinFetch serviceyew 的网络请求服务测试需要本地的 httpbin 服务。如果本机装有 Dockercargo make test会自动在容器中启动 httpbin否则可以通过环境变量指定一个可用的 httpbin 实例HTTPBIN_URLhttps://your-httpbin.example.com cargo make testHTTPBIN_URL允许你将测试指向任意兼容 httpbin 的端点自建实例或公司内网镜像均可这在 CI 或离线环境下尤其有用。2.3 宏测试与 stderr 基线文件Yew 的过程宏html!、#[function_component]、#[hook]等在编译期会产生大量诊断信息。为了确保错误信息准确、易读仓库采用 trybuild 风格的测试每个预期失败的测试文件旁都配有一个.stderr文件记录编译器输出的精确错误快照。这些文件位于packages/yew-macro/tests/html_macro/html!宏相关36 个.rs 15 个.stderrpackages/yew-macro/tests/function_component_attr/#[function_component]属性宏20 个.rs 14 个.stderrpackages/yew-macro/tests/hook_attr/、hook_macro/、classes_macro/、derive_props/、props_macro/、html_lints/等目录同样遵循.rs.stderr配对模式。新增或修改宏测试时必须同步更新对应的.stderr文件否则 trybuild 会比较失败。文档特别强调编译器每次发布都可能改变错误输出格式因此这些基线文件应使用 Rust 1.56 生成部分测试依赖该版本稳定的 const generics 特性。更新/生成.stderr文件的方式是在yew-macro目录下运行cargo make test-overwrite从 packages/yew-macro/Makefile.toml 可以看出test-overwrite继承了test任务并设置环境变量TRYBUILD overwritetrybuild 检测到该变量后会用当前编译器输出覆盖.stderr基线。另外该任务固定使用toolchain 1.85.0运行可传参指定过滤条件例如cargo make test html_macro而test-lint则切换到 nightly 工具链并启用lintsfeature 运行test_html_lints。三、拼写检查typosYew 用 typos 捕获拼写错误CI 会在每个 PR 上自动运行。本地使用方式cargo install typos-cli --locked typos # 检查拼写错误 typos -w # 自动修复拼写错误误报false positive通过仓库根目录的 _typos.toml 配置排除[files] extend-exclude [examples/router/data/syllables.txt, examples/function_router/data/syllables.txt] [default.extend-words] ba baextend-exclude跳过含大量造词数据的音节约表syllables.txt避免误报extend-words将特定词加入白名单如ba。提交前运行typos是低成本但很有效的 CI 通过技巧。四、Lint 与格式化执行静态检查的命令cargo make lint根 Makefile.toml 中lint任务本质上是cargo clippy -- --denywarnings即任何 Clippy 警告都会被当作错误拒绝。此外还有lint-releasecargo clippy --all-targets --release -- --denywarnings——因为 Yew 在 debug 与 release 构建之间存在代码差异release 形态的检查同样必不可少checks-flow会一次性并行运行lint、lint-release和format。自动修复格式化问题则使用 nightly 工具链cargo nightly fmt仓库 rustfmt.toml 配置了相当多的格式化规则贡献者应尽量保持一致风格例如edition 2024、format_code_in_doc_comments true文档注释中的代码块也参与格式化、wrap_comments truecomment_width 100、group_imports StdExternalCrate与imports_granularity Module按标准库/外部/本地分组、模块粒度合并导入、use_field_init_shorthand true等。若本机 nightly 版本有差异导致cargo nightly fmt输出与 CI 不一致建议先提交代码再让 CI 给出格式化提示或直接安装与 CI 对齐的 nightly。五、基准测试Yew 使用 js-framework-benchmark 对框架整体做性能基准测试。操作方式clonebakape/js-framework-benchmark仓库按其 README 的指引运行。仓库内与基准测试配套的工具包括 tools/benchmark-corevnode 构建/拼接基准、tools/benchmark-hooks 与 tools/benchmark-structhooks 与 struct 组件两种写法的对比基准以及 tools/benchmark-ssr。CI 侧的 collect_sizes.py、make_benchmark_ssr_cmt.py、make_example_size_cmt.py 等脚本负责采集并发布基准结果。如果你对性能优化敏感可以先在本地跑benchmark-*相关 bench 再提交改动。六、设计新 API 的准则文档强调在构建新 API 时应站在使用者视角自问三个问题这个 API 会不会导致令人困惑、难以定位的错误信息这个 API 能否与其他 API 良好组合这个 API 的用法是否直观同时推荐参考以下两份指南仅作设计参考非仓库内文件The Rust API GuidelinesRust 官方 API 设计规范Elegant Library APIs in RustRust 库 API 优雅设计经验谈这些是指导性原则而非强制规范——在个别场景无法完全遵循时应优先保证可用性与一致性。结合仓库源码可见Yew 的 API 层大量使用了强类型与编译期约束例如 packages/yew/src/function_component.rs 等宏实现会在编译期校验组件函数的返回类型、Props 参数形态把错误提前到编译阶段暴露这正是错误信息清晰可定位的实践体现。七、维护官网文档Yew 官网yew.rs源码位于仓库 website 目录绝大多数内容以 Markdown/MDX 编写普通文档修改不需要改动任何 Rust 代码文档正文位于 website/docs 与 website/versioned_docs构建工具是 Docusaurus本地预览npm install npm start生产构建npm run build本地化内容位于 website/i18n含 ja、zh-Hans、zh-Hant 等语言。详细说明见 website/README.md。值得一提的验证机制是cargo make website-test即test-flow中的第三个任务tools/website-test 会把文档中的 Rust 代码块自动收集为 doctest 执行其入口 tools/website-test/src/lib.rs 通过include!(concat!(env!(OUT_DIR), /website_tests.rs))在构建期生成测试代码。若文档代码块之间存在前后依赖可以在文档末尾添加!-- COMBINE CODE BLOCKS --注释让测试装配器按 diff 标记把多个代码块拼接为一段完整程序后统一测试同时可用// ...行告知装配器丢弃之前的上下文。这意味着你写的每一个 Rust 示例都会被真实编译运行编写文档时务必保证代码块可独立编译。八、贡献流程速查表场景推荐命令查看全部可用任务cargo make --list-all-steps运行全量测试原生 文档 网站代码块cargo make test-flow浏览器wasm测试cargo make test自动下载 Geckodriver需firefox在 PATH自定义 httpbin 地址跑 fetch 测试HTTPBIN_URLurl cargo make test更新宏错误基线.stderr在packages/yew-macro下运行cargo make test-overwrite拼写检查 / 自动修复typos/typos -wClippy 格式化检查cargo make lint、cargo make checks-flow自动格式化cargo nightly fmt框架级性能基准clonebakape/js-framework-benchmark后按其 README 操作整体提交流程建议为rustup target add wasm32-unknown-unknown→ 安装 cargo-make → 运行cargo make test-flow与cargo make checks-flow→typos检查拼写 → 提交 PR。这样即可覆盖 Yew CI 的核心检查项测试、文档、Clippy、Rustfmt、拼写让评审与合并流程更加顺畅。【免费下载链接】yewRust / Wasm framework for creating reliable and efficient web applications项目地址: https://gitcode.com/gh_mirrors/ye/yew创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Yew 框架贡献指南从开发环境搭建到测试、Lint 与基准测试的完整工作流【免费下载链接】yewRust / Wasm framework for creating reliable and efficient web applications项目地址: https://gitcode.com/gh_mirrors/ye/yew本篇指南以仓库根目录 CONTRIBUTING.md 为主线系统梳理 YewRust / Wasm 前端框架的本地开发环境搭建、测试矩阵原生测试、浏览器测试、宏测试、文档测试、拼写检查、Clippy/Rustfmt 静态检查、基准测试以及官网文档维护的完整流程。读完本文你将掌握如何基于cargo-make任务编排运行 Yew 的全部质量检查流水线理解各测试类型的底层实现与常见坑点并具备向 Yew 仓库提交高质量 PR 的实操能力。一、搭建本地开发环境1.1 添加 Wasm 编译目标Yew 的应用代码最终编译为 WebAssembly 并在浏览器中运行因此第一步是为 Rust 工具链添加wasm32-unknown-unknown目标rustup target add wasm32-unknown-unknown该目标是未知操作系统、未知环境的裸 wasm 编译目标不依赖任何系统库是 Rust 生态在浏览器端运行的标准编译目标。添加后即可用cargo build --target wasm32-unknown-unknown将 Yew 组件树编译为 wasm 模块。1.2 安装 cargo-make 任务编排工具Yew 将测试、Lint、格式化等常用操作封装为cargo-make任务需要先安装cargo install cargo-make安装完成后可以通过以下命令查看 Yew 工作区中定义的全部任务及其说明cargo make --list-all-steps从根目录 Makefile.toml 的头部注释可以看到任务被组织为两条主流程checks-flow由lint、lint-release、format三个任务组成并行 fork 执行负责 Clippy 检查debug 与 release 两种构建以及 nightly 格式化test-flow由test、doc-test、website-test三个任务组成并行执行负责全量测试。此外packages/yew还提供了clippy-feature-soundness任务依赖 cargo-hack用于对 yew、yew-agent、yew-router 做 feature 组合幂等检查。1.3 根 Makefile 的关键配置解读根目录 Makefile.toml 中有几个对贡献者影响直接的配置min_version 0.32.4要求本地 cargo-make 不低于该版本default_to_workspace false任务默认不在整个 workspace 上执行需要在任务级显式声明workspace true例如test、doc-test任务CARGO_MAKE_WORKSPACE_SKIP_MEMBERS执行 workspace 级命令时跳过examples/*与tools/*避免示例和工具影响核心包的检查速度CARGO_MAKE_CLIPPY_ARGS -- --denywarnings所有 Clippy 调用默认把警告升级为错误保证 CI 零告警。二、运行全部测试cargo make test-flow文档推荐的统一入口是cargo make test-flow根据根 Makefile.toml 中test-flow的定义该命令会并行 fork执行三个任务任务实际命令说明testcargo test --all-targetsworkspace编译并运行全部 target单元测试、集成测试等doc-testcargo test --doc --all-featuresworkspace以全部 feature 组合运行文档注释中的 doctestwebsite-testcargo test -p website-test将官网文档中的 Rust 代码块作为 doctest 运行三个任务互不依赖并行执行可以显著缩短全量验证时间。需要注意的是workspace 级任务会按照CARGO_MAKE_WORKSPACE_SKIP_MEMBERS跳过examples/*与tools/*。2.1 浏览器测试与 Geckodrivercargo make test在执行时会调用浏览器驱动。文档明确指出如果 PATH 中找不到 Geckodrivercargo-make 会自动把它下载到临时目录。Geckodriver 是 Firefox 的 WebDriver 实现Yew 的 wasm 测试通过它驱动真实浏览器运行。一个常见的坑Geckodriver 按firefox这个名字在 PATH 中查找浏览器可执行文件。如果你安装的是 Firefox Developer Edition其二进制名是firefox-developer-edition会导致测试报错。解决办法二选一安装标准版 Firefox创建符号链接ln -s $(which firefox-developer-edition) /usr/local/bin/firefox将firefox链接到开发者版二进制。在 packages/yew/Makefile.toml 中可以看到浏览器测试的真实形态wasm-test任务调用wasm-pack test --firefox --headless并携带csr,hydration,ssr,test等 feature即在无头 Firefox 中运行 Yew 的 CSR客户端渲染与 hydration水合测试而native-test任务则以cargo test --features csr,ssr,hydration,test跑原生非 wasm侧测试。两者共同构成test任务的依赖链。2.2 Fetch service 测试与 httpbinFetch serviceyew 的网络请求服务测试需要本地的 httpbin 服务。如果本机装有 Dockercargo make test会自动在容器中启动 httpbin否则可以通过环境变量指定一个可用的 httpbin 实例HTTPBIN_URLhttps://your-httpbin.example.com cargo make testHTTPBIN_URL允许你将测试指向任意兼容 httpbin 的端点自建实例或公司内网镜像均可这在 CI 或离线环境下尤其有用。2.3 宏测试与 stderr 基线文件Yew 的过程宏html!、#[function_component]、#[hook]等在编译期会产生大量诊断信息。为了确保错误信息准确、易读仓库采用 trybuild 风格的测试每个预期失败的测试文件旁都配有一个.stderr文件记录编译器输出的精确错误快照。这些文件位于packages/yew-macro/tests/html_macro/html!宏相关36 个.rs 15 个.stderrpackages/yew-macro/tests/function_component_attr/#[function_component]属性宏20 个.rs 14 个.stderrpackages/yew-macro/tests/hook_attr/、hook_macro/、classes_macro/、derive_props/、props_macro/、html_lints/等目录同样遵循.rs.stderr配对模式。新增或修改宏测试时必须同步更新对应的.stderr文件否则 trybuild 会比较失败。文档特别强调编译器每次发布都可能改变错误输出格式因此这些基线文件应使用 Rust 1.56 生成部分测试依赖该版本稳定的 const generics 特性。更新/生成.stderr文件的方式是在yew-macro目录下运行cargo make test-overwrite从 packages/yew-macro/Makefile.toml 可以看出test-overwrite继承了test任务并设置环境变量TRYBUILD overwritetrybuild 检测到该变量后会用当前编译器输出覆盖.stderr基线。另外该任务固定使用toolchain 1.85.0运行可传参指定过滤条件例如cargo make test html_macro而test-lint则切换到 nightly 工具链并启用lintsfeature 运行test_html_lints。三、拼写检查typosYew 用 typos 捕获拼写错误CI 会在每个 PR 上自动运行。本地使用方式cargo install typos-cli --locked typos # 检查拼写错误 typos -w # 自动修复拼写错误误报false positive通过仓库根目录的 _typos.toml 配置排除[files] extend-exclude [examples/router/data/syllables.txt, examples/function_router/data/syllables.txt] [default.extend-words] ba baextend-exclude跳过含大量造词数据的音节约表syllables.txt避免误报extend-words将特定词加入白名单如ba。提交前运行typos是低成本但很有效的 CI 通过技巧。四、Lint 与格式化执行静态检查的命令cargo make lint根 Makefile.toml 中lint任务本质上是cargo clippy -- --denywarnings即任何 Clippy 警告都会被当作错误拒绝。此外还有lint-releasecargo clippy --all-targets --release -- --denywarnings——因为 Yew 在 debug 与 release 构建之间存在代码差异release 形态的检查同样必不可少checks-flow会一次性并行运行lint、lint-release和format。自动修复格式化问题则使用 nightly 工具链cargo nightly fmt仓库 rustfmt.toml 配置了相当多的格式化规则贡献者应尽量保持一致风格例如edition 2024、format_code_in_doc_comments true文档注释中的代码块也参与格式化、wrap_comments truecomment_width 100、group_imports StdExternalCrate与imports_granularity Module按标准库/外部/本地分组、模块粒度合并导入、use_field_init_shorthand true等。若本机 nightly 版本有差异导致cargo nightly fmt输出与 CI 不一致建议先提交代码再让 CI 给出格式化提示或直接安装与 CI 对齐的 nightly。五、基准测试Yew 使用 js-framework-benchmark 对框架整体做性能基准测试。操作方式clonebakape/js-framework-benchmark仓库按其 README 的指引运行。仓库内与基准测试配套的工具包括 tools/benchmark-corevnode 构建/拼接基准、tools/benchmark-hooks 与 tools/benchmark-structhooks 与 struct 组件两种写法的对比基准以及 tools/benchmark-ssr。CI 侧的 collect_sizes.py、make_benchmark_ssr_cmt.py、make_example_size_cmt.py 等脚本负责采集并发布基准结果。如果你对性能优化敏感可以先在本地跑benchmark-*相关 bench 再提交改动。六、设计新 API 的准则文档强调在构建新 API 时应站在使用者视角自问三个问题这个 API 会不会导致令人困惑、难以定位的错误信息这个 API 能否与其他 API 良好组合这个 API 的用法是否直观同时推荐参考以下两份指南仅作设计参考非仓库内文件The Rust API GuidelinesRust 官方 API 设计规范Elegant Library APIs in RustRust 库 API 优雅设计经验谈这些是指导性原则而非强制规范——在个别场景无法完全遵循时应优先保证可用性与一致性。结合仓库源码可见Yew 的 API 层大量使用了强类型与编译期约束例如 packages/yew/src/function_component.rs 等宏实现会在编译期校验组件函数的返回类型、Props 参数形态把错误提前到编译阶段暴露这正是错误信息清晰可定位的实践体现。七、维护官网文档Yew 官网yew.rs源码位于仓库 website 目录绝大多数内容以 Markdown/MDX 编写普通文档修改不需要改动任何 Rust 代码文档正文位于 website/docs 与 website/versioned_docs构建工具是 Docusaurus本地预览npm install npm start生产构建npm run build本地化内容位于 website/i18n含 ja、zh-Hans、zh-Hant 等语言。详细说明见 website/README.md。值得一提的验证机制是cargo make website-test即test-flow中的第三个任务tools/website-test 会把文档中的 Rust 代码块自动收集为 doctest 执行其入口 tools/website-test/src/lib.rs 通过include!(concat!(env!(OUT_DIR), /website_tests.rs))在构建期生成测试代码。若文档代码块之间存在前后依赖可以在文档末尾添加!-- COMBINE CODE BLOCKS --注释让测试装配器按 diff 标记把多个代码块拼接为一段完整程序后统一测试同时可用// ...行告知装配器丢弃之前的上下文。这意味着你写的每一个 Rust 示例都会被真实编译运行编写文档时务必保证代码块可独立编译。八、贡献流程速查表场景推荐命令查看全部可用任务cargo make --list-all-steps运行全量测试原生 文档 网站代码块cargo make test-flow浏览器wasm测试cargo make test自动下载 Geckodriver需firefox在 PATH自定义 httpbin 地址跑 fetch 测试HTTPBIN_URLurl cargo make test更新宏错误基线.stderr在packages/yew-macro下运行cargo make test-overwrite拼写检查 / 自动修复typos/typos -wClippy 格式化检查cargo make lint、cargo make checks-flow自动格式化cargo nightly fmt框架级性能基准clonebakape/js-framework-benchmark后按其 README 操作整体提交流程建议为rustup target add wasm32-unknown-unknown→ 安装 cargo-make → 运行cargo make test-flow与cargo make checks-flow→typos检查拼写 → 提交 PR。这样即可覆盖 Yew CI 的核心检查项测试、文档、Clippy、Rustfmt、拼写让评审与合并流程更加顺畅。【免费下载链接】yewRust / Wasm framework for creating reliable and efficient web applications项目地址: https://gitcode.com/gh_mirrors/ye/yew创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
