Streamlit（二十）- API 参考文档（十三）- 缓存与状态管理组件
文章目录
- 一、服务端（SERVER）分组
- 1. `st.cache_data`：函数数据缓存装饰器
- 功能说明
- 核心参数
- 常用内置方法
- 代码示例
- 2. `st.cache_resource`：全局资源缓存装饰器
- 功能说明
- 核心参数
- 常用内置方法
- 代码示例
- `cache_data` 和 `cache_resource` 核心区别
- 3. `st.session_state`：会话状态存储对象
- 功能说明
- 基础操作语法
- 关键特性
- 限制
- 二、浏览器端（BROWSER）分组
- 1. `st.context`：浏览器上下文信息对象
- 功能说明
- 核心属性
- 代码示例
- 2. `st.query_params`：URL查询参数管理对象
- 功能说明
- 基础读写语法
- 处理重复Key（同一个参数出现多次 `?a=1&a=2`）
- 内置常用方法
- 典型使用场景
一、服务端（SERVER）分组
1.st.cache_data：函数数据缓存装饰器
功能说明
用于缓存计算结果数据（DataFrame、接口返回数据、统计结果、模型推理输出等）的装饰器。
缓存数据会做拷贝隔离，每个会话读取独立副本；适合频繁查询、重复计算、不占用全局连接的数据。
核心参数
| 参数 | 说明 |
|---|---|
ttl | 缓存过期时长，单位秒/时间字符串，None永久有效 |
max_entries | 缓存最大存储条目数，超限自动淘汰最旧缓存 |
show_spinner | 缓存未命中时展示加载动画，可自定义提示文字 |
persist | 设置为disk可将缓存持久化到本地磁盘，重启应用不丢失 |
hash_funcs | 自定义类型哈希函数，用于无法自动哈希的自定义对象 |
常用内置方法
func.clear()：清空该函数指定参数的缓存 / 全部缓存st.cache_data.clear()：全局清空所有cache_data缓存
代码示例
importstreamlitasst# 缓存接口查询数据，持久化到磁盘，有效期1天@st.cache_data(ttl="1d",persist="disk")defload_online_data(url):# 模拟接口请求importpandasaspdreturnpd.DataFrame({"value":[1,2,3]})df=load_online_data("https://demo.api.com/data")2.st.cache_resource：全局资源缓存装饰器
功能说明
用于缓存全局共享资源（数据库连接、AI大模型、GPU推理实例、文件句柄等），资源对象全应用、多会话共享，不会生成数据拷贝，节省内存。
注意：缓存资源需要线程安全，多用户并发访问不会冲突。
核心参数
大部分参数与st.cache_data通用，独有：
validate：资源校验函数，每次读取缓存时执行，返回False则自动重新创建资源
常用内置方法
func.clear()：清空当前函数缓存st.cache_resource.clear()：全局清空所有资源缓存
代码示例
importstreamlitasstfromtransformersimportpipeline# 全局缓存NLP大模型，所有用户共用一个模型实例@st.cache_resourcedefload_sentiment_model():model=pipeline("sentiment-analysis")returnmodel model=load_sentiment_model()result=model("我爱Streamlit")st.write(result)cache_data和cache_resource核心区别
| 特性 | st.cache_data | st.cache_resource |
|---|---|---|
| 缓存内容 | 计算数据、表格、文本结果 | 模型、数据库连接、硬件资源 |
| 内存隔离 | 每个会话生成独立数据拷贝 | 全应用单例共享，无拷贝 |
| 使用场景 | 接口查询、数据清洗、统计计算 | 加载大模型、创建数据库连接 |
3.st.session_state：会话状态存储对象
功能说明
字典式会话存储，单独隔离每个浏览器标签页/用户会话，页面重运行、多页面跳转时数据不会丢失；用来存储控件值、临时变量、登录信息、计算中间结果。
基础操作语法
- 初始化（防止重复创建）
if"username"notinst.session_state:st.session_state.username=""- 读写取值（两种写法等效）
# 点语法st.session_state.username="小明"# 字典下标语法st.session_state["username"]="小明"# 读取st.write(st.session_state.username)- 删除键值
# 删除单个keydelst.session_state.username# 清空全部会话数据forkeyinst.session_state.keys():delst.session_state[key]关键特性
- 控件自动绑定：设置了
key参数的组件，值会自动同步到session_state
st.text_input("输入姓名",key="name")st.write(st.session_state.name)# 自动读取输入框内容- 配合回调函数：按钮、输入框的
on_click/on_change回调可以修改会话状态 - 多页面互通：同一个会话下所有页面共享
session_state数据
限制
- 不建议直接修改已渲染控件对应的
key值，会抛出异常；初始化需在控件渲染前完成 - 部分特殊对象（未序列化的lambda、数据库游标）默认无法存储，可开启强制序列化配置
二、浏览器端（BROWSER）分组
1.st.context：浏览器上下文信息对象
功能说明
只读对象，用于读取当前用户浏览器请求的上下文信息，仅可读取、无法修改，适合鉴权、环境识别场景。
核心属性
st.context.cookies- 只读字典，获取浏览器发送的全部Cookie；
- 取值示例：
st.context.cookies["_ga"]。
st.context.headers- 只读请求头字典，键名大小写不敏感；
- 普通取值仅获取重复Header的最后一个值；
headers.get_all("key")：获取同一个键的全部Header值列表。
代码示例
importstreamlitasst# 读取全部Cookiest.write("当前Cookie：",st.context.cookies)# 读取指定Cookiega_cookie=st.context.cookies.get("_ga","无")st.write("GA Cookie值：",ga_cookie)# 读取Host请求头host=st.context.headers["host"]st.write("访问域名：",host)# 获取全部Accept编码头all_accept=st.context.headers.get_all("accept-encoding")st.write("全部编码头：",all_accept)2.st.query_params：URL查询参数管理对象
功能说明
字典式读写对象，用于读取、修改浏览器地址栏URL上的?key=value查询参数；修改后浏览器地址会自动同步更新，支持多页面传参、页面分享链接。
基础读写语法
importstreamlitasst# 读取参数（下标/属性两种写法）id_val=st.query_params["id"]name_val=st.query_params.name# 修改参数，URL自动刷新st.query_params.id="1001"st.query_params.name="测试用户"处理重复Key（同一个参数出现多次?a=1&a=2）
- 直接取值只会拿到最后一个值；
.get_all(key)获取该键所有值组成列表；- 赋值列表可生成重复参数：
st.query_params.a = ["1", "2", "3"]
# 获取全部同名参数all_a=st.query_params.get_all("a")st.write(all_a)内置常用方法
.clear()：清空URL全部查询参数st.query_params.clear().from_dict(dict)：批量覆盖所有查询参数st.query_params.from_dict({"page":"dashboard","type":"data"}).to_dict()：将当前参数转为标准字典返回
典型使用场景
- 页面间跳转传递ID、筛选条件；
- 生成带参数分享链接，打开页面自动读取参数加载对应数据；
- 保存筛选器状态到URL，刷新页面不会丢失筛选条件。