Supabase Realtime 实时通信指南：构建实时应用的核心技术

【免费下载链接】supabase-py Python Client for Supabase. Query Postgres from Flask, Django, FastAPI. Python user authentication, security policies, edge functions, file storage, and realtime data streaming. Good first issue. 项目地址: https://gitcode.com/gh_mirrors/su/supabase-py

Supabase Realtime 是 Supabase 生态系统中提供实时数据同步功能的核心模块，它允许开发者轻松构建具有实时更新能力的应用程序。通过 Supabase-py 库中的 Realtime 客户端，Python 开发者可以实现数据库变更监听、实时消息广播和用户在线状态跟踪等功能，为 Flask、Django 或 FastAPI 等应用添加实时交互体验。

为什么选择 Supabase Realtime？

Supabase Realtime 基于 WebSocket 技术实现，提供了高效、可靠的实时数据传输能力。它与 Supabase 其他服务（如身份验证、存储）无缝集成，让开发者能够快速构建全栈实时应用。相比传统的轮询方式，Supabase Realtime 具有更低的延迟和更高的性能，同时简化了实时功能的实现复杂度。

核心优势

• 即时数据同步：数据库变更实时推送到客户端，无需手动刷新
• 简单易用的 API：通过简洁的接口实现复杂的实时功能
• 双向通信：支持客户端向服务器发送消息和服务器向客户端推送更新
• 自动重连机制：网络中断后自动恢复连接，确保数据一致性
• 灵活的订阅策略：可以精确订阅特定表、列或行的变更

Supabase Realtime 的核心组件

Supabase Realtime 模块包含多个关键组件，共同构成了完整的实时通信系统：

AsyncRealtimeClient

AsyncRealtimeClient 是异步环境下的核心客户端类，负责管理 WebSocket 连接和消息处理。它支持异步/等待语法，非常适合与 FastAPI 等现代异步框架集成。

主要功能包括：

• 建立和管理 WebSocket 连接
• 创建和管理实时频道
• 处理连接状态变化
• 实现自动重连逻辑

相关代码实现位于 src/realtime/src/realtime/_async/client.py。

SyncRealtimeClient

SyncRealtimeClient 是同步环境下的客户端类，提供了与 AsyncRealtimeClient 类似的功能，但采用同步编程模型，适合传统的 Django 或 Flask 应用。

注意：部分高级功能可能仅在异步客户端中可用，如 src/realtime/src/realtime/_sync/client.py 中提到的某些特性。

RealtimeChannel

RealtimeChannel 代表一个实时通信频道，用于订阅特定的数据变更或消息广播。通过频道，开发者可以：

• 订阅数据库表的变更事件（INSERT、UPDATE、DELETE）
• 发送和接收广播消息
• 跟踪用户在线状态（Presence）

快速开始：使用 Supabase Realtime

要在 Python 项目中使用 Supabase Realtime，首先需要安装 supabase-py 库。如果还没有克隆仓库，可以使用以下命令：

git clone https://gitcode.com/gh_mirrors/su/supabase-py
cd supabase-py

基本使用流程

1. 创建 Realtime 客户端

from realtime import AsyncRealtimeClient

# 初始化异步 Realtime 客户端
client = AsyncRealtimeClient(REALTIME_URL, API_KEY)

2. 连接到 Realtime 服务器

await client.connect()

3. 创建并订阅频道

# 创建频道
channel = client.channel("my-channel")

# 订阅数据库变更
channel.postgres_changes(
    event="*",  # 监听所有事件：INSERT, UPDATE, DELETE
    schema="public",
    table="messages",
    callback=handle_changes  # 处理变更的回调函数
)

# 订阅广播消息
channel.broadcast(
    event="chat-message",
    callback=handle_broadcast  # 处理广播消息的回调函数
)

# 加入频道
await channel.subscribe()

4. 处理实时事件

async def handle_changes(payload):
    print("数据库变更:", payload)

async def handle_broadcast(payload):
    print("收到广播消息:", payload)

5. 发送广播消息

await channel.send(
    type="broadcast",
    event="chat-message",
    payload={"message": "Hello, Realtime!"}
)

6. 断开连接

await client.disconnect()

高级功能

Presence：用户在线状态跟踪

Supabase Realtime 提供了 Presence 功能，可以轻松实现用户在线状态跟踪：

# 加入 Presence 频道
channel = client.channel("user-presence")

# 订阅 Presence 状态变更
channel.presence().on_sync(handle_presence_sync)

# 设置用户状态
await channel.track({"user_id": "123", "status": "online"})

await channel.subscribe()

订阅特定数据变更

可以精确订阅特定表、列或行的变更，减少不必要的数据传输：

channel.postgres_changes(
    event="INSERT",  # 只监听插入事件
    schema="public",
    table="messages",
    filter="room_id=eq.10",  # 只监听 room_id 为 10 的记录
    callback=handle_new_message
)

常见问题与解决方案

连接稳定性问题

如果遇到连接不稳定的情况，可以调整重连参数：

client = AsyncRealtimeClient(
    REALTIME_URL, 
    API_KEY,
    retry_attempts=10,  # 最大重连次数
    retry_interval=1  # 初始重连间隔（秒）
)

性能优化

对于高频率更新的应用，可以考虑：

• 合理设置订阅范围，只监听必要的数据
• 实现客户端数据缓存策略
• 使用批量处理减少频繁更新

总结

Supabase Realtime 为 Python 开发者提供了强大而简单的实时通信能力，使得构建实时应用变得前所未有的容易。通过 AsyncRealtimeClient 和 SyncRealtimeClient，开发者可以在不同类型的 Python 应用中轻松集成实时功能，从简单的聊天应用到复杂的协作工具。

无论是需要实时显示数据更新，还是构建实时协作功能，Supabase Realtime 都能提供可靠、高效的解决方案。通过本文介绍的基本使用方法和高级功能，你可以开始构建自己的实时应用，并根据具体需求进一步探索 Supabase Realtime 的更多可能性。

要了解更多细节，可以查阅项目的官方文档和源代码：

• Realtime 模块源代码：src/realtime/
• Supabase 客户端集成：src/supabase/src/supabase/

【免费下载链接】supabase-py Python Client for Supabase. Query Postgres from Flask, Django, FastAPI. Python user authentication, security policies, edge functions, file storage, and realtime data streaming. Good first issue. 项目地址: https://gitcode.com/gh_mirrors/su/supabase-py