Primus 中文教程

1. 核心概念

Primus 是一个实时通信框架，它为各种实时通信库（如 Socket.io、SockJS 等）提供了一个统一的抽象层。通过使用 Primus，开发者可以编写一次代码，然后在不同的实时通信库之间无缝切换，而不需要修改应用代码。

1.1 主要特点

统一抽象层：为多种实时通信库提供一致的 API
插件系统：支持通过插件扩展功能
跨库兼容：可以在不同的实时通信库之间无缝切换
可扩展性：易于扩展和定制
性能优化：内置性能优化

1.2 技术栈特点

抽象层：提供了对底层实时通信库的抽象
插件系统：支持通过插件扩展功能
跨库兼容：兼容多种实时通信库
可扩展：易于扩展和定制

2. 安装配置

2.1 安装

使用 npm 安装 Primus：

npm install primus

2.2 基本配置

首先，创建一个基本的 Primus 服务器：

const http = require('http');
const express = require('express');
const Primus = require('primus');

// 创建 Express 应用
const app = express();
const server = http.createServer(app);

// 创建 Primus 实例
const primus = new Primus(server, {
  transformer: 'websockets', // 使用 websockets 作为传输方式
  parser: 'JSON' // 使用 JSON 作为解析器
});

// 启动服务器
server.listen(3000, () => {
  console.log('服务器运行在 http://localhost:3000');
});

2.3 支持的传输方式

Primus 支持多种传输方式，包括：

websockets：原生 WebSocket
sockjs：SockJS
engine.io：Engine.io（Socket.io 的底层传输库）
browserchannel：BrowserChannel
faye：Faye

3. 基本使用

3.1 服务器端

3.1.1 连接管理

// 监听连接事件
primus.on('connection', (spark) => {
  console.log('新连接:', spark.id);
  
  // 发送消息给客户端
  spark.write('欢迎连接到 Primus 服务器！');
  
  // 监听客户端消息
  spark.on('data', (data) => {
    console.log('收到消息:', data);
    
    // 回复客户端
    spark.write('服务器收到消息:', data);
  });
  
  // 监听断开连接事件
  spark.on('end', () => {
    console.log('连接断开:', spark.id);
  });
});

3.1.2 广播消息

// 广播消息给所有连接的客户端
primus.write('这是一条广播消息');

// 广播消息给特定客户端
primus.forEach((spark, id) => {
  if (id !== 'exclude_id') {
    spark.write('这是一条定向广播消息');
  }
});

3.2 客户端

3.2.1 基本连接

首先，需要从服务器获取 Primus 客户端库：

<script src="/primus/primus.js"></script>
<script>
  // 创建 Primus 客户端实例
  const primus = Primus.connect('http://localhost:3000');
  
  // 监听连接事件
  primus.on('open', () => {
    console.log('连接已建立');
    
    // 发送消息给服务器
    primus.write('Hello from client!');
  });
  
  // 监听服务器消息
  primus.on('data', (data) => {
    console.log('收到服务器消息:', data);
  });
  
  // 监听断开连接事件
  primus.on('end', () => {
    console.log('连接已断开');
  });
</script>

4. 高级功能

4.1 插件系统

Primus 提供了强大的插件系统，可以通过插件扩展功能。

4.1.1 创建插件

// 创建一个简单的插件
function myPlugin() {
  return function (primus) {
    // 扩展 Primus 实例
    primus.$.myPlugin = {
      sayHello: function () {
        return 'Hello from my plugin!';
      }
    };
    
    // 监听连接事件
    primus.on('connection', (spark) => {
      // 扩展 spark 实例
      spark.$.myPlugin = {
        clientId: spark.id
      };
    });
  };
}

// 使用插件
primus.use('myPlugin', myPlugin());

4.1.2 使用内置插件

Primus 内置了一些有用的插件，例如：

primus-emitter：提供事件发射器功能
primus-rooms：提供房间功能
primus-resource：提供资源管理功能

4.2 房间系统

使用 primus-rooms 插件实现房间功能：

// 安装插件
npm install primus-rooms

// 使用插件
const Rooms = require('primus-rooms');
primus.use('rooms', Rooms);

// 服务器端
primus.on('connection', (spark) => {
  // 加入房间
  spark.join('room1', (err) => {
    if (err) {
      console.error('加入房间失败:', err);
      return;
    }
    console.log('加入房间成功');
    
    // 向房间发送消息
    spark.room('room1').write('有人加入了房间');
  });
  
  // 离开房间
  spark.leave('room1', (err) => {
    if (err) {
      console.error('离开房间失败:', err);
      return;
    }
    console.log('离开房间成功');
  });
});

4.3 认证

实现基本的认证功能：

// 服务器端
primus.on('connection', (spark) => {
  // 验证连接
  spark.on('data', (data) => {
    if (data.type === 'auth') {
      // 验证令牌
      if (data.token === 'valid-token') {
        spark.write({ type: 'auth', status: 'success' });
        // 标记为已认证
        spark.authorized = true;
      } else {
        spark.write({ type: 'auth', status: 'error', message: '无效的令牌' });
        // 断开连接
        spark.end();
      }
    } else {
      // 检查是否已认证
      if (!spark.authorized) {
        spark.write({ type: 'error', message: '请先认证' });
        return;
      }
      
      // 处理其他消息
      console.log('收到消息:', data);
    }
  });
});

// 客户端
primus.on('open', () => {
  // 发送认证信息
  primus.write({ type: 'auth', token: 'valid-token' });
});

primus.on('data', (data) => {
  if (data.type === 'auth') {
    if (data.status === 'success') {
      console.log('认证成功');
      // 认证成功后发送其他消息
      primus.write({ type: 'message', content: 'Hello after auth!' });
    } else {
      console.error('认证失败:', data.message);
    }
  } else {
    console.log('收到服务器消息:', data);
  }
});

4.4 消息广播

实现高级消息广播功能：

// 广播给所有客户端
primus.write('广播给所有客户端');

// 广播给特定房间的客户端
primus.room('room1').write('广播给 room1 的客户端');

// 广播给除了特定客户端之外的所有客户端
primus.forEach((spark, id) => {
  if (id !== spark.id) {
    spark.write('广播给除了自己之外的所有客户端');
  }
});

4.5 性能优化

4.5.1 使用二进制数据

// 服务器端
primus.on('connection', (spark) => {
  // 发送二进制数据
  const buffer = Buffer.from('Hello, binary world!');
  spark.write(buffer);
});

// 客户端
primus.on('data', (data) => {
  if (data instanceof ArrayBuffer) {
    // 处理二进制数据
    const decoder = new TextDecoder();
    const text = decoder.decode(data);
    console.log('收到二进制数据:', text);
  } else {
    console.log('收到其他数据:', data);
  }
});

4.5.2 使用连接池

// 配置连接池
const primus = new Primus(server, {
  transformer: 'websockets',
  parser: 'JSON',
  pool: {
    max: 100, // 最大连接数
    min: 10,  // 最小连接数
    idle: 30000 // 空闲超时时间（毫秒）
  }
});

5. 最佳实践

5.1 代码组织

将 Primus 相关代码组织成模块：

// primus.js
const Primus = require('primus');
const Rooms = require('primus-rooms');

function createPrimus(server) {
  const primus = new Primus(server, {
    transformer: 'websockets',
    parser: 'JSON'
  });
  
  // 使用插件
  primus.use('rooms', Rooms);
  
  // 初始化事件处理
  initEvents(primus);
  
  return primus;
}

function initEvents(primus) {
  primus.on('connection', (spark) => {
    console.log('新连接:', spark.id);
    
    // 处理认证
    spark.on('data', (data) => {
      if (data.type === 'auth') {
        // 处理认证逻辑
      }
    });
    
    // 处理断开连接
    spark.on('end', () => {
      console.log('连接断开:', spark.id);
    });
  });
}

module.exports = createPrimus;

// 使用
const http = require('http');
const express = require('express');
const createPrimus = require('./primus');

const app = express();
const server = http.createServer(app);
const primus = createPrimus(server);

server.listen(3000, () => {
  console.log('服务器运行在 http://localhost:3000');
});

5.2 错误处理

实现完善的错误处理：

// 服务器端
primus.on('connection', (spark) => {
  spark.on('data', (data) => {
    try {
      // 处理消息
      console.log('收到消息:', data);
      spark.write('处理成功');
    } catch (error) {
      console.error('处理消息时出错:', error);
      spark.write({ type: 'error', message: '处理消息时出错' });
    }
  });
  
  spark.on('error', (error) => {
    console.error('连接错误:', error);
  });
});

// 客户端
primus.on('error', (error) => {
  console.error('客户端错误:', error);
});

5.3 安全性

5.3.1 使用 HTTPS

const https = require('https');
const fs = require('fs');
const express = require('express');
const Primus = require('primus');

// 读取 SSL 证书
const options = {
  key: fs.readFileSync('key.pem'),
  cert: fs.readFileSync('cert.pem')
};

// 创建 Express 应用
const app = express();
const server = https.createServer(options, app);

// 创建 Primus 实例
const primus = new Primus(server, {
  transformer: 'websockets',
  parser: 'JSON'
});

server.listen(3000, () => {
  console.log('HTTPS 服务器运行在 https://localhost:3000');
});

5.3.2 实现速率限制

// 安装速率限制插件
npm install express-rate-limit

// 使用速率限制
const rateLimit = require('express-rate-limit');

const limiter = rateLimit({
  windowMs: 15 * 60 * 1000, // 15 分钟
  max: 100 // 每个 IP 限制 100 个请求
});

app.use(limiter);

6. 实际应用

6.1 实时聊天应用

创建一个简单的实时聊天应用：

6.1.1 服务器端

const http = require('http');
const express = require('express');
const Primus = require('primus');
const Rooms = require('primus-rooms');

// 创建 Express 应用
const app = express();
const server = http.createServer(app);

// 创建 Primus 实例
const primus = new Primus(server, {
  transformer: 'websockets',
  parser: 'JSON'
});

// 使用房间插件
primus.use('rooms', Rooms);

// 静态文件服务
app.use(express.static('public'));

// 处理连接
primus.on('connection', (spark) => {
  console.log('新连接:', spark.id);
  
  // 加入默认房间
  spark.join('general', (err) => {
    if (err) {
      console.error('加入房间失败:', err);
      return;
    }
    console.log(`${spark.id} 加入了 general 房间`);
  });
  
  // 处理消息
  spark.on('data', (data) => {
    console.log('收到消息:', data);
    
    if (data.type === 'join_room') {
      // 加入房间
      spark.join(data.room, (err) => {
        if (err) {
          console.error('加入房间失败:', err);
          spark.write({ type: 'error', message: '加入房间失败' });
          return;
        }
        spark.write({ type: 'join_room', status: 'success', room: data.room });
        console.log(`${spark.id} 加入了 ${data.room} 房间`);
      });
    } else if (data.type === 'leave_room') {
      // 离开房间
      spark.leave(data.room, (err) => {
        if (err) {
          console.error('离开房间失败:', err);
          spark.write({ type: 'error', message: '离开房间失败' });
          return;
        }
        spark.write({ type: 'leave_room', status: 'success', room: data.room });
        console.log(`${spark.id} 离开了 ${data.room} 房间`);
      });
    } else if (data.type === 'message') {
      // 发送消息到房间
      if (data.room) {
        primus.room(data.room).write({
          type: 'message',
          user: data.user,
          content: data.content,
          timestamp: new Date().toISOString()
        });
      } else {
        // 发送到所有房间
        primus.write({
          type: 'message',
          user: data.user,
          content: data.content,
          timestamp: new Date().toISOString()
        });
      }
    }
  });
  
  // 处理断开连接
  spark.on('end', () => {
    console.log('连接断开:', spark.id);
  });
});

// 启动服务器
server.listen(3000, () => {
  console.log('服务器运行在 http://localhost:3000');
});

6.1.2 客户端

创建 public/index.html 文件：

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Primus 实时聊天</title>
  <style>
    body {
      font-family: Arial, sans-serif;
      margin: 0;
      padding: 0;
      background-color: #f0f0f0;
    }
    .container {
      max-width: 800px;
      margin: 0 auto;
      padding: 20px;
      background-color: white;
      border-radius: 5px;
      box-shadow: 0 0 10px rgba(0, 0, 0, 0.1);
      margin-top: 20px;
    }
    h1 {
      text-align: center;
      color: #333;
    }
    .chat-box {
      height: 400px;
      overflow-y: scroll;
      border: 1px solid #ddd;
      padding: 10px;
      margin-bottom: 10px;
      border-radius: 5px;
    }
    .message {
      margin-bottom: 10px;
      padding: 10px;
      background-color: #f9f9f9;
      border-radius: 5px;
    }
    .message .user {
      font-weight: bold;
      color: #333;
    }
    .message .content {
      margin-top: 5px;
      color: #666;
    }
    .message .timestamp {
      font-size: 0.8em;
      color: #999;
      text-align: right;
      margin-top: 5px;
    }
    .input-box {
      display: flex;
      margin-bottom: 10px;
    }
    .input-box input {
      flex: 1;
      padding: 10px;
      border: 1px solid #ddd;
      border-radius: 5px;
      margin-right: 10px;
    }
    .input-box button {
      padding: 10px 20px;
      background-color: #4CAF50;
      color: white;
      border: none;
      border-radius: 5px;
      cursor: pointer;
    }
    .input-box button:hover {
      background-color: #45a049;
    }
    .room-selector {
      margin-bottom: 10px;
    }
    .room-selector select {
      padding: 10px;
      border: 1px solid #ddd;
      border-radius: 5px;
      margin-right: 10px;
    }
    .room-selector button {
      padding: 10px 20px;
      background-color: #2196F3;
      color: white;
      border: none;
      border-radius: 5px;
      cursor: pointer;
    }
    .room-selector button:hover {
      background-color: #0b7dda;
    }
  </style>
</head>
<body>
  <div class="container">
    <h1>Primus 实时聊天</h1>
    
    <div class="room-selector">
      <label for="room">选择房间：</label>
      <select id="room">
        <option value="general">general</option>
        <option value="tech">tech</option>
        <option value="random">random</option>
      </select>
      <button id="join-room">加入房间</button>
    </div>
    
    <div class="chat-box" id="chat-box"></div>
    
    <div class="input-box">
      <input type="text" id="message-input" placeholder="输入消息...">
      <button id="send-button">发送</button>
    </div>
  </div>
  
  <script src="/primus/primus.js"></script>
  <script>
    // 创建 Primus 实例
    const primus = Primus.connect('http://localhost:3000');
    
    // 获取 DOM 元素
    const chatBox = document.getElementById('chat-box');
    const messageInput = document.getElementById('message-input');
    const sendButton = document.getElementById('send-button');
    const roomSelect = document.getElementById('room');
    const joinRoomButton = document.getElementById('join-room');
    
    // 用户名
    const username = '用户' + Math.floor(Math.random() * 1000);
    
    // 监听连接事件
    primus.on('open', () => {
      console.log('连接已建立');
      addMessage('系统', '连接已建立，欢迎来到聊天房间！', new Date().toISOString());
    });
    
    // 监听消息
    primus.on('data', (data) => {
      console.log('收到消息:', data);
      
      if (data.type === 'message') {
        addMessage(data.user, data.content, data.timestamp);
      } else if (data.type === 'join_room') {
        if (data.status === 'success') {
          addMessage('系统', `您已加入 ${data.room} 房间`, new Date().toISOString());
        }
      } else if (data.type === 'error') {
        addMessage('系统', `错误: ${data.message}`, new Date().toISOString());
      }
    });
    
    // 监听断开连接
    primus.on('end', () => {
      console.log('连接已断开');
      addMessage('系统', '连接已断开', new Date().toISOString());
    });
    
    // 发送消息
    sendButton.addEventListener('click', () => {
      const message = messageInput.value.trim();
      if (message) {
        primus.write({
          type: 'message',
          user: username,
          content: message,
          room: roomSelect.value
        });
        messageInput.value = '';
      }
    });
    
    // 按 Enter 键发送消息
    messageInput.addEventListener('keypress', (e) => {
      if (e.key === 'Enter') {
        sendButton.click();
      }
    });
    
    // 加入房间
    joinRoomButton.addEventListener('click', () => {
      const room = roomSelect.value;
      primus.write({
        type: 'join_room',
        room: room
      });
    });
    
    // 添加消息到聊天框
    function addMessage(user, content, timestamp) {
      const messageDiv = document.createElement('div');
      messageDiv.className = 'message';
      messageDiv.innerHTML = `
        <div class="user">${user}</div>
        <div class="content">${content}</div>
        <div class="timestamp">${new Date(timestamp).toLocaleString()}</div>
      `;
      chatBox.appendChild(messageDiv);
      chatBox.scrollTop = chatBox.scrollHeight;
    }
  </script>
</body>
</html>

6.2 React 集成

将 Primus 集成到 React 应用中：

6.2.1 安装依赖

npm install primus react react-dom

6.2.2 创建 Primus 客户端

// src/PrimusClient.js
import { useEffect, useRef, useState } from 'react';

const usePrimus = (url) => {
  const primusRef = useRef(null);
  const [isConnected, setIsConnected] = useState(false);
  const [messages, setMessages] = useState([]);
  
  useEffect(() => {
    // 动态加载 Primus 客户端
    const script = document.createElement('script');
    script.src = `${url}/primus/primus.js`;
    script.onload = () => {
      // 创建 Primus 实例
      primusRef.current = Primus.connect(url);
      
      // 监听连接事件
      primusRef.current.on('open', () => {
        console.log('连接已建立');
        setIsConnected(true);
      });
      
      // 监听消息
      primusRef.current.on('data', (data) => {
        console.log('收到消息:', data);
        setMessages(prev => [...prev, data]);
      });
      
      // 监听断开连接
      primusRef.current.on('end', () => {
        console.log('连接已断开');
        setIsConnected(false);
      });
    };
    
    document.body.appendChild(script);
    
    // 清理
    return () => {
      if (primusRef.current) {
        primusRef.current.end();
      }
      document.body.removeChild(script);
    };
  }, [url]);
  
  // 发送消息
  const sendMessage = (data) => {
    if (primusRef.current && isConnected) {
      primusRef.current.write(data);
    }
  };
  
  return {
    primus: primusRef.current,
    isConnected,
    messages,
    sendMessage
  };
};

export default usePrimus;

6.2.3 创建 React 组件

// src/App.js
import React, { useState } from 'react';
import usePrimus from './PrimusClient';

function App() {
  const { isConnected, messages, sendMessage } = usePrimus('http://localhost:3000');
  const [inputMessage, setInputMessage] = useState('');
  const [username] = useState('用户' + Math.floor(Math.random() * 1000));
  
  const handleSendMessage = () => {
    if (inputMessage.trim()) {
      sendMessage({
        type: 'message',
        user: username,
        content: inputMessage.trim(),
        room: 'general'
      });
      setInputMessage('');
    }
  };
  
  return (
    <div className="App">
      <h1>Primus React 聊天</h1>
      <div className="status">
        连接状态: {isConnected ? '已连接' : '未连接'}
      </div>
      <div className="chat-box">
        {messages.map((message, index) => (
          <div key={index} className="message">
            {message.type === 'message' && (
              <>
                <div className="user">{message.user}</div>
                <div className="content">{message.content}</div>
                <div className="timestamp">
                  {new Date(message.timestamp).toLocaleString()}
                </div>
              </>
            )}
          </div>
        ))}
      </div>
      <div className="input-box">
        <input
          type="text"
          value={inputMessage}
          onChange={(e) => setInputMessage(e.target.value)}
          placeholder="输入消息..."
        />
        <button onClick={handleSendMessage}>发送</button>
      </div>
    </div>
  );
}

export default App;

7. 总结

Primus 是一个强大的实时通信框架，它通过提供统一的抽象层，使得开发者可以在不同的实时通信库之间无缝切换，而不需要修改应用代码。本文介绍了 Primus 的核心概念、安装配置、基本使用、高级功能、最佳实践和实际应用示例，希望能够帮助开发者更好地理解和使用 Primus。

7.1 主要优势

统一抽象层：为多种实时通信库提供一致的 API
插件系统：支持通过插件扩展功能
跨库兼容：可以在不同的实时通信库之间无缝切换
可扩展性：易于扩展和定制
性能优化：内置性能优化

7.2 适用场景

实时聊天应用：如本文示例所示
实时游戏：需要低延迟的实时通信
实时协作工具：如实时文档编辑
实时监控：如实时数据可视化
任何需要实时通信的应用

7.3 未来展望

Primus 作为一个成熟的实时通信框架，已经被广泛应用于各种实时应用中。随着 WebSocket 技术的不断发展和普及，Primus 也在不断进化，为开发者提供更加便捷、高效的实时通信解决方案。

通过本文的学习，相信开发者已经对 Primus 有了全面的了解，可以开始在实际项目中使用 Primus 构建实时应用了。