定義 Phoenix 路由器。

路由器提供一組巨集，用於產生轉接到特定控制器和動作的路由。這些巨集以 HTTP 詞彙命名。例如

defmodule MyAppWeb.Router do
  use Phoenix.Router

  get "/pages/:page", PageController, :show
end

上述 get/3 巨集接受對 /pages/hello 的請求，並將其轉接到 PageController 的 show 動作，並在 params 中包含 %{"page" => "hello"}。

Phoenix 的路由器極為有效率，因為它仰賴 Elixir 模式比對來比對路由和服務請求。

路由

以 HTTP 詞彙命名的 get/3、post/3、put/3 等巨集用於建立路由。

路由

get "/pages", PageController, :index

比對對 /pages 的 GET 請求，並將其轉接到 PageController 的 index 動作。

get "/pages/:page", PageController, :show

比對 /pages/hello，並在 params 中包含 %{"page" => "hello"}，轉接到 show 動作。

defmodule PageController do
  def show(conn, params) do
    # %{"page" => "hello"} == params
  end
end

可以比對部分段落和多重段落。例如

get "/api/v:version/pages/:id", PageController, :show

比對 /api/v1/pages/2，並在 params 中放入 %{"version" => "1", "id" => "2"}。只能擷取段落的尾端部分。

從頭到尾比對路由。這裡的第二條路由

get "/pages/:page", PageController, :show
get "/pages/hello", PageController, :hello

永遠不會比對到 /pages/hello，因為 /pages/:page 優先比對到它。

路由可以使用類別星號的型態來比對尾端段落。

get "/pages/*page", PageController, :show

比對 /pages/hello/world，並將類別星號段落放入 params["page"] 中。

GET /pages/hello/world
%{"page" => ["hello", "world"]} = params

類別星號不能有字首或字尾，但可以和變數混合

get "/pages/he:page/*rest", PageController, :show

比對

GET /pages/hello
%{"page" => "llo", "rest" => []} = params

GET /pages/hey/there/world
%{"page" => "y", "rest" => ["there" "world"]} = params

為什麼使用巨集？

Phoenix 盡可能降低巨集的使用量。然而，您可能已經注意到 Phoenix.Router 大量依賴於巨集。為什麼會這樣？

我們使用 get、post、put 和 delete 來定義路由。我們使用巨集的目的是

• 它們定義路由引擎，在每個請求中用於選擇要將請求轉接到哪個控制器。多虧巨集，Phoenix 會編譯您的所有路由成一個單一 case-statement，其中包含模式比對規則，而這些規則已經由 Erlang VM 大幅最佳化

• 對於您定義的每個路由，我們也會定義元資料來實作 Phoenix.VerifiedRoutes。正如我們很快就會了解到的，已驗證的路由允許我們將任何路由像參考一個正常的字串一樣，只不過它經過編譯器的驗證是有效的（使運送中斷的連結、表單、信件等事項到生產環境變得困難許多）

換句話說，路由器仰賴巨集來建立更快速、更安全的應用程式。同時也要記住 Elixir 中的巨集只在編譯時期才會執行，這為編譯好的程式碼提供了充足的穩定性。Phoenix 透過 mix phx.routes 為所有已定義的路由提供內省。

產生路由

如要於您的應用程式內部產生路由，請參閱 Phoenix.VerifiedRoutes 文件，關於透過編譯時期驗證的基於 ~p 的路由產生方式，這是產生路由路徑和 URL 的優先方式。

Phoenix 也支援產生函式幫手，這是 Phoenix v1.6 及較早版本中的預設機制。我們將在接著進行的章節中介紹它。

幫手（已棄用）

預設情況下，Phoenix 在您的路由器內部產生一個 Helpers 模組，其中包含有助於開發人員產生與保持路由為最新的命名幫手。透過將 helpers: false 傳遞到 use Phoenix.Router，即可停用幫手。

幫手是根據控制器的名稱自動產生的。例如，路由

get "/pages/:page", PageController, :show

將會產生以下的命名幫手

MyAppWeb.Router.Helpers.page_path(conn_or_endpoint, :show, "hello")
"/pages/hello"

MyAppWeb.Router.Helpers.page_path(conn_or_endpoint, :show, "hello", some: "query")
"/pages/hello?some=query"

MyAppWeb.Router.Helpers.page_url(conn_or_endpoint, :show, "hello")
"http://example.com/pages/hello"

MyAppWeb.Router.Helpers.page_url(conn_or_endpoint, :show, "hello", some: "query")
"http://example.com/pages/hello?some=query"

如果路由包含類似全域比對的樣式，那些參數就必須作為清單給予

MyAppWeb.Router.Helpers.page_path(conn_or_endpoint, :show, ["hello", "world"])
"/pages/hello/world"

在命名的 URL 幫手中產生的 URL 是根據 :url、:http 和 :https 的設定。不過，如果您因為某些原因而需要手動控制 URL 的產生，URL 幫手也允許您傳入一個 URI 結構

uri = %URI{scheme: "https", host: "other.example.com"}
MyAppWeb.Router.Helpers.page_url(uri, :show, "hello")
"https://other.example.com/pages/hello"

也可以使用 :as 選項自訂命名的幫手。給定路由

get "/pages/:page", PageController, :show, as: :special_page

命名的幫手會是

MyAppWeb.Router.Helpers.special_page_path(conn, :show, "hello")
"/pages/hello"

範圍和資源

在 Phoenix 應用程式中，將所有路由都命名空間在應用程式範圍以下的情形非常普遍

scope "/", MyAppWeb do
  get "/pages/:id", PageController, :show
end

上面的路由將會轉發給 MyAppWeb.PageController。此語法不但對開發人員很方便（我們不必在所有路由上重複 MyAppWeb. 這個字首），而且也讓 Phoenix 能夠減少 Elixir 編譯器的負擔。如果我們寫成以下的樣子

get "/pages/:id", MyAppWeb.PageController, :show

Elixir 編譯器推論路由器直接取決於 MyAppWeb.PageController，但這並非事實。Phoenix 可透過範圍提示 Elixir 編譯器，控制器並非路由器的實際依賴項。這能提供更有效率的編譯時間。

範圍讓我們能設定任何路徑或甚至輔助程式名稱的範圍

scope "/v1", MyAppWeb, host: "api." do
  get "/pages/:id", PageController, :show
end

例如，上述路由將會比對路徑 "/api/v1/pages/1"，且命名的路由將會是 api_v1_page_path，就像 scope/2 選項所提供數值所預期的那樣。

就像所有路徑一樣，您能定義動態區段，這會套用至控制器的參數中

scope "/api/:version", MyAppWeb do
  get "/pages/:id", PageController, :show
end

例如，上述路由將會比對路徑 "/api/v1/pages/1"，且在控制器中的 params 引數將會有個具有 :version 鍵對應值 "v1" 的映射。

Phoenix 也提供了一個 resources/4 巨集，它可讓開發人員為給定的資源產生「RESTful」路由

defmodule MyAppWeb.Router do
  use Phoenix.Router

  resources "/pages", PageController, only: [:show]
  resources "/users", UserController, except: [:delete]
end

最後，Phoenix 內含一個 mix phx.routes 工作，它可以漂亮地格式化給定路由器中的所有路由。我們能使用它來驗證上述路由器中所包含的所有路由

$ mix phx.routes
page_path  GET    /pages/:id       PageController.show/2
user_path  GET    /users           UserController.index/2
user_path  GET    /users/:id/edit  UserController.edit/2
user_path  GET    /users/new       UserController.new/2
user_path  GET    /users/:id       UserController.show/2
user_path  POST   /users           UserController.create/2
user_path  PATCH  /users/:id       UserController.update/2
           PUT    /users/:id       UserController.update/2

也可以將路由器明確地傳遞為工作中的引數

$ mix phx.routes MyAppWeb.Router

查看 scope/2 和 resources/4 以取得更多資訊。

管道與外掛程式

一旦要求到達 Phoenix 路由器，就會透過管道執行一系列轉換，直到要求被傳送到想要的路由。

此類轉換是透過外掛程式定義的，正如 Plug 規範書所定義的那樣。定義一個管道後，就可以將它透過每個範圍進行傳遞。

例如

defmodule MyAppWeb.Router do
  use Phoenix.Router

  pipeline :browser do
    plug :fetch_session
    plug :accepts, ["html"]
  end

  scope "/" do
    pipe_through :browser

    # browser related routes and resources
  end
end

Phoenix.Router 從 Plug.Conn 和 Phoenix.Controller 匯入函式，以協助定義外掛程式。在上述範例中，fetch_session/2 來自 Plug.Conn，而 accepts/2 來自 Phoenix.Controller。

請注意，只有在找到路由時才會呼叫路由器管道。若未找到任何比對結果，則不會呼叫任何外掛程式。

如何組織我的路由？

在 Phoenix 中，我們傾向於定義提供特定功能的管道。舉例來說，以上的 pipeline :browser 包含所有路徑的常見 plug，這些路徑都是瀏覽器提取的。類似地，如果你也有服務 :api 要求，你會有一個獨立的 :api 管道，驗證你端點的特定資訊。

也許更重要的是，定義特定於驗證和授權的管道也很常見。舉例來說，你可能有要求所有使用者都經過驗證的管道。另一個管道可能僅強制管理者使用者能夠提取特定的路徑。由於路徑從上到下比對，建議在受限較少的路徑之前放置驗證/授權的路徑，以確保它們會優先比對。

當你的管道定義好後，你會在需要的範圍內重新使用管道，並將你的路徑分組到它們的管道周圍。舉例來說，想像你在建立一個部落格。任何人都能閱讀文章，但只有經過驗證的使用者才能建立文章。你的路徑會長這樣：

pipeline :browser do
  plug :fetch_session
  plug :accepts, ["html"]
end

pipeline :auth do
  plug :ensure_authenticated
end

scope "/" do
  pipe_through [:browser, :auth]

  get "/posts/new", PostController, :new
  post "/posts", PostController, :create
end

scope "/" do
  pipe_through [:browser]

  get "/posts", PostController, :index
  get "/posts/:id", PostController, :show
end

注意以上路徑是如何在不同範圍內被分割的。儘管一開始這樣的分割會令人困惑，但它有一個很大的優點：你可以非常容易地檢查你的路徑，查看所有需要驗證的路徑，以及哪些路徑不需要。這有助於稽核並確保你的路徑有適當的範圍。

你可以建立你想要的範圍，可以建立少一點或多一點。因為管道可以在範圍之間重複使用，所以它們有助於封裝常見的功能，而且你可以在你定義的每個範圍中根據需要組合它們。