 wanghanlin
|
5a553ec813
|
feat(sdk): SDK 内置 Token 自动刷新，支持每请求前向宿主取 Token
问题：SDK Token 默认仅 2 小时有效，而 SDK 此前没有任何刷新入口 —— token 只能
在 init() 时传一次、只存内存，收到 401 只回调 onError 报错，想换 Token 只能
destroy() 重建整个 DOM，第三方页面长时间挂载必然掉线。
取 Token 的四种触发方式（client/src/token.ts）
- 临期主动刷新：阈值取「总寿命 10% 与 5 分钟」的较小值，需传 expiresIn
- 每请求前取：tokenStrategy: 'always'，每个受保护请求发出前都向宿主取一次，
完全不推算过期时间（该模式下不排定时器、不认「返回同一 Token」的静默窗口）
- 401 兜底重试：换一次 Token 后自动重试原请求，UI 上不会闪错误
- 手动入口：ChatbotSDK.setToken(token, expiresIn?) / refreshToken()
取 Token 的两种来源（二选一，getToken 回调优先并明确告警）
- getToken 回调：由宿主实现，可复用其请求封装与鉴权头
- tokenUrl 地址：SDK 直接 GET，兼容 {token,expiresIn} 与
{success,token,expiresIn,roles}；用 credentials: 'same-origin'（同源带
Cookie、跨域不带，避免把宿主站点 Cookie 泄露给别的域）
两者都让 API Key 留在宿主服务端，不进浏览器；后端零改动。
关键实现约束（均有单测覆盖）
- 临期阈值必须自适应：后端 clampExpirationMillis 允许的最短 ttl 恰为 300s，
固定 5 分钟会让它永远处于临期态，定时器延迟算成 0 退化成秒级无限刷新循环
- expiresIn 只做 24h 上界钳制、绝不做下界，避免把「只剩 20s 的 Token」当成
300s 而带着已过期 Token 发请求（上界同时防 setTimeout 溢出与毫秒误传）
- provider 调用自带 10s 超时，refreshPromise 在 finally 无条件清空：宿主回调
永不 settle 时，挂起会经 single-flight 传染给后续所有受保护请求
- setToken 自增 generation 但不碰 refreshPromise：既防止在途刷新返回的旧值
覆盖宿主刚推来的新值，又不破坏 single-flight
- 刷新失败统一进 60s 熔断窗口（判断在 refreshNow 内，不在 ensureFresh），窗口
内请求照常发出、由 401 兜底，避免宿主取 Token 挂死时每个请求多等一次超时
- isProtectedPath 改用 URL.pathname 判定并与后端 SdkAuthFilter.shouldNotFilter
逐字对齐；顺带修掉旧实现 endsWith('/feedback') 遇 query 参数漏注入、
/attachment/upload 注入了 Token 却不享受 401 处理的两处不一致
- 401 透明重试对写请求（POST /feedback、/attachment/upload、DELETE 会话）安全，
依据是 SdkAuthFilter 的 401 全部发生在 chain.doFilter 之前（401 ⇒ 业务逻辑
未执行）；该前提已写入代码注释与 CLAUDE.md，改过滤器时需重新评估
顺带修复
- chat.ts：首 token 前点「停止生成」会反而多发一个同步 /ai/chat 请求
- tests/config.test.ts：2 条断言早已因窗口默认值改动而变红（不修平的话
npm test 无法充当回归门）
- 文档：修正 width 默认值 380->500、enableRag 默认值 false->true、roleId 幽灵
参数、「仅 console.error 输出」（控制台日志早已全量关闭）等过时描述，并补齐
token/expiresIn/getToken/tokenStrategy/tokenUrl 全部鉴权参数
验证
- client 单测 92 个全绿（新增 token.test.ts 60 个 + config 新增 9 个），
npx tsc --noEmit 通过
- npm run build（SDK）与 frontend npm run build 均通过，
mvn clean package -P prod 构建成功
- 浏览器端未实测（按项目惯例由用户在 IDEA 启动服务，避免抢占 9090 端口），
面板已加 TTL 输入与 tokenStrategy 选择开关供手工验证
|
1 month ago |
