Mastra React 最佳实践提取复杂派生逻辑让渲染前的数据推导保持可读、可测、可评审【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra导读本指南源自 Mastra 工程团队的 React 最佳实践规则集react-best-practices共 26 条规则、9 大类别聚焦其中的structure-complex-derived-logic规则。该规则针对 React 组件渲染前常见的运算符汤operator soup问题当大段布尔条件、嵌套三元、局部let赋值、||/??/?./展开运算符与默认回退混杂在一起推导最终渲染值时业务规则被淹没、评审困难、声明式组合退化为逐步状态跟踪。读完本文你将掌握如何把这些派生逻辑提取为带守卫子句guard clause和显式 return 的命名谓词与纯辅助函数并了解该规则在 Hook 选项对象、查询/请求构建器、配置映射与 reducer 中的同等适用性。规则概述什么是复杂派生逻辑该规则在 结构类规则目录 中归类为 Component Structure组件结构类别影响等级为MEDIUM-HIGH可维护性其 impactDescription 明确指出密集的派生逻辑会把业务规则藏在运算符汤里让评审变难并把声明式组合变成逐步的状态跟踪。核心判定标准如下当一个组件推导最终的渲染值、导航模型nav model、可见性标志、激活状态或路由目标时保持推导过程可读。如果短短几行就同时混杂了大型布尔条件、嵌套三元、局部赋值、||、??、可选链、展开运算符和默认回退就应该把这段逻辑移动到命名谓词或小型纯辅助函数中用守卫子句与显式 return 组织。需要特别强调的是这条规则并非只针对渲染层。原文明确指出This is not a render-only rule. Hook option objects, query and request builders, config maps, and reducers derive values too, and the same operator soup hurts them the same way.即 Hook 选项对象、查询/请求构建器、配置映射、reducer 同样会推导值同样的运算符汤问题以相同方式损害它们。两个伴随原则原则一把渲染准备阶段的let默认视为代码异味。优先使用命名辅助函数通过守卫子句和显式 return 返回最终值。let应当保留给真正的顺序算法、计数器、循环、资源句柄或每一步都刻意依赖上一步的场景当局部变量代表最终推导出的 UI/数据结构时要避免使用let——那里的赋值会让最终值难以预期。原则二不要只修复一个异味而留下另一个。例如把被重新赋值的let提取成const base condition ? a : b如果这个三元仍在选择结构化数据那依然是有问题的。清理后的版本应该同时移除运算符汤、嵌套控制流和赋值。实战拆解五类典型模式与其修正原规则文件structure-complex-derived-logic.md给出了五类最典型的坏味道每一类都配有 Incorrect / Correct 对照。下面逐一拆解并补充实现层面的深层原因。1. 大型布尔条件Large Conditions反例组件内联一个由两个大括号分支组成的||条件直接计算isProjectsHeaderActivefunction Sidebar({ orgId, projectId, isSettingsActive, product, pathname }: SidebarProps) { const isProjectsHeaderActive (product studio !projectId !isSettingsActive pathname /orgs/${orgId}) || (product gateway !projectId !isSettingsActive); return Nav activeProjects{isProjectsHeaderActive} /; }正例把规则顺序放进带守卫子句的命名函数shouldHighlightProjects调用点在 JSX 之前只负责给派生布尔值命名function shouldHighlightProjects({ product, projectId, isSettingsActive, pathname, projectsHref, }: { product: Product; projectId?: string; isSettingsActive: boolean; pathname: string; projectsHref: string; }) { if (projectId || isSettingsActive) return false; if (product gateway) return true; return pathname projectsHref; } function Sidebar({ orgId, projectId, isSettingsActive, product, pathname }: SidebarProps) { const projectsHref /orgs/${orgId}; const isProjectsHeaderActive shouldHighlightProjects({ product, projectId, isSettingsActive, pathname, projectsHref, }); return Nav activeProjects{isProjectsHeaderActive} /; }要点调用点先命名派生布尔值再进入 JSX辅助函数拥有规则排序的所有权。原先需要脑内求值的复合条件现在每个if都是一行可命名的业务规则评审者从上到下读一遍守卫即可。2. 嵌套结构三元Nested Structural Ternaries反例三元嵌套选择结构化数据——sections根据三个状态取不同的 section 集合function Sidebar({ orgId, projectId, isSettingsActive }: SidebarProps) { const resolvedOrgId orgId ?? fallbackOrgId; const sections isSettingsActive ? getSettingsSections(resolvedOrgId) : projectId ? getProjectSections(resolvedOrgId, projectId) : getOrgSections(resolvedOrgId); return Nav sections{sections} /; }正例每个分支用ifreturn 占据一行可命名的位置function getBaseSections({ orgId, projectId, isSettingsActive, }: { orgId: string; projectId?: string; isSettingsActive: boolean; }) { if (isSettingsActive) return getSettingsSections(orgId); if (projectId) return getProjectSections(orgId, projectId); return getOrgSections(orgId); } function Sidebar({ orgId, projectId, isSettingsActive }: SidebarProps) { const resolvedOrgId orgId ?? fallbackOrgId; const sections getBaseSections({ orgId: resolvedOrgId, projectId, isSettingsActive, }); return Nav sections{sections} /; }原规则特别提醒当嵌套三元选择的是结构化数据、路由或组件时代价尤其高昂——因为此时三元不只是取二选一而是在承担控制流职责。3. 做工作的三元Ternaries That Do Work这是最微妙的一类。规则给出判定标准三元表达式是在两个值之间做选择。一旦某个分支长出身体——块箭头、IIFE、多行对象——或者一旦它的条件测试了一个形状而分支又必须用as重新断言这个形状它就不再是选择而是开始计算了。两者的修复方式相同一个带守卫子句的命名函数。反例buildPreview中三元条件测了Array.isArray(value)/typeof value object分支里却又用as断言value.messages——条件刚验证过的形状分支还得再断言一次export function buildPreview(input: unknown) { const value parseIfJson(input); const messages Array.isArray(value) ? value : value typeof value object Array.isArray((value as { messages?: unknown }).messages) ? (value as { messages: unknown[] }).messages : undefined; if (!messages) return undefined; return previewFrom(messages); }正例先用isRecord谓词把unknown收窄为可读属性的Recordstring, unknown再用toMessages以守卫子句逐层校验function isRecord(value: unknown): value is Recordstring, unknown { return typeof value object value ! null; } function toMessages(value: unknown): unknown[] | undefined { if (Array.isArray(value)) return value; if (!isRecord(value)) return undefined; if (!Array.isArray(value.messages)) return undefined; return value.messages; } export function buildPreview(input: unknown) { const messages toMessages(parseIfJson(input)); if (!messages) return undefined; return previewFrom(messages); }为什么这里必须补谓词而不是删掉as规则原文解释了这段 TypeScript 收窄的深层原因值得原样理解typeof value object只能把unknown收窄为object | null因为typeof null object前面的value 只是剥掉了null剩下的是object——一个没有任何属性的类型读取.messages依然是编译错误断言是唯一的出路更关键的是类型收窄跟踪的是引用references而非表达式写在(value as X).messages上的条件对分支里的value什么也证明不了所以分支必须再断言一次谓词isRecord才是同时移除两次断言的正确手段。原规则将此总结为三元分支和其他控制流一样收窄——条件从未强制产生断言缺失的是谓词。提取Extraction修复的是另一半——密度。这类形状通常需要两处修复所以当你在密集条件中遇到as簇时记得同时寻找缺失的谓词。这正是本规则与 types-no-type-assertions.mdHIGH 影响等级、禁止as断言的交叉点后者规定生产与测试代码一律不得使用as仅as const允许而条件内部聚集的 casts 通常意味着缺失谓词正是两者的共同修复路径。同时要注意提取不等于包装。一行内二选一的三元完全没问题加辅助函数不会减少调用点的工作反而徒增一个名字、一层间接和常常多一个类型参数。4. 回退与运算符汤Fallback and Operator Soup反例一行内混用??、展开、内联对象字面量、?:、||——回退行为、链接选择、默认对象全部挤在渲染准备阶段function Sidebar({ orgId, projectId, sections }: SidebarProps) { const [mainSection, ...restSections] sections ?? []; const nextSections [ { ...(mainSection ?? { key: main, links: [] }), links: [projectId ? getBackLink(orgId) : getProjectsLink(orgId), ...(mainSection?.links || [])], }, ...restSections, ]; return Nav sections{nextSections} /; }正例把链接选择getProjectsEntryLink与向首 section 前置链接prependLinkToFirstSection分别提取为命名函数每个函数只做一件事function getProjectsEntryLink({ orgId, projectId }: { orgId: string; projectId?: string }) { if (projectId) return getBackLink(orgId); return getProjectsLink(orgId); } function prependLinkToFirstSection(sections: NavSection[], link: NavLink) { const [mainSection, ...restSections] sections; if (!mainSection) { return [{ key: main, links: [link] }]; } return [ { ...mainSection, links: [link, ...mainSection.links], }, ...restSections, ]; } function Sidebar({ orgId, projectId, sections }: SidebarProps) { const nextSections prependLinkToFirstSection(sections, getProjectsEntryLink({ orgId, projectId })); return Nav sections{nextSections} /; }规则结论把回退行为和链接选择移入命名辅助函数渲染准备阶段不应该要求读者同时解码? :、||、??、?.、展开运算符和默认对象。5. 可变派生组合Mutable Derived Composition反例let sections ...之后跟着条件赋值。读者必须跟踪一个被重新赋值的局部变量并自行判断前面的回退行为是否改变了后面的分支function Sidebar({ orgId, projectId, isSettingsActive, product }: SidebarProps) { let sections getBaseSections({ orgId: orgId ?? fallbackOrgId, projectId, isSettingsActive, }); if (orgId product studio !isSettingsActive) { sections prependLinkToFirstSection(sections, getProjectsEntryLink({ orgId, projectId })); } return Nav sections{sections} /; }正例把整段组合逻辑收进getSidebarSections用守卫子句把不需要前置链接的各种情况提前返回最后只保留一个真正的组合分支function getSidebarSections({ orgId, projectId, product, isSettingsActive, }: { orgId?: string; projectId?: string; product: Product; isSettingsActive: boolean; }) { const baseSections getBaseSections({ orgId: orgId ?? fallbackOrgId, projectId, isSettingsActive, }); if (!orgId) return baseSections; if (product ! studio) return baseSections; if (isSettingsActive) return baseSections; return prependLinkToFirstSection(baseSections, getProjectsEntryLink({ orgId, projectId })); } function Sidebar({ orgId, projectId, isSettingsActive, product }: SidebarProps) { const sections getSidebarSections({ orgId, projectId, product, isSettingsActive, }); return Nav sections{sections} /; }调用点直接拿到最终值读者无需追踪被重赋值的局部变量。这与 structure-derive-dont-duplicate.md 的精神一致能被推导的值不要在调用点重复维护。使用边界与放置策略原规则给出了两条重要的边界说明辅助函数默认保持文件局部file-local。除非多个领域确实共享同一个概念否则不要把这套提取变成通用工具层。目的始终是给条件或推导命名、去掉无用的复杂度而不是创造一个泛化 utility 层。let有它的合法用途真正的顺序算法、计数器、循环、资源句柄或每一步刻意依赖前一步的场景。规则反对的是把let用于最终派生出的 UI/数据结构。在调用点层面派生值应以命名局部变量的形式出现在 JSX 之前如const isProjectsHeaderActive ...而不是写成propName{complexHelper({ ... })}的内联调用——后者的名字只存在于 prop 名中无法在 JSX 中被复查。与相邻规则的关系本规则不是孤立条款它与 react-best-practices 规则集中多个条目互补相邻规则关系types-no-type-assertions密集条件中的as簇意味着缺失谓词提取派生逻辑与补谓词常常需要一起完成structure-derive-dont-duplicate能从已有 prop 推导的值不要作为独立参数传入避免双源真相structure-early-return-render-branches互斥视图用守卫子句分支但布局外层只保留一份本规则处理推导值、它处理分支渲染structure-narrow-apis提取后辅助函数应保持 API 窄小不要把一堆值塞进一个参数对象假装收窄types-no-null辅助函数返回缺失时用undefined而非null保持内部类型无 null例如 structure-early-return-render-branches.md 处理的是渲染分支选择而本规则处理的是分支之前的值推导——前者关注Panel外层只出现一次后者关注sections/isActive等派生值如何被算出来。评审异味清单Review Smells规则文件末尾给出了可直接用于 Code Review 的完整异味清单照此检查你的 diff内联在 JSX 或渲染准备阶段的超大/||条件选择结构化数据的嵌套三元跨多行、或包着块箭头 / IIFE / 多行对象的三元分支分支里的as断言其形状正是条件刚刚测试过的同一需求被编码两次一次在条件里一次在它守护的值里let result ...后面跟着if (...) result ...以propName{complexHelper({ ... })}传派生 prop而不是先命名局部变量四行代码里混用? :、||、??、?.、展开运算符和默认对象用注释解释赋值顺序评审评论中出现 feels intense、can we simplify this?、could we refactor those lines into an understandable function?、why do we need let? 之类的措辞派生出的数组/对象随后被渲染或作为 props 传递。小结在 Mastra 工程实践中提取复杂派生逻辑是一条中等偏高影响的可维护性规则它要求组件、Hook、构建器与 reducer 在推导最终值时用命名谓词 守卫子句 显式 return取代运算符汤与可变赋值。它的价值不只是代码好看——守卫子句让每条业务规则占一行、可命名、可单测移除as断言让类型检查器重新接管形状校验消除let让最终值可以被直接预期。将本文中的五类正反对照与异味清单用于日常编写与评审即可把渲染前的数据推导从逐步状态跟踪恢复为声明式组合。进一步查阅规则全文见 structure-complex-derived-logic.md规则目录见 react-best-practices-reference.md技能总览见 SKILL.md。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考