用于实现客户端-服务器关系中的服务器的行为模块。

GenServer 就像任何其他 Elixir 进程一样，可以用于保持状态、异步执行代码等等。使用此模块实现的通用服务器进程（GenServer）的优势在于它将具有一套标准的接口函数，并包括用于跟踪和错误报告的功能。它也将适合于监管树。

graph BT
    C(Client #3) ~~~ B(Client #2) ~~~ A(Client #1)
    A & B & C -->|request| GenServer
    GenServer -.->|reply| A & B & C

示例

GenServer 行为抽象了常见的客户端-服务器交互。开发人员只需要实现他们感兴趣的回调和功能。

让我们从一个代码示例开始，然后探索可用的回调。假设我们想用 GenServer 实现一个像堆栈一样的服务，允许我们压入和弹出元素。我们将通过实现三个回调来定制一个通用的 GenServer 模块。

init/1 将我们传递给 GenServer 的初始参数转换为 GenServer 的初始状态。handle_call/3 在服务器接收到同步的 pop 消息时触发，从堆栈中弹出元素并将其返回给用户。handle_cast/2 将在服务器接收到异步的 push 消息时触发，将元素压入堆栈

defmodule Stack do
  use GenServer

  # Callbacks

  @impl true
  def init(elements) do
    initial_state = String.split(elements, ",", trim: true)
    {:ok, initial_state}
  end

  @impl true
  def handle_call(:pop, _from, state) do
    [to_caller | new_state] = state
    {:reply, to_caller, new_state}
  end

  @impl true
  def handle_cast({:push, element}, state) do
    new_state = [element | state]
    {:noreply, new_state}
  end
end

我们将启动、消息传递和消息循环的进程机制留给 GenServer 行为，只关注堆栈实现。我们现在可以使用 GenServer API 通过创建进程并向其发送消息来与服务交互

# Start the server
{:ok, pid} = GenServer.start_link(Stack, "hello,world")

# This is the client
GenServer.call(pid, :pop)
#=> "hello"

GenServer.cast(pid, {:push, "elixir"})
#=> :ok

GenServer.call(pid, :pop)
#=> "elixir"

我们通过调用 start_link/2 来启动我们的 Stack，传递服务器实现的模块及其用逗号分隔的元素列表作为初始参数。GenServer 行为调用 init/1 回调来建立 GenServer 的初始状态。从这一点开始，GenServer 将控制权，所以我们通过在客户端发送两种类型的消息来与它交互。**call** 消息期望来自服务器的回复（因此是同步的），而 **cast** 消息则不期望。

每次调用 GenServer.call/3 都会产生一条消息，该消息必须由 GenServer 中的 handle_call/3 回调处理。一个 cast/2 消息必须由 handle_cast/2 处理。GenServer 支持 8 个回调，但只有 init/1 是必需的。

use GenServer

当你 use GenServer 时，GenServer 模块将设置 @behaviour GenServer 并定义一个 child_spec/1 函数，这样你的模块就可以用作监管树中的子节点。

客户端/服务器 API

尽管在上面的例子中我们使用了 GenServer.start_link/3 以及其他函数来直接启动和与服务器通信，但大多数情况下我们不会直接调用 GenServer 函数。相反，我们将调用包装在代表服务器公共 API 的新函数中。这些薄包装器被称为 **客户端 API**。

这是我们 Stack 模块的更好实现

defmodule Stack do
  use GenServer

  # Client

  def start_link(default) when is_binary(default) do
    GenServer.start_link(__MODULE__, default)
  end

  def push(pid, element) do
    GenServer.cast(pid, {:push, element})
  end

  def pop(pid) do
    GenServer.call(pid, :pop)
  end

  # Server (callbacks)

  @impl true
  def init(elements) do
    initial_state = String.split(elements, ",", trim: true)
    {:ok, initial_state}
  end

  @impl true
  def handle_call(:pop, _from, state) do
    [to_caller | new_state] = state
    {:reply, to_caller, new_state}
  end

  @impl true
  def handle_cast({:push, element}, state) do
    new_state = [element | state]
    {:noreply, new_state}
  end
end

在实践中，服务器和客户端函数通常在同一个模块中。如果服务器和/或客户端实现变得复杂，你可能希望将它们放在不同的模块中。

下图总结了客户端和服务器之间的交互。客户端和服务器都是进程，通信通过消息（实线）进行。服务器 <-> 模块交互发生在 GenServer 进程调用你的代码时（虚线）

sequenceDiagram
    participant C as Client (Process)
    participant S as Server (Process)
    participant M as Module (Code)

    note right of C: Typically started by a supervisor
    C->>+S: GenServer.start_link(module, arg, options)
    S-->>+M: init(arg)
    M-->>-S: {:ok, state} | :ignore | {:error, reason}
    S->>-C: {:ok, pid} | :ignore | {:error, reason}

    note right of C: call is synchronous
    C->>+S: GenServer.call(pid, message)
    S-->>+M: handle_call(message, from, state)
    M-->>-S: {:reply, reply, state} | {:stop, reason, reply, state}
    S->>-C: reply

    note right of C: cast is asynchronous
    C-)S: GenServer.cast(pid, message)
    S-->>+M: handle_cast(message, state)
    M-->>-S: {:noreply, state} | {:stop, reason, state}

    note right of C: send is asynchronous
    C-)S: Kernel.send(pid, message)
    S-->>+M: handle_info(message, state)
    M-->>-S: {:noreply, state} | {:stop, reason, state}

如何监管

一个 GenServer 最常见的是在监管树下启动。当我们调用 use GenServer 时，它会自动定义一个 child_spec/1 函数，允许我们直接在监管者下启动 Stack。要在一个监管者下启动一个默认的 ["hello", "world"] 堆栈，我们可以这样做

children = [
  {Stack, "hello,world"}
]

Supervisor.start_link(children, strategy: :one_for_all)

请注意，指定模块 MyServer 与指定元组 {MyServer, []} 是相同的。

use GenServer 也接受一个选项列表，用于配置子节点规范，从而配置它在监管者下的运行方式。生成的 child_spec/1 可以使用以下选项进行定制

• :id - 子节点规范标识符，默认为当前模块
• :restart - 子节点应何时重启，默认为 :permanent
• :shutdown - 如何关闭子节点，是立即关闭还是让它有时间关闭

例如

use GenServer, restart: :transient, shutdown: 10_000

有关更多详细信息，请参阅 Supervisor 模块中的“子节点规范”部分。@doc 注解紧接在 use GenServer 之前，将附加到生成的 child_spec/1 函数。

在停止 GenServer 时，例如通过从回调中返回一个 {:stop, reason, new_state} 元组，退出原因将被监管者用来确定是否需要重启 GenServer。请参阅 Supervisor 模块中的“退出原因和重启”部分。

名称注册

两者 start_link/3 和 start/3 都支持 GenServer 通过 :name 选项在启动时注册一个名称。注册的名称在终止时也会自动清理。支持的值有

• 一个原子 - GenServer 使用 Process.register/2 在本地（到当前节点）注册给定名称。

• {:global, term} - GenServer 使用 :global 模块 中的函数在全局注册给定项。

• {:via, module, term} - GenServer 使用给定机制和名称注册。:via 选项期望一个导出 register_name/2、unregister_name/1、whereis_name/1 和 send/2 的模块。一个这样的例子是 :global 模块，它使用这些函数来维护可供 Elixir 节点网络全局访问的进程名称列表及其关联的 PID。Elixir 还附带一个名为 Registry 的本地、分散式和可扩展注册表，用于本地存储动态生成的名称。

例如，我们可以按如下方式启动并注册我们的 Stack 服务器:

# Start the server and register it locally with name MyStack
{:ok, _} = GenServer.start_link(Stack, "hello", name: MyStack)

# Now messages can be sent directly to MyStack
GenServer.call(MyStack, :pop)
#=> "hello"

一旦服务器启动，该模块中的剩余函数（call/3、cast/2 等）也将接受一个原子，或任何 {:global, ...} 或 {:via, ...} 元组。一般来说，支持以下格式

• 一个 PID
• 如果服务器在本地注册，则为一个原子
• {atom, node} 如果服务器在另一个节点上本地注册
• {:global, term} 如果服务器在全局注册
• {:via, module, name} 如果服务器通过备用注册表注册

如果你有兴趣在本地注册动态名称，请不要使用原子，因为原子永远不会被垃圾回收，因此动态生成的原子也不会被垃圾回收。对于这种情况，你可以使用 Registry 模块来设置你自己的本地注册表。

接收“常规”消息

一个 GenServer 的目标是为开发人员抽象出“接收”循环，自动处理系统消息、支持代码更改、同步调用等等。因此，你永远不应该在 GenServer 回调中调用你自己的“接收”，因为这样做会导致 GenServer 行为异常。

除了 call/3 和 cast/2 提供的同步和异步通信外，“常规”消息（由 send/2、Process.send_after/4 等函数发送）可以在 handle_info/2 回调中处理。

handle_info/2 可用于多种情况，例如处理 Process.monitor/1 发送的监控 DOWN 消息。handle_info/2 的另一个用例是，在 Process.send_after/4 的帮助下执行周期性工作

defmodule MyApp.Periodically do
  use GenServer

  def start_link(_) do
    GenServer.start_link(__MODULE__, %{})
  end

  @impl true
  def init(state) do
    # Schedule work to be performed on start
    schedule_work()

    {:ok, state}
  end

  @impl true
  def handle_info(:work, state) do
    # Do the desired work here
    # ...

    # Reschedule once more
    schedule_work()

    {:noreply, state}
  end

  defp schedule_work do
    # We schedule the work to happen in 2 hours (written in milliseconds).
    # Alternatively, one might write :timer.hours(2)
    Process.send_after(self(), :work, 2 * 60 * 60 * 1000)
  end
end

超时

init/1 或任何 handle_* 回调的返回值可能包括一个以毫秒为单位的超时值；如果没有，则假定为 :infinity。超时可用于检测传入消息的间歇。

timeout() 值的使用方式如下

• 如果进程在返回 timeout() 值时有任何消息正在等待，则超时将被忽略，等待的消息将按正常方式处理。这意味着即使超时为 0 毫秒也不能保证执行（如果你想立即无条件地执行另一个操作，请使用 :continue 指令）。

• 如果在指定的毫秒数过去之前有任何消息到达，则超时将被清除，该消息将按正常方式处理。

• 否则，当指定的毫秒数过去而没有消息到达时，handle_info/2 将使用 :timeout 作为第一个参数被调用。

何时（不）使用 GenServer

到目前为止，我们已经了解到 GenServer 可以用作处理同步和异步调用的监管进程。它还可以处理系统消息，例如周期性消息和监控事件。GenServer 进程也可以被命名。

GenServer 或一般进程必须用于模拟系统运行时的特征。GenServer 切勿用于代码组织目的。

在 Elixir 中，代码组织是通过模块和函数完成的，不需要进程。例如，假设您正在实现一个计算器，并且您决定将所有计算器操作放在 GenServer 后面。

def add(a, b) do
  GenServer.call(__MODULE__, {:add, a, b})
end

def subtract(a, b) do
  GenServer.call(__MODULE__, {:subtract, a, b})
end

def handle_call({:add, a, b}, _from, state) do
  {:reply, a + b, state}
end

def handle_call({:subtract, a, b}, _from, state) do
  {:reply, a - b, state}
end

这是一种反模式，不仅因为它使计算器逻辑变得复杂，而且因为它将计算器逻辑放在单个进程后面，该进程可能会成为系统中的瓶颈，尤其是在调用次数增加的情况下。相反，直接定义函数。

def add(a, b) do
  a + b
end

def subtract(a, b) do
  a - b
end

如果您不需要进程，那么您就不需要进程。仅使用进程来模拟运行时属性，例如可变状态、并发和故障，切勿用于代码组织。

使用 :sys 模块进行调试

GenServer 作为 特殊进程，可以使用 :sys 模块 进行调试。通过各种钩子，该模块允许开发人员内省进程的状态并跟踪其执行过程中发生的系统事件，例如接收的消息、发送的回复和状态更改。

让我们探讨 :sys 模块 中用于调试的基本函数。

• :sys.get_state/2 - 允许检索进程的状态。对于 GenServer 进程，它将是回调模块状态，作为最后一个参数传递到回调函数中。
• :sys.get_status/2 - 允许检索进程的状态。此状态包括进程字典、进程是否正在运行或已暂停、父 PID、调试器状态以及行为模块的状态，其中包括回调模块状态（如 :sys.get_state/2 返回的）。可以通过定义可选的 GenServer.format_status/2 回调来更改此状态的表示方式。
• :sys.trace/3 - 将所有系统事件打印到 :stdio。
• :sys.statistics/3 - 管理进程统计信息的收集。
• :sys.no_debug/2 - 关闭给定进程的所有调试处理程序。在完成调试后，关闭调试非常重要。过多的调试处理程序或应该关闭但未关闭的调试处理程序会严重损害系统的性能。
• :sys.suspend/2 - 允许暂停进程，使其仅回复系统消息，而不回复其他消息。可以通过 :sys.resume/2 重新激活暂停的进程。

让我们看看如何使用这些函数来调试我们之前定义的堆栈服务器。

iex> {:ok, pid} = Stack.start_link([])
iex> :sys.statistics(pid, true) # turn on collecting process statistics
iex> :sys.trace(pid, true) # turn on event printing
iex> Stack.push(pid, 1)
*DBG* <0.122.0> got cast {push,1}
*DBG* <0.122.0> new state [1]
:ok

iex> :sys.get_state(pid)
[1]

iex> Stack.pop(pid)
*DBG* <0.122.0> got call pop from <0.80.0>
*DBG* <0.122.0> sent 1 to <0.80.0>, new state []
1

iex> :sys.statistics(pid, :get)
{:ok,
 [
   start_time: {{2016, 7, 16}, {12, 29, 41}},
   current_time: {{2016, 7, 16}, {12, 29, 50}},
   reductions: 117,
   messages_in: 2,
   messages_out: 0
 ]}

iex> :sys.no_debug(pid) # turn off all debug handlers
:ok

iex> :sys.get_status(pid)
{:status, #PID<0.122.0>, {:module, :gen_server},
 [
   [
     "$initial_call": {Stack, :init, 1},            # process dictionary
     "$ancestors": [#PID<0.80.0>, #PID<0.51.0>]
   ],
   :running,                                        # :running | :suspended
   #PID<0.80.0>,                                    # parent
   [],                                              # debugger state
   [
     header: 'Status for generic server <0.122.0>', # module status
     data: [
       {'Status', :running},
       {'Parent', #PID<0.80.0>},
       {'Logged events', []}
     ],
     data: [{'State', [1]}]
   ]
 ]}

了解更多

如果您想详细了解 GenServers，Elixir 入门指南提供了类似教程的介绍。Erlang 中的文档和链接也可以提供额外的见解。

• GenServer - Elixir 入门指南
• :gen_server 模块文档
• gen_server 行为 - OTP 设计原则
• 客户端和服务器 - 学习一些 Erlang 以获得更大的好处！