性能开发规范

本文档是 W7Panel 性能开发规范入口，面向后端 API、K8s 调用、WebDAV 文件处理、前端请求、列表渲染、状态缓存和资源加载。

性能规范只记录长期有效的开发约束。历史测试结论和一次性分析报告保留在外层 docs/testing/performance/。

文档目录

文档	说明
后端性能规范	WebDAV、认证、K8s 客户端、缓存、并发和日志性能要求
前端性能规范	API 请求、轮询清理、状态缓存、列表渲染和资源加载要求

通用原则

• 新增功能先确认数据规模、请求频率、超时和缓存失效策略。
• 不把历史测试报告中的临时状态当作当前实现事实；实现前必须用代码和测试重新确认。
• 性能优化不能绕过鉴权、安全边界和协议标准，例如 WebDAV、OIDC、Registry v2 的响应格式不能为了统一 JSON 而改变。
• 面向用户的慢路径需要有 loading、超时、错误提示或降级行为。
• 大对象、大文件、大列表和高频轮询必须有明确边界，不能依赖默认值。

性能分级

开发前先给改动路径定级。等级决定是否必须做缓存、分页、并发限制和压测。

等级	场景	必须满足
P0 高频核心路径	认证中间件、首页、应用列表、文件管理、终端、日志、K8s proxy、WebDAV	有超时、缓存或防重策略；不能无上限读取、渲染或并发
P1 用户常用路径	应用详情、存储、域名、镜像、监控、审计列表	有 loading/error 状态；列表有分页或明确上限；请求可取消或可复用
P2 低频管理路径	设置页、一次性安装、手动维护动作	至少有超时和错误提示；长任务要避免阻塞请求
P3 开发调试路径	调试工具、测试页面、临时诊断接口	不影响生产默认路径；日志和开销有开关

设计流程

新增或重构功能时按以下顺序检查：

1. 确认数据规模：单次请求可能返回多少对象、多少字段、多少字节。
2. 确认调用频率：首屏一次、用户操作触发、轮询、高频中间件还是批量任务。
3. 确认成本来源：K8s API、kubelet exec、磁盘 I/O、网络代理、DOM 渲染、图表渲染还是大文本解析。
4. 确认边界策略：分页、limit、字段裁剪、流式处理、懒加载、虚拟滚动、缓存、防重或并发限制。
5. 确认失效策略：缓存何时刷新，token、namespace、Pod、containerID、权限变化时如何处理。
6. 确认验证方式：用什么命令、页面、Network 记录或测试用例证明不会退化。

默认预算

这些预算用于开发评审，不是硬性 SLA。超过预算时必须在文档或代码评审里说明原因。

指标	默认预算
普通 API 超时	10 秒
前端 axios 默认超时	30 秒
WebDAV 单文件编辑大小	50MB
单次目录条目	5000
首屏关键请求	互不依赖时并行
前端普通列表直接渲染	小于 1000 条
轮询间隔	按实时性设置，默认不低于 5 秒
批量并发	必须显式限制，不使用无限并发

常见方案选择

问题	优先方案	不建议
同一数据被多组件重复请求	store/hook 缓存、防重 Promise	每个组件各自请求
K8s 大列表响应慢	后端分页、字段裁剪、按 namespace 查询	前端拉全量再过滤
文件内容读取慢或内存高	流式读取、大小限制、特殊文件短路	io.ReadAll 后再判断
页面首屏慢	并行请求、懒加载低优先级数据	按代码顺序串行等待
高频 token 校验慢	token 指纹缓存、TTL、过期失效	每请求 TokenReview
大列表卡顿	分页、虚拟滚动、稳定 key	全量 DOM + index key
弹窗打开导致页面慢	弹窗显示时再初始化	页面加载时初始化所有弹窗数据

提交前检查

检查项	后端	前端
请求次数	是否避免重复 TokenReview、重复 K8s exec、重复创建客户端	是否避免首屏串行请求和重复拉取同一状态
数据规模	是否分页、limit、字段裁剪或流式处理	是否分页、虚拟滚动或按需渲染
生命周期	goroutine、连接、文件句柄是否释放	定时器、轮询、WebSocket、编辑器实例是否清理
缓存	是否有 TTL、失效、并发保护	是否有模块化 key、失效、强制刷新
日志	是否使用 slog，避免高频同步输出	是否避免生产 console 和敏感信息输出

提交说明或评审记录中建议写清：

• 哪些请求会新增、减少或改变调用时机。
• 新增缓存的 key、TTL、最大容量和失效方式。
• 列表、文件、日志、终端等大数据场景的边界。
• 本次验证用到的命令、页面和测试数据规模。