widget-code-review

# Widget 组件代码评审 ## 适用场景 - 用户要求对某个 Widget / Page 文件进行代码审查 - 用户觉得某个组件"看起来糟糕"、"需要优化" - 重构前的问题发现阶段 ## 不适用 - 已经明确要执行重构 → 用 `widget-refactor` 技能 --- ## 评审维度（按此顺序逐项检查） ### 1. 体量与结构 | 检查项 | 标准 | 坏味道 | |--------|------|--------| | 文件行数 | ≤ 500 行 | 超过 600 行的 God Widget | | build 方法行数 | ≤ 40 行 | 超过 60 行的巨型 build | | 最大缩进层级 | ≤ 6 层 | 8 层以上的嵌套地狱 | | 方法数量 | ≤ 15 个 | 职责不单一的信号 | ### 2. build 方法可读性 | 检查项 | 期望 | 坏味道 | |--------|------|--------| | 骨架一屏可见 | build 只做 UI 拼接，一屏能看完结构 | 需要滚动 3 屏才看完 | | 内联闭包 | 事件处理 ≤ 1 行（方法引用） | 超过 3 行的匿名闭包硬嵌在构建树中 | | 条件分支 | 用 getter 或三元表达式 | 大段 if-else 块打断构建流 | | 重复参数 | 同组参数只出现一次 | 两个相似组件重复传 8+ 相同参数 | | 组件分离 | 可独立构建的小零件，独立出文件；按功能建文件夹收录 | 30+ 行的 UI 片段内联在 build 中 | | 注释 | 类顶部 `///` 文档注释，方法体内不写注释 | 代码里散落说明性注释 | ### 3. 分层职责 | 检查项 | 期望 | 坏味道 | |--------|------|--------| | HTTP 请求 | 在 Repository / Cubit 层 | View 层直接 `dio.get(...)` | | JSON 解析 | 在 data 层 | View/State 中 `jsonDecode(...)` | | WS 监听 | 在 Cubit 中管理（自动 cancel） | View 层持有 StreamSubscription | | 业务判断 | 在 logic 层或 handler | View 中写 switch/if 业务分支 | | 状态修改 | 通过 Cubit emit | View 层 setState 管理业务状态 | | 错误提示 | 通过事件总线或 State 反馈 | View 层 try-catch 包裹每个调用 | ### 4. 命名与参数设计 | 检查项 | 期望 | 坏味道 | |--------|------|--------| | 方法命名 | 动词开头，表达意图 | `_safeSend`、`_handle1`、`_do` | | 参数分组 | 3+ 个总是一起传递的参数 → 值对象 | 10+ 散装参数的构造函数 | | 值对象边界 | 按语义分组，不是一股脑塞进一个 Config | 一个大 Config 混装身份+UI+状态 | | 缩写 | 只在极小作用域使用 | 类级 getter 用 `_t`、`_c`、`_opts` | | 中转方法 | 不存在（直接用目标方法） | `_handleX() { _doX(); }` 纯委托 | | 重复逻辑 | 用 extension 封装 | 三元嵌套判断类型摘要 | ### 5. 状态管理模式 | 检查项 | 期望 | 坏味道 | |--------|------|--------| | 数据订阅 | `context.select` 精确订阅 | 整个 BlocBuilder 监听全量 State | | 状态归属 | 每组状态有独立 Cubit | 一个 God Cubit 管所有 + View 还存一份 | | Cubit getter | 常用派生值暴露 getter | 外部每次从 state 手动计算 | | 独立 Scope Widget | 有独立重建边界的 UI 块封装为 Widget | BlocBuilder 嵌套在 build 中 | ### 6. 性能与生命周期 | 检查项 | 期望 | 坏味道 | |--------|------|--------| | Subscription | Cubit 管理，View 不持有 | View 层 listen + dispose cancel | | BuildContext | async 后必检 mounted | `await ... Navigator.push` 无守卫 | | const 优化 | 纯展示 Widget 可 const | 每次 build 重建不变的 Widget | | 重复计算 | 昂贵计算缓存或提升 | itemBuilder 中每次 `jsonDecode` | --- ## 输出要求 评审结果输出为文档文件，路径：`docs/project/checkup/{版本}/client/{序号}_{文件名}_review.md` ```markdown # {文件名} 代码评审 当前行数：{N} 行（有效代码 {M} 行） ## 问题清单 | # | 维度 | 问题描述 | 严重度 | 建议 | |---|------|---------|--------|------| | 1 | 结构 | build 方法 120 行 | P0 | 拆为子方法 | | 2 | 可读性 | onSendVideo 回调内联 10 行 | P1 | 提取为命名方法 | | ... | | | | | ## 改进方向（概要） - P0：... - P1：... ``` ## 严重度定义 | 级别 | 含义 | 标准 | |------|------|------| | P0 | 必须修 | 严重影响可读性/可维护性，阻碍后续开发 | | P1 | 应该修 | 违反分层/重复代码/命名混乱，但不阻塞 | | P2 | 可以修 | 风格优化、微调，有空再改 | ## 注意事项 - 不要只列问题不给方向——每个问题附带一句改进方向 - 不要过度设计——500 行内能清晰表达就不需要强行拆 - 保持务实——P2 问题一行带过