如何在Streamlit中实现基于Pydantic和JSON的状态持久化

Streamlit作为轻量级的数据应用开发框架，默认状态下页面每次交互都会重新运行脚本，导致用户之前输入的数据、选择的配置等状态全部丢失。通过结合Pydantic和JSON实现状态持久化，可以让应用在页面刷新后依然保留之前的状态，大幅提升使用体验。

核心依赖与原理说明

实现这个功能需要用到两个核心库，Streamlit负责页面交互，Pydantic负责状态数据的结构化定义和校验，JSON作为中间格式完成数据的序列化与反序列化。整体原理是：将用户操作产生的状态按照Pydantic模型的结构整理成字典，再转为JSON字符串写入本地文件；页面加载时读取本地JSON文件，解析后恢复为Pydantic模型实例，再同步到Streamlit的会话状态中。

环境准备

首先确保已经安装所需的依赖库，如果未安装可以通过pip命令安装：

pip install streamlit pydantic

定义Pydantic状态模型

首先需要用Pydantic定义状态的数据结构，明确需要持久化的字段及其类型，这样可以避免存储不符合预期的数据。以下是一个示例模型，包含用户输入的文本、选择的数值和两个勾选框的状态：

from pydantic import BaseModel

class AppState(BaseModel):
    user_input: str = ""  # 用户输入的文本
    select_value: int = 0  # 用户选择的数值
    is_checked1: bool = False  # 第一个勾选框状态
    is_checked2: bool = False  # 第二个勾选框状态

实现JSON读写工具函数

接下来编写两个工具函数，分别用于将Pydantic模型实例转为JSON并写入文件，以及从JSON文件读取数据并恢复为Pydantic模型实例：

import json
from pathlib import Path
from typing import Optional

def save_state_to_json(state: AppState, file_path: str = "app_state.json") -> None:
    """将状态保存到JSON文件"""
    # 将Pydantic模型转为字典，再序列化为JSON字符串
    state_dict = state.model_dump()
    with open(file_path, "w", encoding="utf-8") as f:
        json.dump(state_dict, f, ensure_ascii=False, indent=2)

def load_state_from_json(file_path: str = "app_state.json") -> Optional[AppState]:
    """从JSON文件加载状态，文件不存在则返回None"""
    path = Path(file_path)
    if not path.exists():
        return None
    try:
        with open(file_path, "r", encoding="utf-8") as f:
            state_dict = json.load(f)
        # 将字典转为Pydantic模型实例，自动完成类型校验
        return AppState(**state_dict)
    except Exception:
        # 文件损坏或格式错误时返回None
        return None

在Streamlit中集成状态持久化逻辑

最后在Streamlit的主逻辑中，将状态模型和读写函数与页面交互绑定，实现状态的自动保存和恢复：

import streamlit as st

def main():
    st.title("Streamlit状态持久化示例")
    
    # 1. 初始化状态：优先从JSON文件加载，没有则使用默认模型
    if "app_state" not in st.session_state:
        loaded_state = load_state_from_json()
        if loaded_state:
            st.session_state.app_state = loaded_state
        else:
            st.session_state.app_state = AppState()
    
    # 2. 页面交互组件，绑定到会话状态
    st.session_state.app_state.user_input = st.text_input(
        "请输入内容",
        value=st.session_state.app_state.user_input
    )
    st.session_state.app_state.select_value = st.slider(
        "选择数值",
        min_value=0,
        max_value=100,
        value=st.session_state.app_state.select_value
    )
    st.session_state.app_state.is_checked1 = st.checkbox(
        "选项1",
        value=st.session_state.app_state.is_checked1
    )
    st.session_state.app_state.is_checked2 = st.checkbox(
        "选项2",
        value=st.session_state.app_state.is_checked2
    )
    
    # 3. 保存按钮：点击后将当前状态写入JSON文件
    if st.button("保存当前状态"):
        save_state_to_json(st.session_state.app_state)
        st.success("状态保存成功，刷新页面后状态会恢复")
    
    # 4. 展示当前状态内容
    st.subheader("当前状态内容")
    st.write(st.session_state.app_state.model_dump())

if __name__ == "__main__":
    main()

注意事项

• 本地JSON文件的存储路径可以根据需要修改，若部署到服务器需要注意文件读写权限问题
• Pydantic的model_dump方法会将模型转为字典，兼容JSON的所有基础数据类型，复杂类型需要额外处理序列化逻辑
• 如果多个用户同时使用应用，本地文件存储会导致状态互相覆盖，多用户场景建议改用数据库存储
• 可以在页面每次交互后自动触发保存逻辑，不需要手动点击保存按钮，只需要在交互组件回调中调用保存函数即可

StreamlitPydanticJSON状态持久化修改时间：2026-07-02 19:51:33