排课系统帮助中心

锦中排课系统WebSocket API为开发者提供了一种高效、实时的通信方式，用于与排课系统进行数据交互。通过WebSocket协议，客户端可以与服务器建立持久化的双向通信通道，实现实时数据推送和响应。

本规范适用于需要与锦中排课系统进行实时数据同步的应用场景，例如课程安排更新、用户状态通知、系统状态监控等。

1. 连接建立

客户端需使用WebSocket协议连接到指定的服务器地址，格式如下：

ws://[host]:[port]/api/v1/websocket

其中，[host]为服务器IP或域名，[port]为WebSocket服务端口。

连接成功后，服务器会返回一个包含连接状态的握手消息，确认连接已建立。

2. 消息格式

所有消息均采用JSON格式进行传输，包含以下字段：

type: 消息类型（如：login, event, data, error）

data: 消息内容，根据type不同而变化

timestamp: 消息发送时间戳（毫秒）

示例消息结构：

{
  "type": "login",
  "data": {
    "token": "your_access_token"
  },
  "timestamp": 1698765432100
}
    

3. 事件类型

WebSocket API支持多种事件类型，具体如下：

login: 客户端登录请求，需携带认证Token

event: 系统事件通知，如课程变更、用户状态更新等

data: 数据请求响应，如获取排课信息、查询用户数据等

error: 错误消息，用于通知客户端异常情况

4. 消息处理

客户端在收到消息后，应根据消息类型进行相应处理：

对于login消息，客户端需验证Token有效性，并保持连接活跃

对于event消息，客户端应立即更新本地状态并触发相关逻辑

对于data消息，客户端应解析数据并展示给用户或进行进一步处理

对于error消息，客户端应记录错误日志并尝试重连或提示用户

5. 认证机制

所有WebSocket连接必须通过认证，客户端在连接时需携带有效的访问令牌（Token）。Token通常由系统授权接口生成，并在有效期内使用。

若Token失效或未提供，服务器将拒绝连接请求，并返回相应的错误代码。

6. 错误处理

当发生错误时，服务器将发送error类型的消息，包含以下字段：

code: 错误代码（如：401, 500, 404）

message: 错误描述信息

常见错误代码说明：

401: 未授权，Token无效或缺失

404: 资源不存在或路径错误

500: 服务器内部错误

7. 重连机制

建议客户端实现自动重连机制，以应对网络中断或服务器重启等情况。重连策略可包括：

在连接断开后，等待一定时间后重新尝试连接

对连续失败的连接进行指数退避处理

在重连成功后，重新发送必要的初始化请求

8. 示例代码

以下是一个简单的JavaScript客户端连接示例：

const socket = new WebSocket('ws://example.com:8080/api/v1/websocket');

socket.onopen = () => {
  console.log('Connected to WebSocket server');
  const loginMsg = {
    type: 'login',
    data: { token: 'your_token_here' },
    timestamp: Date.now()
  };
  socket.send(JSON.stringify(loginMsg));
};

socket.onmessage = (event) => {
  const message = JSON.parse(event.data);
  if (message.type === 'event') {
    console.log('Received event:', message.data);
  }
};

socket.onerror = (error) => {
  console.error('WebSocket error:', error);
};
    

9. 注意事项

请确保客户端与服务器的时间同步，以避免因时间偏差导致的逻辑错误

避免频繁发送大量数据，以免影响系统性能

建议在开发环境中测试WebSocket连接，确保其稳定性

10. 版本说明

当前版本为v1.0，后续版本可能会增加新的功能或调整现有接口。建议开发者关注官方文档更新。