# ReadSDK 代码规范 ## 适用范围 本文档适用于 `ReadSDK` 新增代码与重构代码。 - 规范覆盖 `Sources/` 与 `RDReaderDemo/` 中的 Swift 代码。 - 命名、分层与职责边界以 SDK 可维护性和可扩展性为优先。 - 本文档分为两类内容： - `已观察到的约定`：当前工程常见写法。 - `建议统一的规范`：后续统一执行的规则。 ## 新架构目录与职责 ### 已观察到的约定 - `Sources/RDReaderView`：阅读核心容器、翻页能力与基础视图。 - `EPUBCore`：EPUB 解析、资源定位、导航状态、分页与会话协调。 - `EPUBTextRendering`：文本渲染引擎与分页支持。 - `EPUBUI`：可开箱即用的 Reader UI 层。 - `RDReaderDemo`：示例应用与调试入口。 ### 建议统一的规范 - 新增业务能力优先归入 `Sources/RDReaderView` 下的对应模块目录。 - `Core` 层只承载解析、会话、状态机与通用能力，不写页面级交互。 - `UI` 层只承载展示、事件分发和轻量状态同步，不直接处理底层解析逻辑。 - 若模块持续膨胀，优先在当前模块下继续拆分子文件，不跨目录散落实现。 ## 命名规范 ### 已观察到的约定 - 当前工程历史命名以 `SS`、`RDEPUB` 开头。 - 控制器常用 `...Controller`，视图常用 `...View`，会话对象常用 `...Session`。 - 扩展文件采用 `类型名+功能域.swift`，如 `Parser+Archive.swift`。 - 事件方法常使用 `Action` 结尾，例如 `pageTapAction()`、`themeChangeAction()`。 - 绑定数据的方法常使用 `bind`、`update`、`refresh`、`configure` 等动词。 ### 建议统一的规范 - **所有新增类型必须以 `RD` 开头。** - EPUB 相关类型统一以 `RDEPUB` 开头。 - 方法名、变量名沿用 Swift 小驼峰，不增加额外前缀。 - 类型名应反映职责，不使用过宽泛的后缀；只有真正承担协调逻辑时才使用 `Manager`、`Handler`。 - 事件处理方法统一使用"对象/意图 + Action"命名，例如 `pageTapAction`、`themeChangeAction`。 - 数据绑定方法优先使用以下语义： - `bind...`：将模型绑定到视图或模块。 - `update...`：增量刷新已有界面或状态。 - `configure...`：一次性配置样式或依赖。 - `refresh...`：重新拉取或重建数据状态。 - 避免新增拼写不一致的方法名；若发现历史命名拼写错误，新增代码必须使用正确拼写，旧接口修复时应配合调用点一起调整。 命名示例： - `RDReaderView` - `RDEPUBParser` - `RDEPUBPublication` - `RDEPUBReadingSession` - `RDEPUBReaderController` - `RDEPUBReaderTheme` 扩展文件命名示例： ```text RDEPUBParser.swift RDEPUBParser+Archive.swift RDEPUBParser+Package.swift RDEPUBParser+TOC.swift RDEPUBParser+Resources.swift RDEPUBWebView.swift RDEPUBWebView+Configuration.swift RDEPUBWebView+Reflowable.swift ``` ## 分层与职责边界 ### 已观察到的约定 - 阅读入口负责容器装配、翻页模式切换和事件分发。 - EPUB 核心层负责解析、导航、分页、资源读取与定位。 - 渲染层负责 HTML/富文本渲染与分页支持。 - UI 层负责主题、工具栏、目录、设置等交互能力。 ### 建议统一的规范 - `RD...Controller`：负责页面级编排与流程调度，不承载复杂渲染细节。 - `RD...View`：负责展示与局部交互，不承载完整业务流程。 - `RDEPUB...Core`：负责解析、会话状态与数据模型，不依赖具体页面。 - 配置、主题、定位、进度模型统一下沉为 `struct`。 - 跨层通信优先通过会话层或协议，不做跨层直接写状态。 ## UI 与布局规范 ### 已观察到的约定 - 视图多采用 `lazy var` 初始化，并在闭包内完成默认配置。 - 自定义 View 通常在 `init(frame:)` 或业务绑定后调用 `initView()` 完成视图树搭建。 - 复杂页面使用分区 extension 组织代理与事件实现。 - 页面或组件内部按职责拆分样式方法，例如 `topBarStyle()`、`contentStyle()`。 - 页面经常通过回调闭包把交互抛给外层，例如 `pageChangeCallback`、`selectionCallback`。 - 模块内存在多处布局方式混用情况。 ### 建议统一的规范 - SDK 层新增 UI 使用 Auto Layout 原生约束，Demo 层可使用 SnapKit；单文件内不混用多套布局体系。 - 视图层初始化顺序保持一致： - 定义属性与子视图 - 在 `initView()` 中组装视图树 - 在独立方法中拆分样式和状态刷新逻辑 - 当约束会被多次切换时： - 首次创建使用 `makeConstraints`（SnapKit）或 `NSLayoutConstraint` - 重建结构使用 `remakeConstraints`（SnapKit）或先移除再添加 - 仅修改常量时使用 `updateConstraints`（SnapKit）或修改 `constant` 属性 - 布局分支明显时，优先拆成语义化私有方法，不要把所有状态分支堆在一个超长方法里。 - 对外暴露的 UI 刷新入口建议以 `bind` 或 `update` 开头，避免把布局细节暴露给调用方。 - 交互事件通过闭包或 delegate 抛出，避免子视图持有上层业务依赖。 ## 交互与状态处理规范 ### 已观察到的约定 - 事件处理使用 `@objc` + selector。 - 异步回调中广泛使用 `[weak self]`。 - 状态判断常通过 `guard` 提前返回。 ### 建议统一的规范 - 按钮、通知、系统回调放入独立 extension 分组。 - 异步闭包默认先使用 `[weak self]`，仅在必要时改强引用。 - 多前置条件入口统一先 `guard` 校验，减少嵌套。 - 导航与进度恢复统一通过 `RDEPUBReadingSession` 协调。 ## 代码风格细则 ### 已观察到的约定 - extension 分区较常见。 - 解析与渲染模型多数采用 `struct`。 - 存在少量历史命名不统一与可选值处理不一致情况。 ### 建议统一的规范 - 默认遵循”最小可见性”：`private` > `fileprivate` > `internal` > `public`。 - 纯数据模型使用 `struct` + `Codable` + `Equatable`。 - 服务对象使用 `final class`，避免无意义继承。 - 错误类型统一使用 `enum + LocalizedError`。 - 新增代码避免强制解包；若当前上下文无法避免，至少先在上层收敛边界。 - 统一优先使用 `guard` 做前置失败处理，减少深层嵌套。 - extension 的拆分原则以”单一职责”优先： - 事件处理一组 - 代理 / DataSource 实现一组 - 工具方法一组 - 通知适配一组 - 调试代码继续使用 `#if DEBUG` 包裹，不把调试边框、日志、测试分支直接带入正式逻辑。 ## 文件组织规范 ### 已观察到的约定 - 目录按阅读容器、EPUB Core、渲染、UI 分层组织。 - 大类通过 `+Extension` 文件拆分职责。 ### 建议统一的规范 - 目录保持以下分层，不跨层放置实现： - `Sources/RDReaderView/EPUBCore` - `Sources/RDReaderView/EPUBTextRendering` - `Sources/RDReaderView/EPUBUI` - 单文件建议不超过 `600` 行；超出后按职责拆分 extension 文件。 - extension 文件命名统一 `RD类型名+功能域.swift`。 ## 注释规范 - 注释、错误提示、日志统一使用中文。 - 关键流程方法保留”为什么这样做”的注释，不写重复代码字面行为的注释。 - 调试输出统一放在 `#if DEBUG` 下。 - 新代码保留有信息量的注释，避免重复描述显而易见的代码行为。 ## 已观察到的项目模式 ### 模式 1：统一入口 + 扩展拆分 - `RDEPUBParser` 负责 EPUB 解析主入口，不同能力拆到 `+Archive`、`+Package`、`+TOC`、`+Resources` 等扩展文件。 - `RDEPUBReadingSession` 负责阅读会话主入口，状态管理、分页、定位等能力拆到扩展文件。 - 该模式适合继续用于解析器、会话管理、控制器工具方法等横向能力。 ### 模式 2：页面编排在 Controller，局部交互下沉到 View - `RDEPUBReaderController` 负责阅读页整体编排：翻页容器装配、工具栏切换、阅读位置恢复。 - `RDReaderView` 负责分页容器布局与翻页交互，并通过 DataSource / Delegate 把数据需求交回外层。 - 该模式保持 Controller 管流程、View 管展示的职责分离。 ### 模式 3：列表与容器逻辑通过扩展拆开 - 复杂容器将 `UICollectionViewDataSource`、`UICollectionViewDelegate`、`UICollectionViewDelegateFlowLayout` 分别拆分到 extension。 - 该模式降低单文件中主逻辑与代理逻辑的耦合，适合继续用于任何包含列表或容器的组件。 ### 模式 4：渲染路径抽象 - `RDEPUBReadingProfile` 根据 EPUB 特征自动选择渲染路径（`webFixedLayout` / `webInteractive` / `textReflowable`）。 - 新增渲染相关功能时，必须评估对三种路径的覆盖情况。 ## 待统一项 - 当前访问控制级别存在混用：同一类里 `public`、默认 `internal`、`private` 并存，建议后续新增代码默认从最小可见范围开始声明。 - 当前存在少量强制解包，建议新增代码优先通过前置校验收敛风险。 - 当前存在拼写不一致问题，建议后续新增代码统一使用标准英文单词，旧接口如需修复应配合调用点一起调整。 - 当前部分注释偏”过程说明”或遗留调试注释，建议新代码保留有信息量的注释。 - 当前个别 View 在数据绑定阶段再次调用 `initView()` 重建界面，这种方式在复杂组件中容易引入重复添加子视图或状态不一致。建议新增组件优先区分”初始化视图结构”和”刷新数据状态”两个阶段。 ## 禁忌事项 | 禁忌 | 替代做法 | |------|----------| | 新增类型不加 `RD` 前缀 | 所有新增类型统一 `RD` / `RDEPUB` 前缀 | | UI 层直接拼装解析状态 | 通过 `RDEPUBReadingSession` 获取状态 | | 控制器直接操作底层解析细节 | 通过 `RDEPUBPublication`、`RDEPUBParser` 暴露接口 | | 强制解包可选值 | `guard let` / `if let` | | 用页号单独恢复阅读进度 | 统一使用 `href + progression` | ## 使用建议 - 新增功能前先确定目录归属和职责边界。 - 命名先定前缀再落代码：类型一律 `RD` 开头。 - 若需迁移历史 `SS` 前缀，按模块渐进替换，优先替换新增与重构触达文件。 ## 旧 SS 命名迁移到 RD 的分阶段执行清单 ### 阶段 0：冻结新增 SS 命名（立即执行） - 目标：从当前时点开始，不再引入新的 `SS`/`RDEPUB` 类型名。 - 动作： - 新增类型统一使用 `RD`/`RDEPUB` 前缀。 - Code Review 增加命名检查项：发现新增 `SS` 命名必须驳回。 - 在 PR 模板中加入“本次是否新增旧前缀命名”勾选项。 - 验收： - 新提交代码中，新增类型 `SS` 前缀数量为 `0`。 ### 阶段 1：建立迁移映射表（第 1 周） - 目标：明确“旧名 -> 新名”一一映射，避免多人并行改名冲突。 - 动作： - 统计核心公开类型、内部核心类型、测试类型三类清单。 - 建立命名映射表，例如： - `RDReaderView` -> `RDReaderView` - `RDEPUBParser` -> `RDEPUBParser` - `RDEPUBReadingSession` -> `RDEPUBReadingSession` - 对外 API 单独标记“需兼容过渡”的类型。 - 验收： - 映射表覆盖全部高频核心类型，且团队评审通过。 ### 阶段 2：先迁移内部类型（第 2-3 周） - 目标：优先改内部实现，降低外部兼容压力。 - 动作： - 按模块分批迁移：`EPUBCore` -> `EPUBTextRendering` -> `EPUBUI`。 - 每批次只改一个子模块，避免超大 PR。 - 同步修复调用点、扩展文件名与注释中的旧命名。 - 验收： - 目标模块内类型命名全部满足 `RD` 规则。 - 编译通过，Demo 阅读主流程可用。 ### 阶段 3：迁移公开 API 并保留兼容层（第 3-4 周） - 目标：完成对外接口改名，同时给接入方提供平滑升级窗口。 - 动作： - 对外公开类型切换为 `RD` 命名。 - 旧公开类型保留兼容别名，并标注废弃说明（`deprecated`）。 - 在 Release Note 提供“旧名/新名对照表”和迁移示例。 - 验收： - 新接入示例仅使用 `RD` 命名。 - 旧接入代码在兼容期内无需立即改动即可编译。 ### 阶段 4：清理兼容层与收口（下一主版本） - 目标：在约定主版本移除旧前缀，完成命名收口。 - 动作： - 删除 `SS` 兼容别名与过渡代码。 - 清理文档、注释、示例工程中的旧前缀残留。 - 对外发布最终迁移公告与升级说明。 - 验收： - 工程内无 `SS`/`RDEPUB` 类型定义残留。 - 文档与示例代码全部为 `RD`/`RDEPUB` 命名。 ### 迁移过程约束 - 每次迁移 PR 必须包含： - 命名改动清单 - 影响范围说明 - 回归验证结果（编译、Demo 主流程、关键阅读路径） - 禁止在同一 PR 中同时做“大规模命名迁移 + 业务逻辑重构”。 - 若改名会影响外部接入，必须先补迁移文档再合并代码。