Phoenix API 生成器

工作流

基于 OpenAPI YAML

1. 解析 OpenAPI 规范 — 提取路径（paths）、模式（schemas）、请求/响应体。
2. 将每个 schema 映射为一个 Ecto schema 及其对应 migration。
3. 将每个路径映射为一个控制器动作（controller action）；按资源上下文（resource context）分组。
4. 根据 securitySchemes 生成认证插件（auth plugs）。
5. 生成覆盖正常流程（happy path）及验证错误的 ExUnit 测试。

基于自然语言描述

1. 从描述中提取资源、字段、类型及关系。
2. 推断上下文边界（将相关资源归入同一上下文）。
3. 生成 schemas、migrations、controllers、views、router 和 tests。
4. 在写入文件前向用户确认。

文件生成顺序

1. Migrations（时间戳前缀格式：YYYYMMDDHHMMSS）
2. Ecto schemas 及 changesets
3. Context 模块（含 CRUD 函数）
4. Controllers 及 FallbackController
5. JSON 渲染器（Phoenix 1.7+ 使用 *JSON 模块；旧版本使用 *View）
6. Router scope 及 pipelines
7. Auth plugs
8. Tests 及 factories

Phoenix 约定规范

参见 references/phoenix-conventions.md 获取项目结构、命名规则、上下文模式等说明。

核心规则：

• 每个有界域（bounded domain）对应一个 context（例如：Accounts、Billing、Notifications）。
• Context 是对外公开的接口 — 控制器不得直接调用 Repo。
• Schemas 位于 context 下：如 MyApp.Accounts.User。
• 控制器委托逻辑至 context；返回 {:ok, resource} 或 {:error, changeset}。
• 配合 FallbackController 与 action_fallback/1 处理错误元组（error tuples）。

Ecto 模式规范

参见 references/ecto-patterns.md 获取 schema、changeset、migration 的详细说明。

核心规则：

• 始终使用 timestamps(type: :utc_datetime_usec)。
• 二进制 ID（Binary IDs）：声明 @primary_key {:id, :binary_id, autogenerate: true} 并设置 @foreign_key_type :binary_id。
• 当创建与更新所需字段不同时，应分别定义 create_changeset/2 和 update_changeset/2。
• 字段必填性、格式及约束校验应在 changeset 中完成 — 不得置于 controller 中。

多租户（Multi-Tenancy）

为所有租户作用域内的表添加 tenant_id :binary_id 字段。典型模式如下：

# 在 context 中
def list_resources(tenant_id) do
  Resource
  |> where(tenant_id: ^tenant_id)
  |> Repo.all()
end

# 在 plug 中 — 从 conn 提取 tenant 并 assign
defmodule MyAppWeb.Plugs.SetTenant do
  import Plug.Conn
  def init(opts), do: opts
  def call(conn, _opts) do
    tenant_id = get_req_header(conn, "x-tenant-id") |> List.first()
    assign(conn, :tenant_id, tenant_id)
  end
end

务必为 [:tenant_id, ] 添加复合索引（composite index）。

认证插件（Auth Plugs）

API Key 认证

defmodule MyAppWeb.Plugs.ApiKeyAuth do
  import Plug.Conn
  def init(opts), do: opts
  def call(conn, _opts) do
    with [key] <- get_req_header(conn, "x-api-key"),
         {:ok, account} <- Accounts.authenticate_api_key(key) do
      assign(conn, :current_account, account)
    else
      _ -> conn |> send_resp(401, "Unauthorized") |> halt()
    end
  end
end

Bearer Token 认证

defmodule MyAppWeb.Plugs.BearerAuth do
  import Plug.Conn
  def init(opts), do: opts
  def call(conn, _opts) do
    with ["Bearer " <> token] <- get_req_header(conn, "authorization"),
         {:ok, claims} <- MyApp.Token.verify(token) do
      assign(conn, :current_user, claims)
    else
      _ -> conn |> send_resp(401, "Unauthorized") |> halt()
    end
  end
end

Router 结构

scope "/api/v1", MyAppWeb do
  pipe_through [:api, :authenticated]

  resources "/users", UserController, except: [:new, :edit]
  resources "/teams", TeamController, except: [:new, :edit] do
    resources "/members", MemberController, only: [:index, :create, :delete]
  end
end

测试生成规范

参见 references/test-patterns.md 获取 ExUnit、Mox、factory 相关模式说明。

核心规则：

• 对所有不共享状态的测试启用 async: true。
• 使用 Ecto.Adapters.SQL.Sandbox 实现数据库隔离。
• Factory 模块可基于 ex_machina 构建，或手动实现 build/1、insert/1 等函数。
• 分别测试 context 和 controller。
• 针对 controller 的测试需覆盖状态码、响应体结构及各类错误场景。
• 使用 Mox 模拟外部服务 — 需明确定义 behaviour，并在测试中设定期望行为（expectations）。

Controller 测试模板

defmodule MyAppWeb.UserControllerTest do
  use MyAppWeb.ConnCase, async: true

  import MyApp.Factory

  setup %{conn: conn} do
    user = insert(:user)
    conn = put_req_header(conn, "authorization", "Bearer #{token_for(user)}")
    {:ok, conn: conn, user: user}
  end

  describe "index" do
    test "lists users", %{conn: conn} do
      conn = get(conn, ~p"/api/v1/users")
      assert %{"data" => users} = json_response(conn, 200)
      assert is_list(users)
    end
  end

  describe "create" do
    test "returns 201 with valid params", %{conn: conn} do
      params = params_for(:user)
      conn = post(conn, ~p"/api/v1/users", user: params)
      assert %{"data" => %{"id" => _}} = json_response(conn, 201)
    end

    test "returns 422 with invalid params", %{conn: conn} do
      conn = post(conn, ~p"/api/v1/users", user: %{})
      assert json_response(conn, 422)["errors"] != %{}
    end
  end
end

JSON 渲染器（Phoenix 1.7+）

defmodule MyAppWeb.UserJSON do
  def index(%{users: users}), do: %{data: for(u <- users, do: data(u))}
  def show(%{user: user}), do: %{data: data(user)}

  defp data(user) do
    %{
      id: user.id,
      email: user.email,
      inserted_at: user.inserted_at
    }
  end
end

写入文件前检查清单

• Migrations 使用 timestamps(type: :utc_datetime_usec)
• 若项目采用 UUID，则已配置 Binary IDs
• 已在必要位置应用租户作用域（Tenant scoping）
• Auth plug 已接入 router pipeline
• FallbackController 已处理 {:error, changeset} 和 {:error, :not_found}
• 测试覆盖了 200、201、404、422 状态码
• 每个 schema 均已定义对应的 Factory