reactlynx-best-practices

ReactLynx 最佳实践

编写、审查或重构 ReactLynx 代码时，请使用此技能。ReactLynx 遵循 React 编程模型，但 Lynx 的双线程运行时会改变我们对副作用、生命周期时机、事件处理程序和主线程脚本的理解方式。

此技能有意不要求在运行时使用 @ast-grep/napi 或任何原生解析器。随附的扫描器是用于检测常见问题的轻量级启发式工具。Agent 仍必须阅读代码并遵循 rules/*.md 中的规则文档。

适用场景

• 编写新的 ReactLynx 组件或应用代码。
• 发布或审查可复用的 ReactLynx 组件库。
• 检查 ReactLynx 代码中与线程边界、生命周期、事件、lynx.__globalProps、代码拆分或性能有关的问题。
• 重构调用 lynx.getJSModule、NativeModules、runOnMainThread、runOnBackground、lazy、Suspense 或 useLayoutEffect 的代码。
• 调查包含 ReactLynx 渲染、diff、commit、patch 或 setState 事件的性能跟踪记录。

官方参考资料

• ReactLynx 思维方式：https://lynxjs.org/next/react/thinking-in-reactlynx.html
• 渲染流程与生命周期：https://lynxjs.org/next/react/lifecycle.html
• 主线程脚本：https://lynxjs.org/next/react/main-thread-script.html
• 代码拆分：https://lynxjs.org/next/react/code-splitting.html
• 性能分析：https://lynxjs.org/next/react/performance/profiling
• lynx.__globalProps：https://lynxjs.org/next/api/lynx-api/lynx/lynx-global-props.html
• globalPropsMode：https://lynxjs.org/next/zh/api/rspeedy/react-rsbuild-plugin.pluginreactlynxoptions.globalpropsmode.html
• Rslib React 与保留 JSX：https://rslib.rs/guide/solution/react
• TypeScript JSX 发射模式：https://www.typescriptlang.org/docs/handbook/jsx
• ReactLynx 0.121.0 React.createElement 支持：https://github.com/lynx-family/lynx-stack/blob/main/packages/react/CHANGELOG.md#01210

工作流

1. 任务分类

使用以下一种模式：

模式	使用场景
writing	用户要求编写 ReactLynx 代码或提供最佳实践指导
review	用户要求检查、审计、解释或验证现有代码
refactor	用户要求修复或重写现有代码

如果未明确指定模式，请根据用户的措辞推断。尚未检查代码时，优先使用 review，再考虑 refactor。

2. 检查代码

对于仓库相关任务，请先搜索，再编辑：

rg "lynx.getJSModule|NativeModules|useLayoutEffect|main-thread:|runOnMainThread|runOnBackground|lazy\\(|Suspense|background only|globalPropsMode|__globalProps|jsx|exports" <target>

进行更改前，请阅读相关组件、自定义 Hook、转发事件处理程序的自定义组件、Rspeedy 配置，以及与性能有关的代码。

3. 源代码可用时运行辅助扫描器

扫描器可检测常见的仅限后台问题和生命周期问题。它不是完整解析器，不能代替代码审查。

node -e "
import fs from 'fs';
import { ReactLynxWorkflow, formatScanReport } from '<path_to_skill>/scripts/index.mjs';

const input = '<sourceCodeOrFilePath>';
const sourceCode = fs.existsSync(input) ? fs.readFileSync(input, 'utf-8') : input;
const workflow = new ReactLynxWorkflow('review');
const summary = workflow.reviewCode(sourceCode);
console.log(formatScanReport(summary));
"

4. 应用规则检查清单

始终将扫描器输出与以下人工检查结合起来：

• 双线程边界：渲染代码可能在主线程运行；副作用和原生 API 必须仅在后台运行。
• 仅后台传播：仅由仅后台代码调用的代码也属于仅后台代码，但自定义 prop 和自定义 hook 边界通常需要显式添加 'background only' 指令。
• 生命周期：不支持 useLayoutEffect；后台副作用使用 useEffect，布局读取则使用主线程布局事件或 refs。
• 事件：常规 bind*/catch* 处理程序在后台线程运行；main-thread:* 处理程序需要 'main thread'，且限制更严格。
• MTS：捕获的值必须可序列化为 JSON，捕获的变量不能修改，不支持嵌套的主线程函数，跨线程调用必须使用 runOnMainThread() 或 runOnBackground()。
• 共享模块：仅在共享代码时使用 with { runtime: 'shared' } 导入辅助函数，而非用于共享状态。
• 组件库：发布类型擦除后的 dist ESM，并在包含 JSX 的 .jsx 文件中保留编写时的 JSX，同时提供匹配的声明；导出构建实际生成的 .js 或 .jsx 入口。仅通过显式的 source 字段或受支持的条件导出 TS/TSX 源码。检查 Rslib、TypeScript、Babel 和 SWC 的输出，确认 JSX 被转换为 classic、automatic 还是自定义工厂模式。根据 @lynx-js/react 的 peer 范围判断有意使用的 React.createElement，不要假设每次调用都不兼容。
• lynx.__globalProps：由宿主注入、跨页面/全局的数据，通过 updateGlobalProps 更新。
• globalPropsMode：'reactive' 会触发根节点 forceUpdate；'event' 则需要通过 useGlobalPropsChanged 显式更新。迁移到 'event' 时，扫描对 lynx.__globalProps 的直接读取，因为根节点 forceUpdate 不再适用。
• 代码拆分：惰性组件需要默认导出、Suspense、CSS 作用域感知，以及重要边界的错误处理。
• 性能分析：优化之前，使用跟踪事件和易读的 displayName 来定位耗时的渲染/差异比较/更新路径。

5. 安全地重构

对于重构模式：

1. 先报告当前发现的问题。
2. 说明哪些修复可机械完成，哪些需要人工进行设计判断。
3. 仅应用范围明确的更改。
4. 编辑后重新运行辅助扫描器或软件包测试。

仅将自动修复作为建议。当前自动修复针对 detect-background-only 诊断设计，应用前应进行审核。

node -e "
import fs from 'fs';
import { ReactLynxWorkflow, formatFixPlan } from '<path_to_skill>/scripts/index.mjs';

const input = '<sourceCodeOrFilePath>';
const sourceCode = fs.existsSync(input) ? fs.readFileSync(input, 'utf-8') : input;
const workflow = new ReactLynxWorkflow('refactor');
workflow.reviewCode(sourceCode);
const plan = workflow.generateFixPlan();

if (plan) {
  console.log(formatFixPlan(plan));
}
"

规则

规则	影响	用途
detect-background-only	严重	lynx.getJSModule、NativeModules、'background only'、自定义事件/hook 边界
avoid-use-layout-effect	中	生命周期和布局读取
proper-event-handlers	中	bindtap、catchtap、传播、dataset、自定义 prop 处理程序
main-thread-scripts-guide	中	main-thread:*、useMainThreadRef、跨线程调用、共享模块
component-library-packaging	高	ReactLynx 组件库导出、类型擦除后的 ESM、保留的 JSX、Rslib、tsc
global-props-mode	中	globalPropsMode 配置、对 lynx.__globalProps 的直接读取、useGlobalPropsChanged 迁移
code-splitting	中	lazy、Suspense、独立的惰性包、CSS 包作用域
performance-profiling	中	ReactLynx 跟踪事件、flow ID、displayName
hoist-static-jsx	低	静态 JSX 和渲染开销

API 参考

function runSkill(source: string): Diagnostic[];
function runSkillWithFixes(source: string): DiagnosticWithFix[];
function analyzeBackgroundOnlyUsage(source: string): Diagnostic[];
function analyzeLifecycleUsage(source: string): Diagnostic[];
function generateFixes(source: string, diagnostic: Diagnostic): Fix[];
function applyFix(source: string, fix: Fix): string;
function applyFixes(source: string, fixes: Fix[]): string;
function formatScanReport(summary: ScanSummary): string;
function formatFixPlan(plan: FixPlan): string;

class ReactLynxWorkflow {
  constructor(mode: WorkflowMode);
  reviewCode(source: string): ScanSummary;
  generateFixPlan(): FixPlan | null;
  applyAutoFixes(source: string): { fixed: string; appliedFixes: Fix[] };
}