aheh/PrivyDrop

Fork 0

Files

T

david_bai 571b1cddcf update doc

2025-07-03 20:22:46 +08:00

9.1 KiB

Raw Blame History

Privydrop 前端架构文档

一、架构总览

1.1 项目愿景

Privydrop 是一个基于 WebRTC 的 P2P 文件/文本分享工具，旨在提供一个安全、私密、高效的在线分享解决方案。前端架构的核心目标是构建一个高性能、易于维护、可扩展的现代化 Web 应用，并遵循 Next.js 的最佳实践。

1.2 设计理念

在最近的重构中，我们确立了以"关注点分离"和"逻辑内聚"为核心的设计理念：

UI 与逻辑分离: 视图（Components）应尽可能保持"纯粹"，仅负责渲染 UI 和响应用户交互。所有复杂的业务逻辑、状态管理和副作用都应从组件中剥离。
Hooks 作为业务逻辑核心: 自定义 React Hooks 是我们组织业务逻辑和状态的第一公民。每个 Hook 封装一个独立的、高内聚的功能模块（如 WebRTC 连接、房间管理），使得逻辑单元可复用、可测试，并极大地简化了组件树。
分层架构: 代码库遵循清晰的分层结构，确保不同层次的职责单一，降低模块间的耦合度。

1.3 核心技术栈

框架: Next.js 14 (App Router)
语言: TypeScript
UI: React 18, Tailwind CSS, shadcn/ui (基于 Radix UI)
状态管理: 以自定义 React Hooks 为核心的模块化状态管理
WebRTC 信令: Socket.IO Client
数据获取: React Server Components (RSC), Fetch API
国际化: next/server 中间件 + 动态 JSON 字典
内容: MDX (用于博客和静态内容页面)

1.4 高阶分层模型

应用的前端架构可大致分为四个层次：

graph TD
    A["<b>① 应用与路由层 (app/)</b><br/><br/>页面、布局、路由、国际化中间件、数据获取"]
    B["<b>② UI与组件层 (components/)</b><br/><br/>协调器组件、UI 面板、通用组件、基础 UI 元素"]
    C["<b>③ 业务逻辑与状态层 (hooks/)</b><br/><br/>WebRTC 连接、房间管理、文件传输、剪贴板操作等"]
    D["<b>④ 核心库与工具层 (lib/)</b><br/><br/>底层 WebRTC 封装、文件处理、工具函数、API 客户端"]

    style A fill:#f9f9f9,stroke:#333,stroke-width:1px
    style B fill:#f9f9f9,stroke:#333,stroke-width:1px
    style C fill:#f9f9f9,stroke:#333,stroke-width:1px
    style D fill:#f9f9f9,stroke:#333,stroke-width:1px

    A --> B --> C --> D

① 应用与路由层: 由 Next.js App Router 管理，负责页面渲染、路由控制、国际化和初始数据获取。
② UI 与组件层: 负责所有用户界面的展示。它消费来自下一层 (Hooks) 的状态和方法，并将用户交互事件向上传递。
③ 业务逻辑与状态层: 这是应用的"大脑"。通过一系列自定义 Hooks，封装了所有核心功能的业务逻辑和状态。
④ 核心库与工具层: 提供最底层的、与框架无关的纯粹功能，如 WebRTC 的底层封装、API 请求等。

二、核心功能实现：P2P 文件/文本传输

本节将详细阐述应用最核心的 P2P 传输功能是如何通过不同架构层次协同实现的。

2.1 整体流程

用户操作 (components): 用户在 SendTabPanel 或 RetrieveTabPanel 中进行操作（如选择文件、输入房间号）。
逻辑处理 (hooks): useFileTransferHandler 和 useRoomManager 等 Hooks 捕捉这些操作，管理相关状态（如待发送文件列表），并调用 useWebRTCConnection Hook 提供的连接方法。
连接建立 (hooks -> lib): useWebRTCConnection 调用 lib/webrtc_*.ts 中的底层方法，通过 Socket.IO 信令服务器与对端协商，建立 RTCPeerConnection。
数据传输 (lib): 连接建立后，lib/fileSender.ts 和 lib/fileReceiver.ts 负责将文件分片、序列化，并通过 RTCDataChannel 进行传输。
状态更新与回调 (lib -> hooks -> components): 传输过程中，lib 层通过回调函数（如进度更新）通知 hooks 层更新状态，hooks 层的状态变化最终驱动 components 层的 UI 重新渲染。

2.2 模块详解

WebRTC 底层封装 (lib/):
- webrtc_base.ts: 封装了与 Socket.IO 信令服务器的交互、RTCPeerConnection 的通用管理（ICE、连接状态）和 RTCDataChannel 的创建，是所有 WebRTC 操作的基石。
- fileSender.ts / fileReceiver.ts: 负责文件/文本的发送和接收逻辑，包括元数据交换、文件分块、进度计算、数据拼接和文件保存等。
WebRTC 业务逻辑封装 (hooks/):
- useWebRTCConnection.ts: 连接的"中枢管理员"。它初始化和管理 sender 和 receiver 实例，处理连接生命周期，并向上层提供一个简洁的 API（如 broadcastDataToAllPeers）和状态（如 peerCount, sendProgress）。
- useRoomManager.ts: 房间的"状态机"。负责房间 ID 的创建、验证（带防抖）、加入逻辑，并管理房间相关的 UI 状态文本。
- useFileTransferHandler.ts: 传输内容的"数据中心"。管理待发送/已接收的文本和文件，处理文件添加/移除/下载等用户操作，并为 useWebRTCConnection 提供处理接收数据的回调函数。
UI 协调与展示 (components/):
- ClipboardApp.tsx: 核心应用的"总协调员"。它不包含任何业务逻辑，其唯一职责是集成上述所有核心 Hooks，然后将从 Hooks 中获取的状态和回调函数作为 props 分发给具体的 UI 子组件。此外，它还负责监听全局的拖放（Drag and Drop）事件，并在用户拖动文件至窗口任意位置时，渲染一个全屏的拖放区域，极大地提升了文件上传的体验。
- SendTabPanel.tsx / RetrieveTabPanel.tsx: 纯粹的 UI 展示组件，负责渲染发送和接收面板，并响应用户的输入。
- FileListDisplay.tsx: 用于展示文件列表和传输状态。
- FullScreenDropZone.tsx: 一个简单的 UI 组件，用于在全局拖拽文件时显示一个全屏的、半透明的覆盖层，为用户提供清晰的视觉反馈。

三、应用层详细架构

3.1 目录结构与职责

frontend/app/: 应用核心路由和页面。
- [lang]/: 实现多语言动态路由。
  - layout.tsx: 全局布局，提供 Provider (Theme, i18n)。
  - page.tsx: 主页入口，渲染 HomeClient。
  - HomeClient.tsx: (客户端组件) 承载核心应用 ClipboardApp 和其他营销展示组件。
- config/: 应用配置。
  - api.ts: 统一封装与后端 API 的交互。
  - environment.ts: 管理环境变量和运行时配置（如 ICE 服务器）。
frontend/components/: UI 组件库。
- ClipboardApp/: ClipboardApp 拆分出的所有 UI 子组件。实现了关注点分离。
- common/: 可在项目中多处复用的通用组件 (如 YouTubePlayer)。
- ui/: (来自 shadcn/ui) 基础原子组件。
- web/: 网站页面级别的大型静态组件 (如 Header, Footer)。
- Editor/: 自定义富文本编辑器。
frontend/hooks/: 业务逻辑和状态管理的核心。上面已详述。
frontend/lib/: 核心库与工具函数。
- webrtc_*.ts, fileSender.ts, fileReceiver.ts: WebRTC 核心。
- dictionary.ts: 国际化字典加载。
- utils.ts, fileUtils.ts: 通用工具函数。其中 fileUtils.ts 包含了如 traverseFileTree 等用于处理文件和文件夹的核心逻辑。
frontend/types/: 全局 TypeScript 类型定义。
frontend/constants/: 应用范围内的常量，主要是 i18n 配置和消息文件。

3.2 状态管理策略

项目以自定义 React Hooks 为核心进行模块化状态管理。我们刻意避免了引入全局状态管理库（如 Redux, Zustand），理由如下：

降低复杂性: 对于当前应用规模，全局状态会引入不必要的复杂性。
促进内聚: 将相关联的状态和逻辑封装在同一个 Hook 内，使得代码更易于理解和维护。
利用 React 原生能力: 通过 Context 和 Props 传递由 Hooks 管理的状态，足以满足当前所有需求。

3.3 国际化 (i18n)

路由驱动: 通过 URL 路径 (/[lang]/) 实现语言切换。
自动检测: middleware.ts 拦截请求，根据 Accept-Language 头或 Cookie 自动重定向到合适的语言路径。
动态加载: lib/dictionary.ts 中的 getDictionary 函数根据 lang 参数异步加载对应的 messages/*.json 文件，实现了代码分割。

四、总结与展望

当前的前端架构通过分层设计和以 Hooks 为中心的逻辑封装，成功地将一个复杂的 WebRTC 应用拆解为一系列清晰、可维护的模块。UI、业务逻辑和底层库之间的界限分明，为未来的功能扩展和维护奠定了坚实的基础。

未来可优化的方向包括：

增加单元/集成测试: 为核心的 Hooks (useWebRTCConnection 等) 和 lib 中的工具类编写测试用例。
Bundle 分析: 定期使用 @next/bundle-analyzer 分析打包体积，寻找优化点。
组件库完善: 持续沉淀和打磨 components/common 中的通用组件。

9.1 KiB Raw Blame History