widget-code-review

name	widget-code-review
description	Flutter Widget/Page 组件代码评审技能。在需要审查组件代码质量、发现设计问题时激活，确保输出结构化的问题清单和改进建议。
metadata	{"model":"manual","last_modified":"Sun, 14 Jun 2026 00:00:00 GMT"}

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

# {文件名} 代码评审

当前行数：{N} 行（有效代码 {M} 行）

## 问题清单

| # | 维度 | 问题描述 | 严重度 | 建议 |
|---|------|---------|--------|------|
| 1 | 结构 | build 方法 120 行 | P0 | 拆为子方法 |
| 2 | 可读性 | onSendVideo 回调内联 10 行 | P1 | 提取为命名方法 |
| ... | | | | |

## 改进方向（概要）

- P0：...
- P1：...

严重度定义

级别	含义	标准
P0	必须修	严重影响可读性/可维护性，阻碍后续开发
P1	应该修	违反分层/重复代码/命名混乱，但不阻塞
P2	可以修	风格优化、微调，有空再改

注意事项

• 不要只列问题不给方向——每个问题附带一句改进方向
• 不要过度设计——500 行内能清晰表达就不需要强行拆
• 保持务实——P2 问题一行带过