Phoenix.Sync 开源项目教程

1. 项目介绍

Phoenix.Sync 是一个为 Postgres 背后的 Phoenix 应用程序添加实时同步功能的库。它能够将数据同步到 LiveView 和前端网页及移动应用程序中。Phoenix.Sync 与 Plug 以及 Phoenix 的 Controller、LiveView、Router 和 Stream 等模块集成，使用 ElectricSQL 作为核心同步、扇出和数据传递的解决方案。它可以将 Ecto.Query 映射到 Shapes 以实现部分复制。

2. 项目快速启动

环境准备

在开始之前，确保你的系统中已经安装了 Elixir 和 PostgreSQL。

添加依赖

将 Phoenix.Sync 添加到你的 mix.exs 文件中的依赖项：

defp deps do
  [
    {:phoenix_sync, "~> 0.4"}
  ]
end

配置

在 config/config.exs 文件中配置 Phoenix.Sync：

config :phoenix_sync, 
  env: config_env(),
  mode: :embedded,
  repo: MyApp.Repo

确保在你的应用程序中包含 Phoenix.Sync：

children = [
  MyApp.Repo,
  # ...
  {MyApp.Endpoint, phoenix_sync: Phoenix.Sync.plug_opts()}
]

快速同步示例

以下是一个 Phoenix.Controller 中使用 Phoenix.Sync 的快速示例：

defmodule Phoenix.Sync.LiveViewTest.TodoController do
  use Phoenix.Controller
  import Phoenix.Sync.Controller

  def show(conn, %{"id" => id}) do
    query = from(t in Todos.Todo, where: t.id == ^id)
    sync_render(conn, query)
  end
end

3. 应用案例和最佳实践

实时更新 LiveView

使用 Phoenix.Sync.LiveView.sync_stream/4 函数可以在 LiveView 中实现自动的数据同步更新：

defmodule MyWeb.MyLive do
  use Phoenix.LiveView
  import Phoenix.Sync.LiveView

  def mount(_params, _session, socket) do
    {:ok, assign(socket, :todos, sync_stream(socket, :todos, Todos.Todo))}
  end

  def handle_info({:sync, event}, socket) do
    {:noreply, sync_stream_update(socket, event)}
  end
end

通过 Router 暴露形状

使用 Phoenix.Sync.Router.sync/2 宏在 Router 中静态（编译时）定义形状：

defmodule MyWeb.Router do
  use Phoenix.Router
  import Phoenix.Sync.Router

  pipeline :sync do
    plug :my_auth
  end

  scope "/shapes" do
    pipe_through :sync
    sync "/todos", Todos.Todo
  end
end

前端消费形状

前端可以使用 Electric 的 TypeScript 客户端同步数据：

import { Shape, ShapeStream } from "@electric-sql/client";

const stream = new ShapeStream({ url: "/shapes/todos" });
const shape = new Shape(stream);

shape.subscribe(data => {
  console.log(data);
});

4. 典型生态项目

Phoenix.Sync 的生态系统中包括了以下典型项目：

• ElectricSQL: Phoenix.Sync 依赖的核心库，用于数据同步。
• TanStack/db: 一个前端数据库，可以与 Phoenix.Sync 配合使用进行本地乐观更新。
• Phoenix: Phoenix 框架，用于构建实时应用程序。