Elixir 开发

运行 Mix 命令

完整命令参考请见 references/mix-commands.md。

测试

# 运行全部测试
mix test

# 指定文件或行号
mix test test/my_app/accounts_test.exs:42

# 按标签筛选
mix test --only integration

# 仅重跑失败用例（需在前一次运行中启用 --failed 标志）
mix test --failed

# 启用覆盖率统计
mix test --cover

解读测试失败信息：

• ** (MatchError) —— 模式匹配失败；检查返回值结构是否符合预期。
• ** (Ecto.NoResultsError) —— 对不存在的 ID 调用了 Repo.get!；改用 Repo.get 或补充种子数据（seed data）。
• ** (DBConnection.OwnershipError) —— 缺少 async: true 配置或未正确设置 sandbox。
• no function clause matching —— 函数参数元数（arity）错误，或传入了意外类型的参数。

Credo

mix credo --strict
mix credo suggest --format json
mix credo explain MyApp.Module  # 解释指定模块中的问题

常见 Credo 修复方式：

• Credo.Check.Readability.ModuleDoc —— 添加 @moduledoc 注释。
• Credo.Check.Refactor.CyclomaticComplexity —— 提取辅助函数以降低圈复杂度。
• Credo.Check.Design.TagTODO —— 处理或移除 TODO 注释。

Dialyzer

mix dialyzer
mix dialyzer --format short

常见 Dialyzer 警告含义：

• The pattern can never match —— 不可达代码（dead code），或模式中类型不匹配。
• Function has no local return —— 所有执行路径均会崩溃；检查内部调用逻辑。
• The call will never return —— 调用了总会抛出异常的函数。
• 修复建议：添加 @spec 类型签名；万不得已时可使用 @dialyzer {:nowarn_function, func: arity} 抑制警告。

代码格式化

mix format
mix format --check-formatted  # CI 模式 —— 若存在未格式化代码则退出码为 1

模块生成规范

所有公开函数必须包含 @moduledoc、@doc 和 @spec。

Context 模块

defmodule MyApp.Notifications do
  @moduledoc """
  管理通知投递与用户偏好设置。
  """
  import Ecto.Query
  alias MyApp.Repo
  alias MyApp.Notifications.Notification

  @doc "按时间倒序列出指定用户的全部通知。"
  @spec list_notifications(String.t(), keyword()) :: [Notification.t()]
  def list_notifications(user_id, opts \\ []) do
    limit = Keyword.get(opts, :limit, 50)

    Notification
    |> where(user_id: ^user_id)
    |> order_by(desc: :inserted_at)
    |> limit(^limit)
    |> Repo.all()
  end
end

Schema 模块

defmodule MyApp.Notifications.Notification do
  @moduledoc """
  推送/邮件/SMS 通知的数据结构定义。
  """
  use Ecto.Schema
  import Ecto.Changeset

  @type t :: %__MODULE__{}

  @primary_key {:id, :binary_id, autogenerate: true}
  @foreign_key_type :binary_id
  @timestamps_opts [type: :utc_datetime_usec]

  schema "notifications" do
    field :channel, Ecto.Enum, values: [:push, :email, :sms]
    field :title, :string
    field :body, :string
    field :delivered_at, :utc_datetime_usec
    field :user_id, :binary_id

    timestamps()
  end

  @required ~w(channel title body user_id)a

  @doc false
  def changeset(notification, attrs) do
    notification
    |> cast(attrs, @required ++ [:delivered_at])
    |> validate_required(@required)
    |> validate_length(:title, max: 255)
  end
end

OTP 模式

GenServer、Supervisor、Agent、Task 等典型 OTP 模式的详细说明请参阅 references/otp-patterns.md。

何时选用何种模式

GenServer 模板

defmodule MyApp.RateLimiter do
  @moduledoc "令牌桶限流器。"
  use GenServer

  # 客户端 API
  def start_link(opts) do
    name = Keyword.get(opts, :name, __MODULE__)
    GenServer.start_link(__MODULE__, opts, name: name)
  end

  @spec check_rate(String.t()) :: :ok | {:error, :rate_limited}
  def check_rate(key), do: GenServer.call(__MODULE__, {:check, key})

  # 服务端回调
  @impl true
  def init(opts) do
    {:ok, %{limit: Keyword.get(opts, :limit, 100), window_ms: 60_000, buckets: %{}}}
  end

  @impl true
  def handle_call({:check, key}, _from, state) do
    now = System.monotonic_time(:millisecond)
    {count, state} = increment(state, key, now)
    if count <= state.limit, do: {:reply, :ok, state}, else: {:reply, {:error, :rate_limited}, state}
  end

  defp increment(state, key, now) do
    # 实现细节
  end
end

常见编译错误

Ecto 查询模式

动态过滤条件

def list(filters) do
  Enum.reduce(filters, base_query(), fn
    {:status, val}, q -> where(q, [r], r.status == ^val)
    {:since, dt}, q -> where(q, [r], r.inserted_at >= ^dt)
    {:search, term}, q -> where(q, [r], ilike(r.name, ^"%#{term}%"))
    _, q -> q
  end)
  |> Repo.all()
end

预加载（Preloading）

# 查询时预加载（单次查询 + JOIN）
from(p in Post, join: a in assoc(p, :author), preload: [author: a])

# 分离式预加载（两次查询）
Post |> Repo.all() |> Repo.preload(:author)

# 嵌套预加载
Repo.preload(posts, [comments: :author])

聚合查询（Aggregates）

from(o in Order,
  where: o.tenant_id == ^tenant_id,
  group_by: o.status,
  select: {o.status, count(o.id), sum(o.amount)}
)
|> Repo.all()

Phoenix LiveView 基础

挂载（Mount）与事件处理（Handle Events）

defmodule MyAppWeb.DashboardLive do
  use MyAppWeb, :live_view

  @impl true
  def mount(_params, _session, socket) do
    {:ok, assign(socket, items: [], loading: true)}
  end

  @impl true
  def handle_event("delete", %{"id" => id}, socket) do
    MyApp.Items.delete_item!(id)
    {:noreply, assign(socket, items: MyApp.Items.list_items())}
  end

  @impl true
  def render(assigns) do
    ~H"""
    

      <%= item.name %>
      Delete
    
    """
  end
end

通过 PubSub 实现实时通信

# 在 mount 中订阅
def mount(_, _, socket) do
  if connected?(socket), do: Phoenix.PubSub.subscribe(MyApp.PubSub, "items")
  {:ok, assign(socket, items: list_items())}
end

# 在 Context 中广播事件
def create_item(attrs) do
  with {:ok, item} <- %Item{} |> Item.changeset(attrs) |> Repo.insert() do
    Phoenix.PubSub.broadcast(MyApp.PubSub, "items", {:item_created, item})
    {:ok, item}
  end
end

# 在 LiveView 中处理消息
def handle_info({:item_created, item}, socket) do
  {:noreply, update(socket, :items, &[item | &1])}
end