认证 API

用户认证和授权相关的 API 接口

POST /api/auth/login

用户登录接口，返回 JWT 令牌

请求体

{
  "email": "user@example.com",
  "password": "password123"
}

响应示例

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "cld123...",
    "email": "user@example.com",
    "username": "john_doe"
  }
}
POST /api/auth/register

用户注册接口

请求体

{
  "email": "newuser@example.com",
  "username": "newuser",
  "password": "password123"
}

响应示例

{
  "id": "cld456...",
  "email": "newuser@example.com",
  "username": "newuser",
  "createdAt": "2025-01-24T10:30:00.000Z"
}
POST /api/auth/refresh

刷新 JWT 令牌

请求头

Authorization: Bearer <old-token>

响应示例

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 86400
}

用户 API

用户信息管理和状态相关的 API 接口

GET /api/users/profile

获取当前用户信息

请求头

Authorization: Bearer <token>

响应示例

{
  "id": "cld123...",
  "email": "user@example.com",
  "username": "john_doe",
  "avatar": "https://...",
  "status": "ONLINE",
  "createdAt": "2025-01-24T10:30:00.000Z"
}
PUT /api/users/profile

更新用户信息

请求体

{
  "username": "newusername",
  "avatar": "https://new-avatar.jpg"
}

响应示例

{
  "id": "cld123...",
  "username": "newusername",
  "avatar": "https://new-avatar.jpg",
  "updatedAt": "2025-01-24T11:00:00.000Z"
}
PUT /api/users/status

更新用户在线状态

请求体

{
  "status": "BUSY"  // ONLINE, OFFLINE, AWAY, BUSY
}

响应示例

{
  "id": "cld123...",
  "status": "BUSY",
  "lastSeen": "2025-01-24T11:00:00.000Z"
}

消息 API

消息发送、接收和历史记录相关的 API 接口

POST /api/messages/send

发送消息

请求体

{
  "content": "Hello World!",
  "room": "general",
  "type": "TEXT",  // TEXT, IMAGE, VIDEO, FILE
  "receiverId": "optional-user-id"
}

响应示例

{
  "id": "msg123...",
  "content": "Hello World!",
  "type": "TEXT",
  "room": "general",
  "senderId": "user123...",
  "createdAt": "2025-01-24T12:00:00.000Z",
  "sender": {
    "id": "user123...",
    "username": "john_doe",
    "avatar": "https://..."
  }
}
GET /api/messages/history?room=general&limit=50

获取聊天室消息历史

查询参数

room: string     // 聊天室名称
limit: number    // 消息数量限制 (默认 50)
offset: number   // 偏移量 (默认 0)

响应示例

{
  "messages": [
    {
      "id": "msg123...",
      "content": "Hello World!",
      "type": "TEXT",
      "sender": {
        "id": "user123...",
        "username": "john_doe",
        "avatar": "https://..."
      },
      "createdAt": "2025-01-24T12:00:00.000Z"
    }
  ],
  "total": 100,
  "hasMore": true
}
DELETE /api/messages/:id

删除消息

路径参数

id: string  // 消息 ID

响应示例

{
  "success": true,
  "message": "Message deleted successfully"
}

群组 API

群组管理和成员操作相关的 API 接口

POST /api/groups

创建群组

请求体

{
  "name": "开发团队",
  "description": "前端开发讨论组",
  "type": "public",  // public, private
  "avatar": "https://group-avatar.jpg"
}

响应示例

{
  "id": "grp123...",
  "name": "开发团队",
  "description": "前端开发讨论组",
  "type": "public",
  "creatorId": "user123...",
  "createdAt": "2025-01-24T13:00:00.000Z",
  "members": 1
}
GET /api/groups/:id

获取群组信息

路径参数

id: string  // 群组 ID

响应示例

{
  "id": "grp123...",
  "name": "开发团队",
  "description": "前端开发讨论组",
  "type": "public",
  "avatar": "https://group-avatar.jpg",
  "members": 15,
  "creator": {
    "id": "user123...",
    "username": "john_doe"
  },
  "createdAt": "2025-01-24T13:00:00.000Z"
}
POST /api/groups/:id/join

加入群组

路径参数

id: string  // 群组 ID

响应示例

{
  "success": true,
  "message": "Successfully joined the group",
  "groupId": "grp123..."
}

文件 API

文件上传、下载和管理相关的 API 接口

POST /api/files/upload

上传文件

请求格式

Content-Type: multipart/form-data

Form Data:
- file: (binary file data)
- type: "profile" | "message" | "group"
- targetId: string (optional)

响应示例

{
  "id": "file123...",
  "originalName": "document.pdf",
  "fileName": "upload_123456.pdf",
  "mimeType": "application/pdf",
  "size": 1024576,
  "url": "/uploads/upload_123456.pdf",
  "uploadedAt": "2025-01-24T14:00:00.000Z"
}
GET /api/files/:id/download

下载文件

路径参数

id: string  // 文件 ID

响应

二进制文件流
Content-Type: application/octet-stream
Content-Disposition: attachment; filename="document.pdf"

WebSocket 事件

实时通信相关的事件和消息格式

连接事件

客户端事件

// 连接到服务器
socket.emit('connect')

// 加入房间
socket.emit('joinRoom', {
  room: 'general'
})

// 离开房间
socket.emit('leaveRoom', {
  room: 'general'
})

// 发送消息
socket.emit('message', {
  room: 'general',
  content: 'Hello!',
  type: 'TEXT'
})

服务器事件

// 连接成功
socket.on('connected', () => {
  console.log('Connected to server')
})

// 加入房间成功
socket.on('joined', (data) => {
  console.log('Joined room:', data.room)
})

// 接收消息
socket.on('message', (message) => {
  console.log('New message:', message)
})

// 用户状态更新
socket.on('userStatus', (data) => {
  console.log('User status changed:', data)
})

消息格式 

// 消息对象结构
{
  "id": "msg123...",
  "content": "Hello World!",
  "type": "TEXT",  // TEXT, IMAGE, VIDEO, FILE
  "room": "general",
  "senderId": "user123...",
  "receiverId": "user456...",  // 私聊时使用
  "fileUrl": "https://...",    // 文件消息时使用
  "createdAt": "2025-01-24T12:00:00.000Z",
  "sender": {
    "id": "user123...",
    "username": "john_doe",
    "avatar": "https://...",
    "status": "ONLINE"
  },
  "status": "sent",  // sent, delivered, read
  "reactions": [],   // 表情反应
  "replies": []      // 回复消息
}

状态事件

正在输入

// 发送输入状态
socket.emit('typing', {
  room: 'general',
  isTyping: true
})

// 接收输入状态
socket.on('typing', (data) => {
  console.log(data.user + ' is typing...')
})

消息已读

// 标记消息已读
socket.emit('markRead', {
  messageIds: ['msg123', 'msg456']
})

// 接收已读回执
socket.on('messageRead', (data) => {
  console.log('Messages marked as read')
})

用户状态

// 更新用户状态
socket.emit('statusUpdate', {
  status: 'BUSY'  // ONLINE, OFFLINE, AWAY, BUSY
})

// 接收状态更新
socket.on('userStatus', (data) => {
  console.log('User status:', data.status)
})