UserSessionManager

类概述

UserSessionManager 用于统一管理应用的用户登录会话与令牌生命周期，围绕 accessToken/refreshToken 的获取、持久化、安全存储、自动刷新和登出进行封装。类通过串行队列控制并发刷新，配合 Combine 事件流广播会话变更，确保接口调用在授权失败（401）时能够自动刷新并重试一次，从而保障网络请求的安全性与稳定性。支持多环境切换（如开发/测试/生产），并提供单点登出能力。

主要功能

• 登录与令牌获取
  • 提供 signIn(credentials)：完成凭证校验与令牌交换，持久化并发布会话就绪事件。
  • 维护 accessToken/refreshToken 及其过期时间，并在 App 冷启动时从 Keychain 恢复会话状态。
• 令牌自动刷新与重试
  • 提供 refreshIfNeeded()：在访问受保护资源前/或收到 401 后，按需刷新 accessToken。
  • 当服务端返回 401 时，自动执行一次刷新并对原请求重试一次；若刷新失败，则不再二次重试，按错误分类处理。
• 授权头生成
  • 提供 authorizationHeader()：返回当前可用 accessToken 对应的 HTTP 授权头（Authorization: Bearer …）；在调用方需要时与 refreshIfNeeded() 组合使用，确保令牌有效。
• 登出与单点登出
  • 提供 signOut()：清除内存与 Keychain 中的令牌并广播登出事件；支持单点登出策略（例如统一触发全局登出，联动各数据层与界面层统一清理状态）。
• 多环境切换
  • 针对不同环境维护独立的 Keychain 命名空间或键前缀，切换环境时自动清理当前环境令牌并广播需要重新登录的状态。
• 事件发布/订阅
  • 通过 Combine 事件流广播会话状态变化（如已登录、将过期、已刷新、已登出、刷新失败）。外部订阅者（ViewModel/Repository/拦截器）可据此做 UI 与请求层联动。
• 并发控制
  • 刷新流程由内部私有串行队列串行化，确保同一时间仅有一次刷新操作在进行；并发触发的刷新请求会排队等待同一结果，避免“惊群效应”与多次无效刷新。
• 错误分类与处理策略
  • 区分“凭证无效类错误”（如刷新令牌失效、账号被注销）与“网络/服务不可用类错误”（如超时、断网、5xx）。
  • 暴露重试间隔（如读取服务器 Retry-After 或内部退避策略）与上报钩子，便于埋点监控、故障告警与容量观测。

技术特点

• 语言与架构
  • 基于 Swift 5.9，符合 MVVM + Repository 分层。UserSessionManager 聚焦会话域，依赖 Repository 承担具体网络交互（URLSession）与数据编解码（Codable）。
• 并发模型与刷新串行化
  • 对外接口采用 Swift Concurrency（async/await）以简化调用方的异步流程。
  • 内部通过私有串行队列保证刷新流程的互斥执行；并将并发触发的刷新请求汇聚为单次刷新，其他调用挂起等待结果，刷新完成后统一恢复。
• 网络与请求重试
  • 使用 URLSession 发起认证/刷新请求；对 401 响应执行一次性刷新与原请求单次重试，严格限制重试次数以防循环调用。
• 安全与持久化
  • 使用 Keychain 安全存储 accessToken/refreshToken 及相关元数据（含过期时间、环境标识）；数据序列化采用 Codable，便于结构化存储与向后兼容。
  • Keychain 可按业务需求配置可访问性与访问分组；环境切换采用独立键空间，避免跨环境交叉读取。
• 事件机制
  • 暴露 Combine Publisher（例如 sessionStatePublisher/eventsPublisher）用于广播关键状态：SignedIn、TokenRefreshed、SignedOut、RefreshFailed 等，支持 UI 与网络层订阅。
• 扩展与可测试性
  • 通过协议抽象依赖（如 AuthRepository、Clock/DateProvider、Logger/Reporter），便于单元测试注入假实现与模拟场景（过期、断网、401/5xx、无效刷新令牌）。

使用场景

• 应用冷启动
  • 从 Keychain 读取上次会话；若令牌临期或已过期，在首个受保护请求前调用 refreshIfNeeded() 以主动续签。
• 发起受保护 API 请求
  • 请求前调用 refreshIfNeeded()，随后从 authorizationHeader() 取 Authorization 头并附加到 URLRequest。
  • 若服务器仍返回 401，网络层拦截器触发一次刷新并对原请求重试一次；刷新失败则向上抛出错误并发出会话事件。
• 用户登录/注销
  • 登录：调用 signIn(credentials) 完成令牌交换、持久化并广播已登录事件。
  • 注销：调用 signOut() 清空令牌、取消后续自动刷新并广播登出事件，实现单点登出。
• 多环境切换（如 Dev/Staging/Prod）
  • 设置目标环境后，清理当前环境令牌并广播需重新登录的状态；新的登录与令牌将持久化到对应环境命名空间。
• 风险与异常治理
  • 订阅刷新失败与登出事件，对应拉起重新登录、展示用户态提示，或触发上报钩子进行监控与报警。

注意事项

• 刷新互斥
  • 仅允许一次刷新在串行队列中进行；并发触发会等待相同刷新结果。调用方避免在外层再引入并发锁，防止死锁或双重等待。
• 401 重试边界
  • 每个请求最多因 401 触发一次刷新与一次重试；若仍失败，需由上层决定是否提示重新登录或执行降级策略，避免无限重试。
• 授权头与时序
  • authorizationHeader() 默认假设当前 accessToken 可用；若需要确保有效性，请在调用前执行 refreshIfNeeded() 或通过网络拦截器在 401 时补救。
• 错误分类与上报
  • 凭证无效类错误（如无效 refreshToken）应触发强制登出并清除令牌；网络类错误可结合重试间隔进行延迟重试或提示稍后重试。
  • 使用上报钩子记录关键事件（登录成功/失败、刷新成功/失败、登出、环境切换），并包含错误分类与重试间隔信息，便于监控与追踪。
• Keychain 与环境隔离
  • 确保为不同环境使用独立的 Key 标识或命名空间；环境切换需清理旧环境令牌，避免跨环境污染。
  • 按需配置 Keychain 可访问性与访问分组；不在日志或崩溃上报中输出明文令牌。
• 线程与取消
  • 对外 async 接口可能在内部切换至私有串行队列执行；调用方如需取消等待的刷新，应通过结构化并发的 Task 取消机制处理。
• 跨模块一致性
  • 单点登出需与网络拦截器、页面路由、缓存层达成一致行为：收到强制下线或凭证无效时，统一清理态并跳转登录。
• 限制条件
  • UserSessionManager 管理的是客户端令牌状态，无法绕过服务端策略（如令牌撤销、强制下线）；若服务端判定不可刷新，客户端只能终止会话并提示重新登录。