Streamlit交互式代码质量仪表盘实战:CoDiver UI 设计完全拆解
Streamlit交互式代码质量仪表盘实战:CoDiver UI 设计完全拆解
CoDiver 是一个基于 Streamlit 构建的交互式代码质量仪表盘,能把 Python、Java 源码和敏捷数据上传到浏览器端,一键跑出复杂度、代码异味与 Sprint 燃尽图等可视化结果。本文带你逐层拆解它的 UI 实现:从统一文件上传、会话状态(st.session_state)驱动的数据流,到 st.metric 指标卡片与 Plotly 图表组件,看懂一个生产级仪表盘是怎么搭起来的 📊。
快速上手:3 条命令跑起来
在理解代码之前,先把它跑起来(项目提供 requirements.txt,核心依赖为 streamlit、pandas、plotly、javalang):
git clone https://gitcode.com/gh_mirrors/co/CoDiver
cd CoDiver
pip install -r requirements.txt
streamlit run app.py
浏览器打开后,你会看到一个统一的控制面板:左侧侧边栏负责上传与配置,主区域默认显示落地页,上传文件并点击执行按钮后才渲染结果标签页。这个"先控制、后展示"的交互,正是后面所有设计的起点。
一张表看懂:CoDiver 的三大子系统
CoDiver 把"分析引擎"与"界面层"严格分离,UI 只负责收数据和画图。三个子系统对应不同的数据源与可视化:
| 子系统 | 输入 | 核心可视化 | UI 源码位置 |
|---|---|---|---|
| Python 代码指标 | .py 文件 |
复杂度散点图、LOC 直方图 | charts.py |
| Java 静态架构 | .java 文件 |
严重度柱状图、密度热力图 | ui_components.py |
| 敏捷流程 | Sprint .json |
速度趋势线、燃尽图 | app.py |
架构理念:前端"零耦合"地把文件交给后端 AST 引擎,引擎返回结构化字典,再转成 Pandas DataFrame 喂给 Plotly。详见 docs/architecture.md。
侧边栏控制面板:一个上传器通吃三种文件
整个交互的"驾驶舱"在 app.py 的 main() 里,用 st.sidebar 圈出一块统一控制中心,包含三类控件:
- 统一上传器:
st.file_uploader("Upload Source Code", type=['py', 'java'], accept_multiple_files=True),一个控件同时接收 Python 与 Java 文件; - 数据上传器:Sprint 与 Defect 两个 JSON 上传入口;
- 引擎配置区:
st.expander里用st.checkbox勾选四类 Java 检测器(设计/实现异味、命名、文档),用st.slider调节复杂度告警阈值(5–20,默认 10); - 执行按钮:
st.button("Execute CoDiver Analysis", type="primary")是唯一的"发令枪"。
这里有个值得抄的设计:点击按钮并不直接画图,而是先置一个会话标记 st.session_state.omni_analyzed = True(app.py)。这样"上传了文件但还没点执行"时,主区域只会显示提示框;点了执行才真正渲染结果。上传与展示解耦,让用户对"何时分析"有掌控感。
自动分类 + 动态标签页:按需渲染
拿到文件后,app.py 按扩展名一行切分:
python_files = [f for f in source_files if f.name.endswith('.py')]
java_files = [f for f in source_files if f.name.endswith('.java')]
随后用 st.tabs 动态生成标签页(app.py):传了 Python 就出"Code Metrics"页,传了 Java 就出"Architecture & Smells"页,传了 Sprint 数据就出"Agile Analytics"页。没上传任何文件时,则回退到 render_unified_landing() 落地页(app.py),展示能力卡片和使用步骤——界面永远有"下一步引导",这对新手体验非常关键。
一个细节:当用户上传多个 Java 文件时,会插入一个 st.selectbox 让你挑选当前要查看的文件(app.py),避免结果挤在同一个页面里。
会话状态(st.session_state):仪表盘的数据"内存"
Streamlit 每次交互都会重跑脚本,所以"跨渲染存数据"必须靠 st.session_state。CoDiver 的 Java 分析器把它用得很典型(dashboard.py):
initialize_session_state()先给analysis_results、analysis_metrics、source_code、file_name四个键兜底初始化;- 点执行后,
handle_analysis()在st.spinner("Parsing AST nodes...")的加载提示下运行引擎,把结果写回session_state(dashboard.py); display_analysis_results()再统一读取这些键,依次渲染摘要、指标、图表、明细表与源码查看器(dashboard.py)。
另一个巧思:当用户上传的是新文件时(文件名变化),会主动重置 analysis_results = None,防止"新代码配旧结果"的脏状态(dashboard.py)。这是新手最容易踩的坑,值得记下来。
指标卡片与 Plotly 图表:数字要"一眼可读"
仪表盘的核心是"扫一眼就懂"。CoDiver 用两种手段做到:
① st.metric 指标卡片(metrics_cards.py)
四列 st.columns(4) 里塞进 8 张指标卡:总文件数、总 kLOC、平均圈复杂度、认知复杂度、功能点、缺陷密度,以及 COCOMO 估算的工作量(人月)、工期(月)、团队规模(人)。每张卡都能显示一个主数字,信息密度极高。
② Plotly 交互图表(charts.py)
render_loc_distribution:px.histogram画代码行直方图;render_complexity_scatter:px.scatter把圈复杂度 × 认知复杂度画成散点,点大小=LOC,颜色用Viridis色阶——复杂度高的文件一眼"发亮";render_quality_bar:px.bar对比缺陷密度与功能点/kLOC;render_agile_charts:px.line画Sprint 速度趋势与燃尽图(charts.py)。
Java 侧则更丰富(ui_components.py):五个 Tab 覆盖分布饼图(hole=0.4 环形)、严重度堆叠柱、密度热力图(px.density_heatmap)与"Top Code Smells"横向条形图。
细节交互:筛选、告警与一键导出
好的仪表盘不止是"看",还要能"用":
- 重构建议告警:复杂度超过阈值的文件会触发
st.warning卡片,逐条点名并建议"拆成更小的函数";全部达标则st.success报喜(metrics_cards.py); - 三维度筛选:Java 明细表上方用三个
st.multiselect(严重度/类别/类型)实时过滤 DataFrame(ui_components.py); - 导出闭环:
st.download_button支持把筛选结果导出为 CSV/JSON,时间戳命名analysis_report_YYYYmmdd_HHMMSS.csv,还能下载整份 TXT 摘要报告(ui_components.py)。
这套"筛选→查看→导出"的组合,正是把分析结果变成"可交付物"的关键一步。
核心文件清单:照抄这份结构
想在自己的项目里复刻同款仪表盘,重点看这几个文件:
| 文件 | 职责 | 关键实现 |
|---|---|---|
| app.py | 统一入口与调度 | 动态标签页、omni_analyzed 执行开关 |
| dashboard.py | 会话状态与执行流 | initialize_session_state、handle_analysis |
| charts.py | Plotly 图表组件 | 散点/直方图/燃尽图 |
| metrics_cards.py | 指标卡片 | st.columns + st.metric |
| ui_components.py | 摘要/图表/明细/导出 | 五 Tab 可视化 + 筛选导出 |
| sidebar.py | 独立侧边栏 | 文件上传与设置 |
测试用的真实数据样例也在仓库里:sprintJSON.json(Sprint 燃尽数据)与 defect_data.json(缺陷数据),下载下来直接喂给上传器即可复现文章里的图表效果。
总结:4 个可复用的 Streamlit 仪表盘模式
- 统一上传 + 扩展名分发:一个
file_uploader收多语言文件,按后缀路由到不同引擎; - 执行按钮 → 会话标记:用
st.session_state的布尔开关区分"已上传"与"已分析",交互意图更清晰; - 指标卡 + 交互图双栏:
st.metric负责"数字速览",Plotly 负责"细节下钻",信息分层呈现; - 筛选 + 导出闭环:
multiselect实时过滤、download_button一键出报告,让结果真正可用。
照着这四步,配合"UI 与计算逻辑严格分层"的原则(参考 docs/architecture.md 的数据流图),你就能用 Streamlit 搭出一个既好看又实用的代码质量仪表盘。