如何在Streamlit仪表板中实现基于JSON的状态持久化

针对你遇到的Pydantic可变对象变更无法触发保存、不符合Streamlit常规模式的问题，以下是几种高效且符合社区实践的实现方案：

方案1：基于Streamlit Session State + Pydantic 验证的核心方案 #

Streamlit的st.session_state是官方推荐的状态管理工具，所有用户交互的状态都应该托管在这里。结合Pydantic做数据结构校验，再手动/自动同步到JSON文件，能完美解决可变对象的问题。

核心代码示例 #

import os
import json
from typing import List
import streamlit as st
from pydantic import BaseModel, ValidationError

# 定义状态的Pydantic模型，仅用于校验结构
STATE_PATH = os.path.join(os.getcwd(), 'crop_state.json')

class SelectCameraState(BaseModel):
    selected_cameras: List[str] = []

class CropState(BaseModel):
    crop_type: str = "Anchor"  # 默认值
    bbox: List[int] = [0,0,100,100]
    anchor_class: str = ""
    anchor_position: List[int] = [0,0]

class ProcessState(BaseModel):
    feature_extractor: str = ""
    embedding_processor: str = ""
    outlier_detector: str = ""

class ApplicationState(BaseModel):
    camera_select_state: SelectCameraState = SelectCameraState()
    crop_state: CropState = CropState()
    process_state: ProcessState = ProcessState()

# 初始化状态：从JSON加载，加载失败则用默认值
def load_state():
    if os.path.exists(STATE_PATH):
        try:
            with open(STATE_PATH, 'r') as f:
                state_data = json.load(f)
                return ApplicationState(**state_data).dict()
        except (json.JSONDecodeError, ValidationError):
            # 格式错误或校验失败，返回默认状态
            return ApplicationState().dict()
    return ApplicationState().dict()

# 保存状态到JSON
def save_state(state):
    try:
        # 先通过Pydantic校验，确保数据结构合法
        ApplicationState(**state)
        with open(STATE_PATH, 'w') as f:
            json.dump(state, f, indent=2)
    except ValidationError as e:
        st.error(f"状态保存失败：{e}")

# 初始化session_state
if 'app_state' not in st.session_state:
    st.session_state.app_state = load_state()

# 示例：用户交互组件，直接修改session_state
st.subheader("摄像头选择")
selected_cams = st.multiselect(
    "选择摄像头",
    ["cam1", "cam2", "cam3"],
    default=st.session_state.app_state['camera_select_state']['selected_cameras']
)
# 当用户选择变化时，更新session_state并保存
if selected_cams != st.session_state.app_state['camera_select_state']['selected_cameras']:
    st.session_state.app_state['camera_select_state']['selected_cameras'] = selected_cams
    save_state(st.session_state.app_state)

st.subheader("裁剪设置")
crop_type = st.selectbox(
    "裁剪类型",
    ["Anchor", "Fixed"],
    index=0 if st.session_state.app_state['crop_state']['crop_type'] == "Anchor" else 1
)
if crop_type != st.session_state.app_state['crop_state']['crop_type']:
    st.session_state.app_state['crop_state']['crop_type'] = crop_type
    save_state(st.session_state.app_state)

# 可变对象示例：直接修改列表后保存
if st.button("添加摄像头"):
    new_cam = f"cam{len(st.session_state.app_state['camera_select_state']['selected_cameras'])+1}"
    st.session_state.app_state['camera_select_state']['selected_cameras'].append(new_cam)
    save_state(st.session_state.app_state)

# 展示当前状态
st.subheader("当前状态")
st.json(st.session_state.app_state)

方案2：自动监听Session State变化（无需手动触发保存） #

利用Streamlit的st.session_state.on_change方法，监听顶层状态键的变化，自动触发保存逻辑，简化代码：

优化代码示例 #

# 承接方案1的模型、加载/保存函数...

# 自动保存回调
def auto_save():
    save_state(st.session_state.app_state)

# 初始化时注册监听
if 'app_state' not in st.session_state:
    st.session_state.app_state = load_state()
    # 监听app_state的变化，自动保存
    st.session_state.on_change('app_state', auto_save)

# 示例组件：修改状态时无需手动调用save_state
st.subheader("摄像头选择")
selected_cams = st.multiselect(
    "选择摄像头",
    ["cam1", "cam2", "cam3"],
    default=st.session_state.app_state['camera_select_state']['selected_cameras']
)
st.session_state.app_state['camera_select_state']['selected_cameras'] = selected_cams

# 可变对象修改示例：需浅拷贝触发监听
if st.button("添加摄像头"):
    new_cam = f"cam{len(st.session_state.app_state['camera_select_state']['selected_cameras'])+1}"
    st.session_state.app_state['camera_select_state']['selected_cameras'].append(new_cam)
    # 直接修改嵌套列表不会触发on_change，浅拷贝顶层状态强制触发
    st.session_state.app_state = st.session_state.app_state.copy()

注意：直接修改嵌套的可变对象（如列表、字典）不会触发on_change，因为session_state检测的是顶层键的引用变化。解决办法是修改后对顶层状态做一次浅拷贝，强制触发监听事件。

最佳实践 #

• 单一数据源原则：所有状态都托管在st.session_state中，Pydantic仅用于数据结构校验和初始化默认值，不要把Pydantic模型作为状态存储载体。
• 避免在Pydantic验证器中做IO操作：Pydantic的验证器设计目的是数据校验，不是状态持久化，IO操作应该单独封装成函数。
• 处理异常情况：加载JSON时要处理格式错误、校验失败的情况，避免应用崩溃。
• 多用户场景适配：如果是多用户使用的仪表板，不要用全局的JSON文件，应该根据用户会话ID生成独立的状态文件，避免状态冲突。
• 批量保存优化：如果频繁修改状态，可添加防抖逻辑（比如延迟1秒再保存），减少IO操作次数。

内容的提问来源于stack exchange，提问作者jtm123