Streamlit交互式代码质量仪表盘实战:CoDiver UI 设计完全拆解

原创2026-10-20 14:46:031,680 阅读

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):

  1. initialize_session_state() 先给 analysis_results、analysis_metrics、source_code、file_name 四个键兜底初始化;
  2. 点执行后,handle_analysis() 在 st.spinner("Parsing AST nodes...") 的加载提示下运行引擎,把结果写回 session_state(dashboard.py);
  3. 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 仪表盘模式

  1. 统一上传 + 扩展名分发:一个 file_uploader 收多语言文件,按后缀路由到不同引擎;
  2. 执行按钮 → 会话标记:用 st.session_state 的布尔开关区分"已上传"与"已分析",交互意图更清晰;
  3. 指标卡 + 交互图双栏:st.metric 负责"数字速览",Plotly 负责"细节下钻",信息分层呈现;
  4. 筛选 + 导出闭环:multiselect 实时过滤、download_button 一键出报告,让结果真正可用。

照着这四步,配合"UI 与计算逻辑严格分层"的原则(参考 docs/architecture.md 的数据流图),你就能用 Streamlit 搭出一个既好看又实用的代码质量仪表盘。

登录后查看全文
CoDiver