Dify 前端组件架构守则从 React 所有权、边界到 Effects 的评审规则解析【免费下载链接】difyBuild Agentic workflows, RAG pipelines, with rich AI model and tool support on one collaborative workspace. Deploy on cloud, VPC, or self-hosted, so teams move from prototype to production without rebuilding the stack.项目地址: https://gitcode.com/GitHub_Trending/di/dify本篇基于 Dify 仓库内置的frontend-code-review技能规则包系统讲解其中专门约束 React 组件结构、所有权ownership、props、Effects 与状态建模的 component-architecture.md 规则文档。读完后你将掌握在 Dify 这类大型 Next.js TanStack Query 应用中如何判断状态该放在哪一层、组件该拆到哪里、Effect 何时才允许存在并能按仓库既定的评审口径P0–P3 严重级见 SKILL.md产出可复现、可验证的前端架构评审结论。规则包定位评审阶段的路由入口该文档并非面向普通开发者的泛泛指南而是 Dify 为 AI Agent 与人类评审者设计的代码评审规则包rule pack。在 SKILL.md 中前端评审被明确限定在web/与packages/dify-ui/两个目录范围内并按 diff 特征路由到 8 个子规则包组件所有权、props、状态、Effects、导航或模块边界相关的问题统一路由到references/component-architecture.md与 accessibility-ui.md、dify-ui.md、data-query-contracts.md、performance.md 等并列。评审方法论遵循 Evidence First证据优先从请求的文件或当前 diff 确定评审范围阅读被改动的行、其行为属主behavior owner以及最近的AGENTS.md作用域文档仅当公共消费者、生成契约、基础组件 API 或运行时配置影响正确性时才继续追踪它们只报告绑定到可观察故障、被违反的契约、安全边界或被证明的维护风险的发现。评审结论按四级严重度排序输出P0安全/隐私泄露、数据丢失、生产崩溃、关键流程不可访问、P1用户可见回归、非法 API 或鉴权契约、hydration 失败、主交互损坏、P2具体维护性/性能/测试/可访问性缺陷、P3轻微可操作清理项。这套输出规范意味着组件架构问题若不能落到具体文件行号与失败路径就不应进入报告。所有权Ownership状态与行为的最低必要层级规则的第一章回答一个核心问题状态、查询、mutation、事件处理器应该放在哪一层评审口径是flag标记为问题以下五种模式状态/查询/mutation/处理器被提升hoist到了真正使用它们的最低组件之上——即父层代管了本应由子层拥有的东西父组件拥有行/条目级动作row/item actions但这些动作并不在协调一个工作流workflowprops 穿透prop drilling穿过多个纯转发层仅为了把一个值或回调递给最底层的渲染者页面/tab 级区块组件变成数据属主却并不需要共享快照也不共享 loading/error/empty 的 UI功能代码仅因为只出现了一次或以后可能被复用就被提升到 shared 层。同时规则给出一条明确的反直觉豁免兄弟组件各自重复发起相同的 TanStack Query 调用是可接受的只要每个组件独立消费该数据缓存去重本身不构成把数据提升到公共父层的理由。这条规则与 Dify 仓库的实际技术栈直接对应。Dify Web 端在 Next.js App Router 之上大量使用 TanStack Query 管理数据例如 layout-main.tsx/app/(appDetailLayout)/[appId]/layout-main.tsx)、view.tsx/app/(appDetailLayout)/[appId]/overview/view.tsx) 等页面级组件均直接引入tanstack/react-query的 hooksweb/features/下的新特性目录如agent-v2、skills中useQuery/useMutation也分散在各叶子组件内而非集中到页面容器。从源码结构看仓库的既有做法正是谁消费、谁查询与本文档的 ownership 条款互为印证——评审时若发现数据被提升到并不共享加载态的父层即可依据本规则给出 P2 级维护性发现。组件边界Component Boundaries什么时候该拆、什么时候不该包第二章给出六条应被标记的边界问题超过 300 行的 React 组件文件且该文件混合了多个可拆分为聚焦的**同置colocated**组件、hooks 或工具函数的职责。注意规则的两个限定词行数只是触发器前提还必须存在可拆分的多职责混合浅层包装组件shallow wrapper——仅仅重命名 props 或隐藏真正的基础组件primitive多余的 DOM 包裹层它不提供布局、语义、可访问性、状态属主或库集成中的任何一项价值Dialog/dropdown/popover 的隐藏面hidden surface遮挡了父级流程却本应被提取为小的本地组件业务表单、菜单主体或一次性 helper 被移离其属主组件且既无复用也无语义价值。结论性建议只有一句优先按真实的数据与状态需求拆分成同置组件Prefer colocated components split by actual data and state needs。这条规则在 Dify 中有明确的落点约束Web 端对 Dify UI 基础组件的使用受 web/AGENTS.md 强制要求——优先使用langgenius/dify-ui/*子路径导出的 primitive、数据属性和设计令牌且不要添加会隐藏这些契约的 Web 层包装器Button、IconButton、Overlay 等均有此禁令。也就是说浅层 wrapper不仅违反组件架构规则包还会直接违反 Dify UI 的包级契约评审时属于双重命中。packages/dify-ui/README.md 中列出的 primitive 清单./dialog、./dropdown-menu、./popover、./drawer等 overlay 类别正是规则第 4 条隐藏面应提取为小本地组件所指的触发场景overlay 的开启状态与内容往往比宿主按钮复杂得多留在父组件里会让父级流程被弹窗状态污染。不良组件设计模式交互契约与泛化陷阱第三章是六章中条目最多的一章覆盖了 9 种应标记的设计模式可以归纳为三组交互契约破坏组对既有导航、侧边栏、下拉、webapp 列表、应用切换 UI 的重构没有保留行为敏感交互——展开/收起箭头、hover 持久化、置顶/删除控件、路由、键盘/焦点处理、开启状态的属主一个组件混合了数据获取、mutation 副作用、弹窗状态、表单校验、布局与行渲染且没有清晰属主。假泛化组带有大量 boolean props 的通用组件实际编码的是某一个功能的工作流用开关注入而非真实抽象shared 组件导入了功能特定的文案、路由或 API 契约——方向性错误依赖应指向更底层而非功能层功能组件接收预渲染的 fragmentsrender props 滥用仅仅是为了避免把属主放对位置包装组件改变了被包裹 primitive 的可访问语义——与 accessibility-ui.md 规则包交叠属于 P1/P2 级别的复合问题。数据流组子组件对同一概念同时接收原始服务端数据和派生的标志位例如同时传row.status和row.isDisabled产生两个事实来源组件暴露受控 propscontrolled props却为同一值保留了一个竞争的私有 state——受控/非受控混用是典型的 stale-state 缺陷源组件无法在调用方不做预处理的情况下渲染空态、加载态或缺失的可选 API 字段——健壮性契约缺失。该章还给出两条处置原则当既有组件已拥有交互逻辑时优先复用或扩展而非重写若重构不可避免必须保留旧的交互契约并为变更行为添加或更新聚焦测试测试要求路由到 testing.md。在 Dify 仓库中这类行为敏感交互正是评审高风险区web/app/(commonLayout)/下的应用列表、导航、切换类 UI 以及web/features/agent-v2/agent-detail/这类含多 tab、多 overlay 的详情页其展开/收起、hover 持久化、焦点管理行为一旦被重构破坏就会落到 P1用户可见回归而非 P3。规则要求先找属主、再谈重构本质上是在保护这些交互契约的可追溯性。Props 与类型反对无契约变更的形式统一第四章针对 props 设计给出 5 条标记规则仅为风格统一而重写声明或导出但没有改变所拥有行为或契约的变更对琐碎一次性 props起命名的Props类型内联类型更清晰时props 按 UI 实现命名如showArrow而非按领域/API 角色命名API 数据过早转换、或转换后丢失可追溯性generic name 让人无法回溯到后端字段调用方重复了最低渲染组件已经处理的 fallback 检查——防御逻辑下沉后上层应信任属主。本章最重要的一条反噪音条款是不要仅凭语法形式标记FC、React.FC、函数声明、箭头函数、命名导出或默认导出只有当所选形式造成具体的类型、生命周期、导出、框架或强制包契约缺陷时才允许报告。这条显式压制了评审中最高频的品味型噪音与 SKILL 层只报告绑定到可观察故障的发现的原则一致。Effects默认不存在除非同步具名外部系统第五章对useEffect采取了近乎有罪推定的立场。以下行为都应被标记在 effect 中转换 props/state 用于渲染这属于渲染期派生不是 effect把一个 state 值拷贝进另一个表示同一概念的 state事实来源重复stale-state 之源在 effect 中处理本应属于事件处理器的用户动作在 props 或可见性变化时重置本地状态——而派生、稳定的语义身份semantic identity或预期的挂载属主已经表达了该生命周期在 effect 中获取本应属于框架 API 或 TanStack Query 的数据。而一个 effect 若要合法存在必须同步一个具名外部系统规则列举了合法清单浏览器 API、订阅subscription、定时器timer、可见性触发的分析上报analytics-on-visibility、非 React 组件、命令式 DOM 集成。清单之外的 effect 一律视为问题。这条规则与 Dify 的数据层约定高度自洽web/AGENTS.md 要求新的后端调用使用/service/client生成的consoleQuery/consoleClientAPI禁止手写 REST helper——即所有服务端数据获取被集中到生成的 Query 层effect 中 fetch 数据因此失去了合法性依据评审时可直接引用两个证据点。状态建模生命周期先于存储机制第六章是全文概念密度最高的部分。应标记的状态反模式包括存储派生布尔值、disabled 标志、默认 tab、加载文案——这些可以从当前 query/feature 状态直接计算把会话级状态放在更长寿的可见性协调器visibility coordinator里再通过 open-state Effect 或生成的 key 清理而 primitive 的挂载内容生命周期本来就已匹配预期状态寿命把一个 DOM 字段镜像成相互竞争的 prop、default 和 React state 三个来源而编辑并不需要这些来源同步用本地 state 伪造服务端数据或生成的契约字段把本应是**实时应用状态live app state**的 UI 状态持久化到 localStorage在真实 API 确认前把功能本地的 mock 外壳接到不相干的既有 API上。随后是三段关键的方法论陈述值得逐条展开1. 先评审状态生命周期再评审存储机制。对隐藏面hidden surface即 dialog/drawer/popover 一类要区分可见性协调器与挂载内容两个角色私有于某次挂载会话的状态属主就应该是挂载内容本身只有当草稿必须在该内容属主卸载后依然存活、或另一个属主在协调它时才提升promote状态。稳定的语义身份 key 可以在所表示的身份变化时创建新快照但生成的 key 不是例行的 reset 命令——key{Math.random()}式重置正是上文第二条标记项。2. 优先渲染期派生。真正的本地 state 只留给用户选择、瞬态输入、受控弹窗、以及没有服务端来源的功能 UI 状态。只提交submit-only的 DOM 字段可以保持非受控只有当 React 必须拥有当前值来驱动渲染或协同时才使用本地受控 state。观察变更事件或追踪dirty 与否这类派生事实并不要求镜像字段值——这直接呼应第五章拷贝同一概念到第二个 state的禁令。同时明确不能仅因某处使用了受控 state 就提出发现必须有具体的竞争来源、stale-state 或属主缺陷作支撑。3. 落点在 Dify 的形态上。从web/context/目录结构14 个 context/provider 文件看Dify Web 端存在大量页面级 provider本章的可见性协调器 vs 挂载内容正是针对这类 provider 持有过多会话状态的场景。评审时若发现某 modal 的草稿状态挂在页面级 provider 且靠 effect 清理而弹窗内容本应自管即可按本章口径给出属主错误发现。导航Link 优先URL 承载可分享状态第七章给出三条标记规则对普通链接使用命令式路由跳转router.push式的普通导航用button 语义承担导航应为Link/a导航状态藏在组件 state 里而可分享的 filter、tab、分页本质上需要 URL 状态。正向规则是普通导航用Link仅在mutation 成功后的跳转、守卫式重定向、命令流command flow、表单提交副作用四类场景才使用 router API。这与 Dify 的 App Router 结构web/app/下大量(commonLayout)、(shareLayout)路由组页面相匹配应用详情页、webapp 分享页等大量场景涉及深链与分享把 tab/filter 塞进组件 state 会直接丢失可分享性属于可验证的用户可见缺陷P1 级别。小结把六章规则压缩为评审检查表章节一句话核心典型 Dify 证据锚点Ownership数据与行为放在真正使用它的最低组件查询重复不算提升理由web/features/**中useQuery散布于叶子组件Boundaries300 行只是触发器可拆分职责混合才是缺陷拒绝浅层 wrapperweb/AGENTS.md 禁止 Web 层 wrapper 隐藏 Dify UI 契约Bad Patterns重构必须保留交互契约警惕 boolean props 假泛化与双事实来源导航/侧边栏/webapp 列表等既有交互组件Props Types按领域角色命名不为风格统一重写导出语法形式不构成发现生成客户端/service/client的字段可追溯性Effects默认不存在合法者必须同步具名外部系统数据获取集中于生成的 Query 层effect fetch 无合法依据State Modeling生命周期先于存储机制协调器不代管挂载内容私有状态优先渲染期派生web/context/页面级 provider 的状态归属Navigation普通导航用Link可分享状态进 URLApp Router 深链页面结构需要强调的是该规则包的使用前提与边界它服务于显式的评审/审计请求作用于web/与packages/dify-ui/范围发现必须绑定到文件行号、失败契约或复现路径严重度遵循 P0–P3 分级若评审无任何发现输出就是 No issues found. 加上实质性验证缺口说明——不添加赞扬段落、不猜测风险。换言之这份文档的价值不在于给出更多规则而在于精确界定了什么算问题、什么只是品味让组件架构评审在人与 Agent 之间具备可复现的判定基线。【免费下载链接】difyBuild Agentic workflows, RAG pipelines, with rich AI model and tool support on one collaborative workspace. Deploy on cloud, VPC, or self-hosted, so teams move from prototype to production without rebuilding the stack.项目地址: https://gitcode.com/GitHub_Trending/di/dify创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Dify 前端组件架构守则：从 React 所有权、边界到 Effects 的评审规则解析
Dify 前端组件架构守则从 React 所有权、边界到 Effects 的评审规则解析【免费下载链接】difyBuild Agentic workflows, RAG pipelines, with rich AI model and tool support on one collaborative workspace. Deploy on cloud, VPC, or self-hosted, so teams move from prototype to production without rebuilding the stack.项目地址: https://gitcode.com/GitHub_Trending/di/dify本篇基于 Dify 仓库内置的frontend-code-review技能规则包系统讲解其中专门约束 React 组件结构、所有权ownership、props、Effects 与状态建模的 component-architecture.md 规则文档。读完后你将掌握在 Dify 这类大型 Next.js TanStack Query 应用中如何判断状态该放在哪一层、组件该拆到哪里、Effect 何时才允许存在并能按仓库既定的评审口径P0–P3 严重级见 SKILL.md产出可复现、可验证的前端架构评审结论。规则包定位评审阶段的路由入口该文档并非面向普通开发者的泛泛指南而是 Dify 为 AI Agent 与人类评审者设计的代码评审规则包rule pack。在 SKILL.md 中前端评审被明确限定在web/与packages/dify-ui/两个目录范围内并按 diff 特征路由到 8 个子规则包组件所有权、props、状态、Effects、导航或模块边界相关的问题统一路由到references/component-architecture.md与 accessibility-ui.md、dify-ui.md、data-query-contracts.md、performance.md 等并列。评审方法论遵循 Evidence First证据优先从请求的文件或当前 diff 确定评审范围阅读被改动的行、其行为属主behavior owner以及最近的AGENTS.md作用域文档仅当公共消费者、生成契约、基础组件 API 或运行时配置影响正确性时才继续追踪它们只报告绑定到可观察故障、被违反的契约、安全边界或被证明的维护风险的发现。评审结论按四级严重度排序输出P0安全/隐私泄露、数据丢失、生产崩溃、关键流程不可访问、P1用户可见回归、非法 API 或鉴权契约、hydration 失败、主交互损坏、P2具体维护性/性能/测试/可访问性缺陷、P3轻微可操作清理项。这套输出规范意味着组件架构问题若不能落到具体文件行号与失败路径就不应进入报告。所有权Ownership状态与行为的最低必要层级规则的第一章回答一个核心问题状态、查询、mutation、事件处理器应该放在哪一层评审口径是flag标记为问题以下五种模式状态/查询/mutation/处理器被提升hoist到了真正使用它们的最低组件之上——即父层代管了本应由子层拥有的东西父组件拥有行/条目级动作row/item actions但这些动作并不在协调一个工作流workflowprops 穿透prop drilling穿过多个纯转发层仅为了把一个值或回调递给最底层的渲染者页面/tab 级区块组件变成数据属主却并不需要共享快照也不共享 loading/error/empty 的 UI功能代码仅因为只出现了一次或以后可能被复用就被提升到 shared 层。同时规则给出一条明确的反直觉豁免兄弟组件各自重复发起相同的 TanStack Query 调用是可接受的只要每个组件独立消费该数据缓存去重本身不构成把数据提升到公共父层的理由。这条规则与 Dify 仓库的实际技术栈直接对应。Dify Web 端在 Next.js App Router 之上大量使用 TanStack Query 管理数据例如 layout-main.tsx/app/(appDetailLayout)/[appId]/layout-main.tsx)、view.tsx/app/(appDetailLayout)/[appId]/overview/view.tsx) 等页面级组件均直接引入tanstack/react-query的 hooksweb/features/下的新特性目录如agent-v2、skills中useQuery/useMutation也分散在各叶子组件内而非集中到页面容器。从源码结构看仓库的既有做法正是谁消费、谁查询与本文档的 ownership 条款互为印证——评审时若发现数据被提升到并不共享加载态的父层即可依据本规则给出 P2 级维护性发现。组件边界Component Boundaries什么时候该拆、什么时候不该包第二章给出六条应被标记的边界问题超过 300 行的 React 组件文件且该文件混合了多个可拆分为聚焦的**同置colocated**组件、hooks 或工具函数的职责。注意规则的两个限定词行数只是触发器前提还必须存在可拆分的多职责混合浅层包装组件shallow wrapper——仅仅重命名 props 或隐藏真正的基础组件primitive多余的 DOM 包裹层它不提供布局、语义、可访问性、状态属主或库集成中的任何一项价值Dialog/dropdown/popover 的隐藏面hidden surface遮挡了父级流程却本应被提取为小的本地组件业务表单、菜单主体或一次性 helper 被移离其属主组件且既无复用也无语义价值。结论性建议只有一句优先按真实的数据与状态需求拆分成同置组件Prefer colocated components split by actual data and state needs。这条规则在 Dify 中有明确的落点约束Web 端对 Dify UI 基础组件的使用受 web/AGENTS.md 强制要求——优先使用langgenius/dify-ui/*子路径导出的 primitive、数据属性和设计令牌且不要添加会隐藏这些契约的 Web 层包装器Button、IconButton、Overlay 等均有此禁令。也就是说浅层 wrapper不仅违反组件架构规则包还会直接违反 Dify UI 的包级契约评审时属于双重命中。packages/dify-ui/README.md 中列出的 primitive 清单./dialog、./dropdown-menu、./popover、./drawer等 overlay 类别正是规则第 4 条隐藏面应提取为小本地组件所指的触发场景overlay 的开启状态与内容往往比宿主按钮复杂得多留在父组件里会让父级流程被弹窗状态污染。不良组件设计模式交互契约与泛化陷阱第三章是六章中条目最多的一章覆盖了 9 种应标记的设计模式可以归纳为三组交互契约破坏组对既有导航、侧边栏、下拉、webapp 列表、应用切换 UI 的重构没有保留行为敏感交互——展开/收起箭头、hover 持久化、置顶/删除控件、路由、键盘/焦点处理、开启状态的属主一个组件混合了数据获取、mutation 副作用、弹窗状态、表单校验、布局与行渲染且没有清晰属主。假泛化组带有大量 boolean props 的通用组件实际编码的是某一个功能的工作流用开关注入而非真实抽象shared 组件导入了功能特定的文案、路由或 API 契约——方向性错误依赖应指向更底层而非功能层功能组件接收预渲染的 fragmentsrender props 滥用仅仅是为了避免把属主放对位置包装组件改变了被包裹 primitive 的可访问语义——与 accessibility-ui.md 规则包交叠属于 P1/P2 级别的复合问题。数据流组子组件对同一概念同时接收原始服务端数据和派生的标志位例如同时传row.status和row.isDisabled产生两个事实来源组件暴露受控 propscontrolled props却为同一值保留了一个竞争的私有 state——受控/非受控混用是典型的 stale-state 缺陷源组件无法在调用方不做预处理的情况下渲染空态、加载态或缺失的可选 API 字段——健壮性契约缺失。该章还给出两条处置原则当既有组件已拥有交互逻辑时优先复用或扩展而非重写若重构不可避免必须保留旧的交互契约并为变更行为添加或更新聚焦测试测试要求路由到 testing.md。在 Dify 仓库中这类行为敏感交互正是评审高风险区web/app/(commonLayout)/下的应用列表、导航、切换类 UI 以及web/features/agent-v2/agent-detail/这类含多 tab、多 overlay 的详情页其展开/收起、hover 持久化、焦点管理行为一旦被重构破坏就会落到 P1用户可见回归而非 P3。规则要求先找属主、再谈重构本质上是在保护这些交互契约的可追溯性。Props 与类型反对无契约变更的形式统一第四章针对 props 设计给出 5 条标记规则仅为风格统一而重写声明或导出但没有改变所拥有行为或契约的变更对琐碎一次性 props起命名的Props类型内联类型更清晰时props 按 UI 实现命名如showArrow而非按领域/API 角色命名API 数据过早转换、或转换后丢失可追溯性generic name 让人无法回溯到后端字段调用方重复了最低渲染组件已经处理的 fallback 检查——防御逻辑下沉后上层应信任属主。本章最重要的一条反噪音条款是不要仅凭语法形式标记FC、React.FC、函数声明、箭头函数、命名导出或默认导出只有当所选形式造成具体的类型、生命周期、导出、框架或强制包契约缺陷时才允许报告。这条显式压制了评审中最高频的品味型噪音与 SKILL 层只报告绑定到可观察故障的发现的原则一致。Effects默认不存在除非同步具名外部系统第五章对useEffect采取了近乎有罪推定的立场。以下行为都应被标记在 effect 中转换 props/state 用于渲染这属于渲染期派生不是 effect把一个 state 值拷贝进另一个表示同一概念的 state事实来源重复stale-state 之源在 effect 中处理本应属于事件处理器的用户动作在 props 或可见性变化时重置本地状态——而派生、稳定的语义身份semantic identity或预期的挂载属主已经表达了该生命周期在 effect 中获取本应属于框架 API 或 TanStack Query 的数据。而一个 effect 若要合法存在必须同步一个具名外部系统规则列举了合法清单浏览器 API、订阅subscription、定时器timer、可见性触发的分析上报analytics-on-visibility、非 React 组件、命令式 DOM 集成。清单之外的 effect 一律视为问题。这条规则与 Dify 的数据层约定高度自洽web/AGENTS.md 要求新的后端调用使用/service/client生成的consoleQuery/consoleClientAPI禁止手写 REST helper——即所有服务端数据获取被集中到生成的 Query 层effect 中 fetch 数据因此失去了合法性依据评审时可直接引用两个证据点。状态建模生命周期先于存储机制第六章是全文概念密度最高的部分。应标记的状态反模式包括存储派生布尔值、disabled 标志、默认 tab、加载文案——这些可以从当前 query/feature 状态直接计算把会话级状态放在更长寿的可见性协调器visibility coordinator里再通过 open-state Effect 或生成的 key 清理而 primitive 的挂载内容生命周期本来就已匹配预期状态寿命把一个 DOM 字段镜像成相互竞争的 prop、default 和 React state 三个来源而编辑并不需要这些来源同步用本地 state 伪造服务端数据或生成的契约字段把本应是**实时应用状态live app state**的 UI 状态持久化到 localStorage在真实 API 确认前把功能本地的 mock 外壳接到不相干的既有 API上。随后是三段关键的方法论陈述值得逐条展开1. 先评审状态生命周期再评审存储机制。对隐藏面hidden surface即 dialog/drawer/popover 一类要区分可见性协调器与挂载内容两个角色私有于某次挂载会话的状态属主就应该是挂载内容本身只有当草稿必须在该内容属主卸载后依然存活、或另一个属主在协调它时才提升promote状态。稳定的语义身份 key 可以在所表示的身份变化时创建新快照但生成的 key 不是例行的 reset 命令——key{Math.random()}式重置正是上文第二条标记项。2. 优先渲染期派生。真正的本地 state 只留给用户选择、瞬态输入、受控弹窗、以及没有服务端来源的功能 UI 状态。只提交submit-only的 DOM 字段可以保持非受控只有当 React 必须拥有当前值来驱动渲染或协同时才使用本地受控 state。观察变更事件或追踪dirty 与否这类派生事实并不要求镜像字段值——这直接呼应第五章拷贝同一概念到第二个 state的禁令。同时明确不能仅因某处使用了受控 state 就提出发现必须有具体的竞争来源、stale-state 或属主缺陷作支撑。3. 落点在 Dify 的形态上。从web/context/目录结构14 个 context/provider 文件看Dify Web 端存在大量页面级 provider本章的可见性协调器 vs 挂载内容正是针对这类 provider 持有过多会话状态的场景。评审时若发现某 modal 的草稿状态挂在页面级 provider 且靠 effect 清理而弹窗内容本应自管即可按本章口径给出属主错误发现。导航Link 优先URL 承载可分享状态第七章给出三条标记规则对普通链接使用命令式路由跳转router.push式的普通导航用button 语义承担导航应为Link/a导航状态藏在组件 state 里而可分享的 filter、tab、分页本质上需要 URL 状态。正向规则是普通导航用Link仅在mutation 成功后的跳转、守卫式重定向、命令流command flow、表单提交副作用四类场景才使用 router API。这与 Dify 的 App Router 结构web/app/下大量(commonLayout)、(shareLayout)路由组页面相匹配应用详情页、webapp 分享页等大量场景涉及深链与分享把 tab/filter 塞进组件 state 会直接丢失可分享性属于可验证的用户可见缺陷P1 级别。小结把六章规则压缩为评审检查表章节一句话核心典型 Dify 证据锚点Ownership数据与行为放在真正使用它的最低组件查询重复不算提升理由web/features/**中useQuery散布于叶子组件Boundaries300 行只是触发器可拆分职责混合才是缺陷拒绝浅层 wrapperweb/AGENTS.md 禁止 Web 层 wrapper 隐藏 Dify UI 契约Bad Patterns重构必须保留交互契约警惕 boolean props 假泛化与双事实来源导航/侧边栏/webapp 列表等既有交互组件Props Types按领域角色命名不为风格统一重写导出语法形式不构成发现生成客户端/service/client的字段可追溯性Effects默认不存在合法者必须同步具名外部系统数据获取集中于生成的 Query 层effect fetch 无合法依据State Modeling生命周期先于存储机制协调器不代管挂载内容私有状态优先渲染期派生web/context/页面级 provider 的状态归属Navigation普通导航用Link可分享状态进 URLApp Router 深链页面结构需要强调的是该规则包的使用前提与边界它服务于显式的评审/审计请求作用于web/与packages/dify-ui/范围发现必须绑定到文件行号、失败契约或复现路径严重度遵循 P0–P3 分级若评审无任何发现输出就是 No issues found. 加上实质性验证缺口说明——不添加赞扬段落、不猜测风险。换言之这份文档的价值不在于给出更多规则而在于精确界定了什么算问题、什么只是品味让组件架构评审在人与 Agent 之间具备可复现的判定基线。【免费下载链接】difyBuild Agentic workflows, RAG pipelines, with rich AI model and tool support on one collaborative workspace. Deploy on cloud, VPC, or self-hosted, so teams move from prototype to production without rebuilding the stack.项目地址: https://gitcode.com/GitHub_Trending/di/dify创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考