# ReadViewSDK 代码审查报告

> 审查范围：`Sources/RDReaderView/` 全部 184 个 Swift 文件（约 32,300 行）
> 审查维度：并发安全、内存管理、API 正确性、Swift/iOS 平台特定、架构与依赖
> 审查日期：2026-06-26

---

## 严重程度定义

| 标记 | 含义 |
|------|------|
| 🔴 高 | 有明确代码路径可导致崩溃、数据丢失或严重功能缺陷 |
| 🟡 中 | 方向正确但风险程度取决于运行时条件；或当前安全但架构上脆弱 |
| 🟢 低 | 代码异味、可维护性问题或未来风险 |

---

## 🔴 高优先级问题

### H-01 · 内存警告未连接章节缓存清理

`RDEPUBChapterRuntimeStore.handleMemoryWarning()` 已实现（清空除当前章节外的缓存 + 清除图片缓存），但从未被调用。

- `RDEPUBReaderRuntime.handleMemoryWarning()` 只清理了 `backgroundCoverageStore`，未调用 `chapterRuntimeStore.handleMemoryWarning()`
- `RDEPUBReaderController` 未重写 `didReceiveMemoryWarning`

**影响：** 系统内存压力下，`RDEPUBChapterDataCache`（无上限字典）和 `imageCache`（仅 countLimit=50，无 totalCostLimit）不会主动释放内存。

**位置：**
- `RDEPUBChapterRuntimeStore.swift:103` — `handleMemoryWarning()` 方法存在
- `RDEPUBReaderRuntime.swift:606-620` — 只清理 backgroundCoverageStore

---

### H-02 · 主线程信号量等待

`RDEPUBChapterLoader.loadChapterSynchronouslyForMigration()` 使用 `DispatchSemaphore.wait()` 阻塞调用线程。当从 `RDEPUBPresentationRuntime.rebindVisibleLocation()` 以 `allowSynchronousLoad: true` 调用时，会在主线程等待。

**影响：** 如果章节数据未缓存，主线程被阻塞直到章节构建完成，可能导致 ANR 或死锁（如果构建过程需要主线程资源）。

**位置：**
- `RDEPUBChapterLoader.swift:206-268` — `semaphore.wait()`
- `RDEPUBPresentationRuntime.swift:282-286` — `allowSynchronousLoad: true`

---

### H-03 · asyncAfter 闭包中的强制解包

`RDEPUBReaderController+DataSource.swift:425-436` 在 0.3 秒延迟闭包中强制解包 `lastTextPaginationPageSize!`。方法入口的 `guard let lastTextPaginationPageSize` 不保护延迟闭包——0.3 秒后该值可能已变为 `nil`。

**位置：**
```swift
// line 432-433
let stillChanged = abs(currentSize.width - self.lastTextPaginationPageSize!.width) > 0.5
    || abs(currentSize.height - self.lastTextPaginationPageSize!.height) > 0.5
```

---

### H-04 · `unowned context` 在后台操作中的崩溃路径

以下两个类在后台操作中访问 `unowned let context: RDEPUBReaderContext`，若 controller 在操作期间释放则会崩溃：

**RDEPUBMetadataParseWorker：**
- Line 117: `let context = self.context` 在 `[weak self]` guard 之前将 unowned 引用捕获为局部变量
- Lines 197-324: `BlockOperation` 闭包直接使用该局部变量（unowned），无 `[weak self]` 保护
- Lines 296-301, 372-376: `DispatchQueue.main.async` 闭包捕获 unowned 局部变量

**RDEPUBReaderLoadCoordinator：**
- Line 28: 闭包只捕获 `[weak controller]`，未捕获 `[weak self]`
- Line 30: `self.context.makeParser()` 在后台队列访问 unowned 引用
- Lines 41-42, 53-54: `DispatchQueue.main.async` 闭包直接访问 `self.context`

**影响：** 若 `RDEPUBReaderController` 在后台操作期间释放（如用户快速退出阅读器），`unowned` 引用悬挂导致 EXC_BAD_ACCESS。

**位置：**
- `RDEPUBMetadataParseWorker.swift:117, 197-324, 296-301, 372-376`
- `RDEPUBReaderLoadCoordinator.swift:28-57`

---

### H-05 · 章节数据缓存无容量限制

`RDEPUBChapterDataCache` 是无上限的 `[Int: RDEPUBRuntimeChapter]` 字典，仅通过显式 `remove(spineIndex:)` 或 `removeAll()` 逐出。每章持有完整的 `typesetAttributedString`（50-200KB+），50 章可达 5-10MB+。

**位置：** `RDEPUBChapterDataCache.swift:5` — `private var storage: [Int: RDEPUBRuntimeChapter] = [:]`

---

### H-06 · 暗色图片静态 NSCache 无 totalCostLimit

`RDEPUBDarkImageAdjuster.imageCache` 是 static `NSCache<NSString, UIImage>()`，无 `totalCostLimit`，跨越整个 App 生命周期累积调整后的图片。

**位置：** `RDEPUBDarkImageAdjuster.swift:9`

---

### H-07 · 持久化操作静默丢弃错误

`RDEPUBReaderPersistence` 中所有编解码操作均使用 `try?`，失败时：
- **保存**：静默返回，数据丢失无任何反馈（lines 84, 98, 112, 131）
- **加载**：返回 `nil` 或空数组，损坏/版本不匹配的数据无法恢复（lines 80, 94, 108, 127）

**影响：** 用户书签和阅读位置可能在无声中丢失。

**位置：** `RDEPUBReaderPersistence.swift:76-131`

---

### H-08 · WKURLSchemeHandler 线程违规与取消回调缺失

两个确定 bug：

**(a) 不同队列回调：** `webView(_:start:)` 在某个串行队列（由 WebKit 调度）上被调用，但 `respondWithInMemoryData` 和 `respondWithStreaming` 将 `didReceive`/`didFinish`/`didFailWithError` 显式切到了 `ioQueue`（line 121, 151）。这至少违反了"回调应与 `start` 使用同一串行队列"的要求。

**(b) 取消时不调用完成回调：** 任务被 `stop` 后，`isTaskActive` 返回 false 时：
- streaming 路径（line 178）：`guard self.isTaskActive(taskID) else { return }` — 仅 return，不调用 `didFinish` 或 `didFailWithError`
- in-memory 路径（line 128, 141）：同理

这违反了"每个 started task 必须收到完成回调"的协议要求。

**位置：** `RDEPUBResourceURLSchemeHandler.swift:121-187`

---

### H-09 · 搜索在后台线程同步加载所有章节

`RDEPUBReaderSearchCoordinator` 在 `searchQueue` 上遍历所有 buildable spine 索引，逐个同步加载章节。每章持有完整 `typesetAttributedString`，大型书籍搜索时内存峰值显著。

**位置：** `RDEPUBReaderSearchCoordinator.swift:47, 173-236`

---

### H-10 · 依赖版本未锁定

`RDReaderView.podspec` 中 DTCoreText、SnapKit、SSAlertSwift 无版本约束：

```ruby
s.dependency 'ZIPFoundation', '~> 0.9'   # ✅ 已锁定
s.dependency 'DTCoreText'                 # ❌ 无约束
s.dependency 'SnapKit'                    # ❌ 无约束
s.dependency 'SSAlertSwift'               # ❌ 无约束
```

**位置：** `RDReaderView.podspec:17-20`

---

### H-11 · SnapKit 和 SSAlertSwift 疑似死依赖

全仓库搜索未找到任何 `snp.` 或 `SSAlert` 的使用点。这两个依赖可能增加了不必要的二进制体积和潜在冲突。

---

## 🟡 中优先级问题

### M-01 · `RDEPUBReaderState` 无同步保护（隐性风险）

所有属性（`parser`, `publication`, `activeBookmarks`, `pendingPageMapUpdates` 等）均为 `var`，无锁、无 `@MainActor`、无 `dispatchPrecondition`。当前所有访问确实在主线程（经追踪 16 个 `pendingPageMapUpdates` 访问点确认），但缺少形式化保障——未来开发者可能无意从后台线程访问而不自知。

**位置：** `RDEPUBReaderState.swift:1-71`

---

### M-02 · `currentSpineIndex` / `windowSpineIndices` 无锁但当前安全

这两个字段无锁保护，但追踪全部读写路径后确认当前均在主线程。风险是隐性的：store 对象被传入 `chapterLoadQueue` 上下文，未来开发者可能在该队列中访问这些属性而不自知。同文件的其他字段（`navigationLock`, `prefetchLock`, `buildingLock`, `cfiMapLock`）有锁保护，形成不一致的模式。

**位置：** `RDEPUBChapterRuntimeStore.swift:15-17`

---

### M-03 · `warmAnchors` 跨线程访问无同步

`RDEPUBBackgroundPriorityManager.warmAnchors` 在主线程写入（`addWarmAnchor`），在 `MetadataParseWorker` 的后台线程读取（`makeMetadataPriorityOrder`），无锁保护。

**位置：** `RDEPUBBackgroundPriorityPolicy.swift:65`

---

### M-04 · `assert(Thread.isMainThread)` 在 Release 中被移除

`RDEPUBReaderContext` 的 `makeLayoutSnapshot()`、`currentTextPageSize()` 等方法使用 `assert(Thread.isMainThread)` 检查。`assert` 在 `-O` 构建中被移除，生产环境中后台线程调用将静默访问 UIKit 属性，造成数据竞争且无诊断。

**应使用：** `dispatchPrecondition(condition: .onQueue(.main))` 或 `@MainActor` 标注。

**位置：** `RDEPUBReaderContext.swift:172, 188, 210, 215`

---

### M-05 · 磁盘缓存无自动淘汰策略

`RDEPUBChapterSummaryDiskCache` 和 `RDEPUBTextBookCache` 只有全量清除操作（`removeAll()`、`invalidateAll()`），无 LRU/大小/年龄驱逐策略。每次设置变更（字体、行距、主题）产生新缓存键，旧文件无限累积。写操作使用原子替换（tmp + replace），交错不会损坏数据，但可能读到旧值或看到不一致的目录状态。

**位置：**
- `RDEPUBChapterSummaryDiskCache.swift:89` — `removeAll()` 全清
- `RDEPUBTextBookCache.swift:191` — `invalidateAll()` 全清

---

### M-06 · CFI 范围分隔符可能与内容冲突

`RDEPUBCFICompatibility` 按 `".."` 和 `"-"` 分割 CFI 范围字符串，但这些字符可能出现在 CFI 文本断言内部（如 `[foo..bar]`）。代码先匹配 `".."` 再匹配 `"-"`，无歧义消解逻辑。

**位置：** `RDEPUBCFICompatibility.swift:18-21`

---

### M-07 · CFI 步索引对奇数输入容错不严谨

`RDEPUBCFIResolver` 中 `steps[1].index / 2 - 1` 对奇数索引做整除截断，可能映射到错误章节。`max(..., 0)` 仅防负索引，不防错误映射。属于 EPUB CFI 规范的输入验证问题。

**位置：** `RDEPUBCFIResolver.swift:38`

---

### M-08 · WKWebView 保留环需主动管理

`RDEPUBWebView` → `webView` → `configuration.userContentController` → `RDEPUBWebView`（作为 `WKScriptMessageHandler`）形成保留环。

主要解环路径是 `reset()` 和 `configureWebViewIfNeeded` 中主动调用 `teardownWebView()`。**注意：** `deinit` 虽也调用 `teardownWebView()`，但不能作为环会被打破的保证——保留环的存在意味着 `deinit` 可能永远不会触发。风险在于：若某条代码路径跳过了 `teardownWebView()`，环将持续且对象永远不会释放。

**位置：**
- `RDEPUBWebView.swift:129` — `deinit` 调用 `teardownWebView()`（不可靠兜底）
- `RDEPUBWebView.swift:138-160` — `reset()` 调用 `teardownWebView()`（主要解环路径）

---

### M-09 · `configuration` didSet 在 `isViewLoaded` 之前持久化

`RDEPUBReaderController.configuration` 的 `didSet` 在 `guard isViewLoaded` 之前执行了 `readerContext.configuration = configuration`、`applyWebViewDebugPolicy()` 和 `persistReaderSettingsIfNeeded()`。若在 view 加载前设置 configuration，这些副作用会在 UI 未就绪时触发。

**位置：** `RDEPUBReaderController.swift:8-20`

---

### M-10 · empty catch 吞掉章节加载错误

`RDEPUBReaderPaginationCoordinator` 中 `loadInitialInteractiveRuntimeChapters` 的 `catch {}` 为空，章节加载失败被静默忽略，无日志、无恢复。

**位置：** `RDEPUBReaderPaginationCoordinator.swift:283`

---

### M-11 · `RDEPUBReaderFontChoice.displayName` 始终返回中文

枚举的 `displayName` 计算属性硬编码中文字符串（"系统"、"宋体"、"圆体"、"等宽"），无本地化基础设施。

**位置：** `RDEPUBReaderConfiguration.swift:18-28`

---

### M-12 · 大量硬编码中文字符串，本地化覆盖不完整

覆盖文件：`RDEPUBReaderSettingsViewController`、`RDEPUBReaderSearchBarView`、`RDEPUBReaderHighlightsViewController`、`RDEPUBReaderBookmarksViewController`、`RDEPUBReaderTopToolView`、`RDEPUBReaderBottomToolView`、`RDEPUBTextContentView`、`RDEPUBWebView+Configuration`、`RDEPUBChapterLoader`（错误信息）等。

项目中存在约 88 个硬编码中文字符串（如"拷贝"、"高亮"、"批注"、"目录"、"搜索"等），但同时也有使用 `NSLocalizedString` 的地方（如 `RDEPUBImageViewController.swift:126`）。本地化基础设施存在但覆盖不完整——新添加的 UI 文本大多直接硬编码中文而未走本地化流程。

---

### M-13 · DTCoreText 类型泄漏到 EPUBUI 层

5 个 EPUBUI 文件直接使用 `DTCoreTextLayoutFrame`、`DTCoreTextLayoutLine`、`DTCoreTextGlyphRun` 等 DTCoreText 类型（虽有 `#if canImport(DTCoreText)` 保护），意味着替换渲染引擎需修改 UI 层文件。

**位置：**
- `RDEPUBPageInteractionController.swift`
- `RDEPUBPageLayoutSnapshot.swift`
- `RDEPUBTextPageRenderView.swift`
- `RDEPUBTextContentView.swift`
- `RDEPUBDarkImageAdjuster.swift`

---

### M-14 · `imageCache` 有 countLimit 但无 totalCostLimit

`RDEPUBChapterRuntimeStore.imageCache` 设有 `countLimit = 50`，但无 `totalCostLimit`。50 张大尺寸书籍插图可达 150-250MB。

**位置：** `RDEPUBChapterRuntimeStore.swift:41`

---

### M-15 · `UIMenuController` 已废弃

`RDEPUBWebView+Configuration.swift:39` 和 `RDEPUBTextContentView.swift:747-758` 使用 `UIMenuController`，该 API 从 iOS 16 起废弃。应迁移至 `UIEditMenuInteraction`（iOS 16+），并为 iOS 15 保留 fallback。当前代码在 iOS 17+ 上仍可工作但随时可能失效。

---

### M-16 · Dynamic Type 未支持

UI 中所有字体使用硬编码大小（`UIFont.systemFont(ofSize: 13/14/16/18/19)`），未使用 `UIFontMetrics` 或 `preferredFont(forTextStyle:)`。启用 Dynamic Type 的用户看不到文字大小变化。

---

### M-17 · URL Scheme Handler 取消时 `clearTask` 可能被跳过

`respondWithInMemoryData` line 128 的 `guard self.isTaskActive(taskID) else { return }` 在取消时直接返回，跳过了 line 146 的 `self.clearTask(taskID)`。当前因 `stop` 已调用 `clearTask` 而无害，但结构上脆弱。

**位置：** `RDEPUBResourceURLSchemeHandler.swift:128`

---

### M-18 · 硬编码颜色值未集成到主题系统

`RDEPUBReaderSearchBarView` 含 18 个硬编码颜色字面量，默认高亮颜色 `"#F8E16C"` 硬编码在 `RDEPUBReaderController+PublicAPI.swift:65,75`。这些应属于 `RDEPUBReaderTheme`。

---

### M-19 · 硬编码时间常量

多个 `DispatchQueue.main.asyncAfter(deadline:)` 和 `Thread.sleep` 使用硬编码延迟值（0.08s、0.1s、0.15s、0.2s、0.25s、0.3s、1.0s、3.5s），无命名常量或可配置选项。

---

## 🟢 低优先级问题

### L-01 · `RDEPUBChapterLoader` 中 `[self]` 强捕获

Line 103 的 `store.chapterLoadQueue.async { [self] in` 强捕获 self，阻止 loader 在队列任务完成前释放。应改为 `[weak self]`。

**位置：** `RDEPUBChapterLoader.swift:103`

---

### L-02 · MetadataParseWorker Thread.sleep 忙等待

`waitForReadingInteractionToSettle()` 使用 `Thread.sleep(forTimeInterval: 0.08)` 轮询，无上限等待。应考虑 `DispatchSource` 或条件变量。

**位置：** `RDEPUBMetadataParseWorker.swift:385-390`

---

### L-03 · `RDEPUBTextBookCache.queue.sync` 潜在死锁

`load()` 和 `save()` 均使用 `queue.sync`。若从 queue 内部调用则会死锁。当前未发现此调用路径，但模式脆弱。

**位置：** `RDEPUBTextBookCache.swift:136-189`

---

### L-04 · `pendingLoads` 字典无超时清理

`RDEPUBChapterLoader.pendingLoads` 的完成闭包数组在章节加载失败且 `resolvePendingLoad` 未被调用时可能累积。当前所有路径均调用 `resolvePendingLoad`，但无防御性超时。

**位置：** `RDEPUBChapterLoader.swift:7-10`

---

### L-05 · `RDEPUBChapterWindowCoordinator` 是死代码

该类定义了但未被任何代码实例化或引用。其中对 `currentSpineIndex`/`windowSpineIndices` 的7个访问点均为死代码。

---

### L-06 · 平台版本不一致

- `podspec`: `s.platform = :ios, "15.0"`
- `Podfile`（根和 demo）: `platform :ios, '15.6'`

---

### L-07 · `RDEPUBMetadataCancellationController` 微小竞争

`attach()` 方法在 `lock.unlock()` 和 `queue.cancelAllOperations()` 之间存在窄窗口，新操作可能被添加到队列但不会被取消。实际影响极小。

**位置：** `RDEPUBMetadataParseCancellationController.swift:attach()`

---

### L-08 · 页码标签硬编码偏移

`RDEPUBWebContentView` 和 `RDEPUBTextContentView` 的页码标签使用硬编码偏移（24pt, 20pt），在刘海屏设备上可能与安全区域重叠。

---

## 已排除项

以下原报告条目经核实后排除或合并：

| 原编号 | 原描述 | 排除原因 |
|--------|--------|----------|
| #6 | compactMap 结果越界 | 入口有 `childViewControllers.count == expectedCount` 检查，compactMap 后不会少于预期数量 |
| #7 | `result!` 强解包崩溃 | 信号量等待的真实风险是无限等待/卡住，不是 result 为 nil；signal 前必定赋值 |
| #21 | 搜索协调器 fallback 空 store | `?? RDEPUBChapterRuntimeStore()` 前的可选链若为 nil 则整个调用返回 nil，fallback 不会生效 |
| #23 | init 时加载所有 HTML 到内存 | 逐章取 HTML 算哈希后只保存 digest，HTML 字符串不长期保留 |
| #35 | `.nonPersistent()` 阻止 cookie/localStorage | 不持久化是有意设计，不是 bug；原始报告将"不持久化"误述为"不能用" |
| #48 | `didMoveToSuperview` 每次重复 makeUI | 有 `didBuildUI` 防重入保护 |
| 原L-04 | `activeTasks` 字典 `clearTask` 设 nil 不删键 | Swift 中 `dict[key] = nil` 等同于 `removeValue(forKey:)`，不保留空洞 |
| 原M-18 | MetadataParseWorker OperationQueue 未在 deinit 取消 | 外层 `[weak self]` guard 确保 self 存活才执行 queue 操作；`cancellationController` 提供显式取消路径 |
| 原L-08 | `ss_superViewController` 前缀暗示外部来源 | 命名风格猜测，非可验证缺陷 |

---

## 建议优先级排序

| 优先级 | 编号 | 修复复杂度 | 说明 |
|--------|------|-----------|------|
| P0 | H-01 | 低 | 在 `handleMemoryWarning` 中加一行 `chapterRuntimeStore.handleMemoryWarning()`，并在 controller 中转发 `didReceiveMemoryWarning` |
| P0 | H-04 | 中 | MetadataParseWorker 和 LoadCoordinator 中 `unowned context` 改为 `weak`，闭包加 `guard` |
| P0 | H-03 | 低 | `lastTextPaginationPageSize!` 改为 `guard let` 安全解包 |
| P1 | H-08 | 中 | URLSchemeHandler 回调改到与 start 相同队列，取消路径加 `didFailWithError` |
| P1 | H-02 | 中 | 主线程同步加载改为异步回调或确保不从主线程调用 |
| P1 | H-07 | 低 | 关键持久化操作加日志，至少记录失败原因 |
| P1 | H-10 | 低 | 给三个依赖加版本约束；移除 SnapKit 和 SSAlertSwift |
| P2 | H-05 | 中 | 为 ChapterDataCache 加 LRU 逐出策略或最大条目数限制 |
| P2 | H-06 | 低 | 为 DarkImageAdjuster.imageCache 设置 `totalCostLimit` |
| P2 | H-09 | 中 | 搜索改为流式/分批加载，避免一次性持有所有章节 |
| P2 | M-01/02 | 中 | 为 State 和 Store 关键属性加 `@MainActor` 或 `dispatchPrecondition` |
| P2 | M-04 | 低 | `assert` 改为 `dispatchPrecondition` 或 `precondition` |
| P2 | M-08 | 低 | 保留环加注释说明必须通过 `reset()` 打破 |
| P2 | M-15 | 中 | 迁移至 `UIEditMenuInteraction` |