); } function getRandomColor(): string { const colors = ['#ef4444', '#f97316', '#22c55e', '#3b82f6', '#8b5cf6']; return colors[Math.floor(Math.random() * colors.length)]; } ``` ### 4.2 应用入口 ```typescript // packages/client/src/App.tsx import { useState } from 'react'; import { CollaborativeEditor } from './components/CollaborativeEditor'; export default function App() { const [joined, setJoined] = useState(false); const [roomName, setRoomName] = useState('default-room'); const [userName, setUserName] = useState(''); if (!joined) { return ( ); } return ( ); } ``` ### 4.3 Vite配置 ```typescript // packages/client/vite.config.ts import { defineConfig } from 'vite'; import react from '@vitejs/plugin-react'; export default defineConfig({ plugins: [react()], server: { port: 5173, proxy: { '/ws': { target: 'ws://localhost:1234', ws: true, }, }, }, }); ``` ### 预期结果 ```bash cd packages/client pnpm install pnpm dev ``` 打开浏览器 `http://localhost:5173`，输入用户名并加入房间，打开第二个标签页模拟第二个用户，两人即可看到实时编辑同步。 ## 第五步：数据流与同步机制详解 理解数据在系统中如何流转是排查问题和优化的关键： ```mermaid sequenceDiagram participant U1 as 用户A participant C1 as 客户端A participant WS as WebSocket服务器 participant C2 as 客户端B participant U2 as 用户B Note over U1,U2: 初始连接阶段 U1->>C1: 输入文字 C1->>C1: Yjs生成Update(Uint8Array) C1->>WS: 发送Update WS->>WS: Y.applyUpdate()到服务端副本 WS->>C2: 广播Update Note over U1,U2: 冲突场景 U1->>C1: 在位置5插入"X" U2->>C2: 在位置5插入"Y" C1->>WS: Update A (唯一ID: A-timestamp) C2->>WS: Update B (唯一ID: B-timestamp) WS->>WS: CRDT自动合并 WS->>C1: 转发Update B WS->>C2: 转发Update A C1->>C1: CRDT合并 → "XY" 或 "YX"（确定性） C2->>C2: CRDT合并 → 相同结果 Note over U1,U2: 离线恢复 C1--xWS: 网络断开 U1->>C1: 继续编辑（离线） C1->>C1: 本地累积Updates C1->>WS: 网络恢复后发送累积Updates WS->>WS: 合并离线变更 WS->>C2: 广播合并结果 ``` ### Yjs Update的二进制格式 Yjs使用高效的二进制编码传输变更： ```typescript // 调试：观察Update内容 import * as Y from 'yjs'; import * as encoding from 'lib0/encoding'; const doc = new Y.Doc(); doc.on('update', (update: Uint8Array) => { console.log(`Update大小: ${update.byteLength} bytes`); console.log(`Update内容:`, Array.from(update.slice(0, 20))); }); // 手动合并两个文档状态 function mergeStates(base: Uint8Array, diff: Uint8Array): Uint8Array { const doc = new Y.Doc(); Y.applyUpdate(doc, base); Y.applyUpdate(doc, diff); return Y.encodeStateAsUpdate(doc); } ``` ## 第六步：生产级扩展 — Redis Pub/Sub 当WebSocket服务需要水平扩展时，多个服务实例间需要通过Redis同步消息。 向Claude Code输入： > **"给服务端添加Redis Pub/Sub支持，使多个WebSocket实例可以跨进程同步Yjs文档更新"** ```typescript // packages/server/src/redis-sync.ts import Redis from 'ioredis'; import * as Y from 'yjs'; import { DocManager } from './doc-manager.js'; export class RedisSync { private pub: Redis; private sub: Redis; constructor( private redisUrl: string, private docManager: DocManager, ) { this.pub = new Redis(redisUrl); this.sub = new Redis(redisUrl); } async init(): Promise { await this.sub.psubscribe('yjs:update:*'); this.sub.on('pmessage', (_pattern, channel, message) => { const roomName = channel.replace('yjs:update:', ''); const update = new Uint8Array(JSON.parse(message)); const doc = this.docManager.getOrCreateDoc(roomName); Y.applyUpdate(doc, update); }); } broadcast(roomName: string, update: Uint8Array): void { const channel = `yjs:update:${roomName}`; this.pub.publish(channel, JSON.stringify(Array.from(update))); } async disconnect(): Promise { await this.pub.quit(); await this.sub.quit(); } } ``` **扩展架构**： ```mermaid graph TB LB[负载均衡器 / Nginx] --> WS1[WebSocket实例 1] LB --> WS2[WebSocket实例 2] LB --> WS3[WebSocket实例 N] WS1 <--> Redis[(Redis Pub/Sub)] WS2 <--> Redis WS3 <--> Redis Redis --> PG[(PostgreSQL
文档持久化)] WS1 <--> C1[客户端 A/B] WS2 <--> C2[客户端 C/D] WS3 <--> C3[客户端 E/F] style Redis fill:#dc382d,color:#fff style PG fill:#336791,color:#fff style LB fill:#009639,color:#fff ``` ## 第七步：测试策略 ### 7.1 让Claude Code生成测试 向Claude Code输入： > **"为packages/server/src/doc-manager.ts编写单元测试，覆盖文档创建、持久化、清理场景，使用vitest"** Claude Code会根据代码自动生成测试： ```typescript // packages/server/src/__tests__/doc-manager.test.ts import { describe, it, expect, beforeEach, afterEach } from 'vitest'; import * as Y from 'yjs'; import { DocManager } from '../doc-manager.js'; import { promises as fs } from 'fs'; import path from 'path'; describe('DocManager', () => { const testDataDir = './test-data'; let manager: DocManager; beforeEach(async () => { process.env.DATA_DIR = testDataDir; manager = new DocManager(); await fs.mkdir(testDataDir, { recursive: true }); }); afterEach(async () => { await fs.rm(testDataDir, { recursive: true, force: true }); }); it('创建并返回新文档', () => { const doc = manager.getOrCreateDoc('test-room'); expect(doc).toBeInstanceOf(Y.Doc); }); it('同一房间返回同一文档实例', () => { const doc1 = manager.getOrCreateDoc('same-room'); const doc2 = manager.getOrCreateDoc('same-room'); expect(doc1).toBe(doc2); }); it('文档变更后自动持久化', async () => { const doc = manager.getOrCreateDoc('persist-test'); doc.getText('content').insert(0, 'Hello CRDT'); // 等待防抖保存（2秒 + 缓冲） await new Promise(resolve => setTimeout(resolve, 3000)); const filePath = path.join(testDataDir, 'persist-test.yjs'); const data = await fs.readFile(filePath); expect(data.length).toBeGreaterThan(0); // 验证能正确加载 const newDoc = new Y.Doc(); Y.applyUpdate(newDoc, new Uint8Array(data)); expect(newDoc.getText('content').toString()).toBe('Hello CRDT'); }); }); ``` ### 7.2 并发冲突测试 ```typescript // packages/server/src/__tests__/crdt-conflict.test.ts import { describe, it, expect } from 'vitest'; import * as Y from 'yjs'; describe('CRDT冲突解决', () => { it('两个客户端同时编辑同一位置，结果一致', () => { // 模拟两个独立客户端 const docA = new Y.Doc(); const docB = new Y.Doc(); const textA = docA.getText('content'); const textB = docB.getText('content'); // 初始同步 const initState = Y.encodeStateAsUpdate(docA); Y.applyUpdate(docB, initState); // 同时在位置0插入不同内容 textA.insert(0, 'AAA'); textB.insert(0, 'BBB'); // 双向同步 Y.applyUpdate(docA, Y.encodeStateAsUpdate(docB)); Y.applyUpdate(docB, Y.encodeStateAsUpdate(docA)); // 结果必须一致 expect(textA.toString()).toBe(textB.toString()); expect(textA.toString().length).toBe(6); // AAA + BBB }); it('离线编辑后重连，状态正确合并', () => { const docA = new Y.Doc(); const docB = new Y.Doc(); const textA = docA.getText('content'); const textB = docB.getText('content'); // 初始同步 Y.applyUpdate(docB, Y.encodeStateAsUpdate(docA)); // A离线编辑 textA.insert(0, 'Offline-Edit '); // B在线编辑 textB.insert(0, 'Online-Edit '); // 重连后同步 Y.applyUpdate(docA, Y.encodeStateAsUpdate(docB)); Y.applyUpdate(docB, Y.encodeStateAsUpdate(docA)); expect(textA.toString()).toBe(textB.toString()); }); }); ``` 运行测试： ```bash cd packages/server && pnpm test ``` ## 第八步：使用Claude Code驱动整个开发的工作流技巧 本教程的核心不仅是技术实现，更是展示如何用Claude Code高效完成复杂全栈项目。 ### 8.1 分层Prompt策略 ```mermaid flowchart TD A[第1轮: 架构设计] --> B["Prompt: 设计协作编辑器的
系统架构和数据流"] B --> C[Claude Code生成
CLAUDE.md + 架构文档] C --> D[第2轮: 服务端实现] D --> E["Prompt: 基于架构实现
WebSocket服务端"] E --> F[Claude Code生成
server代码] F --> G[第3轮: 前端实现] G --> H["Prompt: 实现React前端
集成Monaco + Yjs"] H --> I[Claude Code生成
client代码] I --> J[第4轮: 测试与扩展] J --> K["Prompt: 编写测试
添加Redis扩展"] K --> L[Claude Code生成
测试 + Redis模块] ``` ### 8.2 关键Prompt模式 | 阶段 | Prompt示例 | 效果 | |------|-----------|------| | 初始化 | "创建pnpm monorepo，包含server和client两个包，配置TypeScript" | 一次性生成完整项目骨架 | | 架构讨论 | "我要构建实时协作编辑器，请先分析技术选型：OT vs CRDT，帮我选择并给出理由" | Claude Code给出分析而非直接写代码 | | 分步实现 | "先实现doc-manager.ts，只关注文档生命周期管理" | 避免一次性生成过多代码 | | 问题排查 | "运行服务端后客户端连接报错 `WebSocket is not open`，请分析可能原因" | Claude Code结合上下文排查 | | 代码审查 | "审查doc-manager.ts，检查是否有内存泄漏风险" | 利用Claude Code的代码理解能力 | | 测试生成 | "为presence-manager.ts编写测试，覆盖用户加入、离开、光标更新" | 自动生成针对性测试 | ### 8.3 上下文管理技巧 长对话中上下文管理至关重要： ```bash # 定期压缩上下文，保留关键信息 /compact # 当需要Claude Code重新理解项目结构时 "请重新阅读CLAUDE.md和packages/server/src/index.ts，然后继续" # 使用worktree隔离实验性改动 "在worktree中实验Monaco Editor的多光标API，不要影响主分支" ``` ## 完整实战案例：部署到生产环境 ### Docker Compose 一键部署 ```yaml # docker-compose.yml version: '3.8' services: server: build: context: ./packages/server dockerfile: Dockerfile ports: - "1234:1234" environment: - PORT=1234 - REDIS_URL=redis://redis:6379 - DATA_DIR=/data volumes: - doc-data:/data depends_on: - redis client: build: context: ./packages/client dockerfile: Dockerfile ports: - "80:80" depends_on: - server redis: image: redis:7-alpine ports: - "6379:6379" volumes: - redis-data:/data volumes: doc-data: redis-data: ``` ```dockerfile # packages/server/Dockerfile FROM node:20-alpine AS builder WORKDIR /app COPY package.json pnpm-lock.yaml ./ RUN corepack enable && pnpm install --frozen-lockfile COPY . . RUN pnpm build FROM node:20-alpine WORKDIR /app COPY --from=builder /app/dist ./dist COPY --from=builder /app/node_modules ./node_modules COPY --from=builder /app/package.json ./ EXPOSE 1234 CMD ["node", "dist/index.js"] ``` ### 部署命令 ```bash # 本地测试 docker compose up --build # 生产部署 docker compose -f docker-compose.prod.yml up -d ``` ## 总结：技术栈全景 ```mermaid graph TB subgraph 前端["前端 (React + Monaco)"] M[Monaco Editor] --> YB[Yjs Binding] YB --> WP[WebSocket Provider] WP --> AW[Awareness Protocol
光标/选区同步] end subgraph 服务端["服务端 (Node.js)"] WSS[WebSocket Server] --> DM[DocManager
文档生命周期] WSS --> PM[PresenceManager
用户感知] DM --> PERSIST[持久化层] PERSIST --> FS[文件系统 / S3] PERSIST --> PG[PostgreSQL] end subgraph 扩展层["生产扩展"] RS[Redis Pub/Sub] --> WSS1[实例 1] RS --> WSS2[实例 2] RS --> WSS3[实例 N] end WP -->|二进制Update| WSS WSS -->|广播| WP DM -.->|跨实例同步| RS style 前端 fill:#1a1b26,color:#a9b1d6 style 服务端 fill:#2d2f3f,color:#a9b1d6 style 扩展层 fill:#1e3a5f,color:#a9b1d6 ``` ## 延伸阅读 - **Yjs官方文档** — [yjs.dev](https://yjs.dev/) — CRDT库的完整API参考和生态工具 - **CRDT: The Hard Parts** — [josephg.com](https://josephg.com/crdts-go-brrr/) — 深入理解CRDT实现中的工程挑战 - **Monaco Editor + Yjs集成指南** — [docs.yjs.dev/ecosystem/editor-bindings/monaco](https://docs.yjs.dev/ecosystem/editor-bindings/monaco) — 编辑器绑定的官方文档 - **WebSocket扩展模式** — [ably.com/blog/scaling-pub-sub-with-websockets-and-redis](https://ably.com/blog/scaling-pub-sub-with-websockets-and-redis) — 生产级WebSocket水平扩展 - **Claude Code项目结构最佳实践** — [claudearchitect.com/docs/claude-code/project-structure](https://claudearchitect.com/docs/claude-code/project-structure/) — monorepo组织方式 ## 训练营适用性评估 | 维度 | 说明 | |------|------| | 适合训练营类型 | 全栈工程师训练营、实时系统专题班、AI辅助开发工作坊 | | 预计教学时长 | 6-8小时（含动手实践） | | 难度等级 | 中高级 | | 分段建议 | 第1-3步（3h）：基础架构 → 第4-5步（2h）：前端集成 → 第6-8步（2h）：生产扩展 | | 学员要求 | 需提前掌握React Hooks和Node.js基础 | | 评估方式 | 最终交付：能支持3+人同时在线编辑、离线重连不丢数据的协作编辑器 | ## 参考来源 1. [Mastering Real-Time Collaborative Editing with Yjs and WebSockets](https://dev.to/hexshift/mastering-real-time-collaborative-editing-with-yjs-and-websockets-12n) — Yjs + WebSocket协作编辑器完整教程，包含代码示例 2. [Beyond WebSockets: Architecting Multiplayer SaaS with CRDTs](https://smarttechdevs.in/blog/multiplayer-saas-architecture-websockets-crdts-yjs) — CRDT在B2B SaaS中的架构设计，深入解析"Last Write Wins"问题 3. [Building a Real-Time Collaborative Code Editor with WebSockets and CRDTs](https://www.samahshakir.dev/blog/real-time-collaborative-editor-websockets-crdt) — 包含Redis Pub/Sub跨实例同步的完整生产架构代码 4. [Scaling WebSocket Applications with Redis Pub/Sub for Horizontal Deployment](https://dev.to/hexshift/scaling-websocket-applications-with-redis-pubsub-for-horizontal-deployment-2mb2) — WebSocket水平扩展的Redis Pub/Sub实现方案 5. [Build a Real-Time Collaborative AI Writing Tool with WebSockets and Claude](https://levelup.gitconnected.com/build-a-real-time-collaborative-ai-writing-tool-with-websockets-and-claude-d34b52fd6095) — Claude API与WebSocket结合构建AI协作写作工具 > [!tip] 51学通信知识星球 > **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。 > **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。 > **当前规模**：5200 篇主题 / 990 个回答，198 元/年。 > **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。 > **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。