ReadViewSDK/.planning/codebase/CONVENTIONS.md

编码规范

分析日期： 2026-05-21

说明：本仓库以 iOS/Swift 为主，未检测到统一的 lint/format 工具配置；代码风格在不同模块/年代间存在差异。.planning/ 下的文档按项目规则使用中文描述，但代码标识符保持英文。

语言与工程约束

• 主要语言：Swift（Podspec 声明 s.swift_versions = ["5.10"]，见 RDReaderView.podspec）
• 最低系统版本：Podspec iOS 15.0（RDReaderView.podspec），示例工程 Podfile/构建设置里常见为 iOS 15.6（Podfile）
• 依赖管理：CocoaPods（Podfile、ReadViewDemo/Podfile、Podfile.lock）

命名约定

文件/类型命名（Swift）：

• 以类型名为文件名的单文件组织较常见：Sources/RDReaderView/EPUBCore/RDEPUBParser.swift
• 大量使用前缀区分模块域：
  • RD...：阅读器 UI/控制器相关（如 Sources/RDReaderView/RDReaderView.swift、Sources/RDReaderView/RDURLReaderController.swift）
  • RDEPUB...：EPUB Core/UI/渲染相关（如 Sources/RDReaderView/EPUBCore/RDEPUBModels.swift）
• Extension 文件使用 + 命名：Sources/RDReaderView/LegacyRDReaderController/RDReaderController+EPUBText.swift

变量/函数命名：

• 基本遵循 Swift lowerCamelCase：parse(epubURL:)（Sources/RDReaderView/EPUBCore/RDEPUBParser.swift）
• UI 代码中常见简写：imageV（Sources/RDReaderView/LegacyRDReaderController/RDReaderCoverView.swift）
• 常量多用 static let：epubPaginationCacheStorageKey（Sources/RDReaderView/LegacyRDReaderController/RDReaderController.swift）

代码风格与排版（从现有代码归纳）

缩进与换行：

• 多数文件使用 4 空格缩进（示例：ReadViewDemo/ReadViewDemo/ViewController.swift、Sources/RDReaderView/EPUBCore/RDEPUBModels.swift）
• 历史代码中更常见“强制换行/多行括号”风格（示例：Sources/RDReaderView/LegacyRDReaderController/RDReaderController.swift 的 CGRect(...)）

空行与分组：

• UI 相关文件常用空行分隔属性/初始化/布局段落（示例：Sources/RDReaderView/LegacyRDReaderController/RDReaderCoverView.swift）
• // MARK: 用于分区组织（示例：Sources/RDReaderView/RDReaderGestureController.swift、Sources/RDReaderView/LegacyRDReaderController/RDReaderController.swift、Sources/RDReaderView/EPUBTextRendering/RDPlainTextBookBuilder.swift）

类型组织：

• 偏好用 extension 拆分职责/协议实现（示例：ReadViewDemo/ReadViewDemo/ViewController.swift 的 UITableViewDataSource/Delegate）
• API 暴露处使用 public、public final class、public enum/struct（示例：Sources/RDReaderView/EPUBCore/RDEPUBModels.swift）
• “对外只读、内部可写”常用 public internal(set)（示例：Sources/RDReaderView/EPUBCore/RDEPUBParser.swift）

导入与依赖使用

import：

• UIKit/UI 文件：import UIKit（大量文件）
• Core/模型文件：import Foundation（如 Sources/RDReaderView/EPUBCore/RDEPUBModels.swift）
• 三方依赖按需引入：
  • SnapKit：布局（如 Sources/RDReaderView/LegacyRDReaderController/RDReaderCoverView.swift）
  • SSAlertSwift：弹窗/提示（如 Sources/RDReaderView/LegacyRDReaderController/RDReaderController.swift）

Pods 目录说明：

• ReadViewDemo/Pods/** 为依赖源码/生成配置，通常不作为本仓库代码风格的“标准样式”参考。

错误处理与日志

• Core 解析层倾向用 throws + 自定义 Error（示例：Sources/RDReaderView/EPUBCore/RDEPUBParser.swift、Sources/RDReaderView/EPUBCore/RDEPUBModels.swift 的 RDEPUBParserError）
• UI/控制器层常见 guard 早返回（示例：ReadViewDemo/ReadViewDemo/ViewController.swift）
• 未检测到统一日志框架（未发现专用 logging package/config）；出现时以系统 API/局部输出为主（需按具体文件核对）。

注释与文档

• 项目规则（强约束）：代码标识符保持英文，但代码注释/文档/提交信息使用中文（见 CONTEXT.md）。
• 历史文件常带 Xcode 头部注释块（示例：Sources/RDReaderView/RDReaderView.swift、Sources/RDReaderView/LegacyRDReaderController/RDReaderCoverView.swift）。
• 公共 API 处存在少量三斜线文档注释（示例：Sources/RDReaderView/RDReaderView.swift 的中文说明）。

Lint / Formatter / 静态检查

未检测到（仓库根与常见位置）：

• SwiftLint 配置：.swiftlint.yml / swiftlint.yml
• SwiftFormat 配置：.swiftformat
• 通用格式化配置：.editorconfig
• 其他：ESLint/Prettier/Biome 等（本仓库非 JS/TS 主体）

可执行的工程级格式化/检查：

• 主要依赖 Xcode（或 Swift 编译器）自身检查；如需引入 SwiftLint/SwiftFormat，应先新增对应配置文件并在 CI/构建脚本中接入。

Evidence（关键证据文件）

• CONTEXT.md
• Podfile
• RDReaderView.podspec
• ReadViewDemo/ReadViewDemo/ViewController.swift
• Sources/RDReaderView/RDReaderView.swift
• Sources/RDReaderView/LegacyRDReaderController/RDReaderController.swift
• Sources/RDReaderView/LegacyRDReaderController/RDReaderCoverView.swift
• Sources/RDReaderView/EPUBCore/RDEPUBParser.swift
• Sources/RDReaderView/EPUBCore/RDEPUBModels.swift
• ReadViewDemo/ReadViewDemo.xcodeproj/project.pbxproj