Phoenix.Router

Создаёт маршрут для обработки connect-запроса по указанному пути.

connect("/events/:id", EventController, :action)

Сведения о параметрах см. в разделе match/5.

Создаёт маршрут для обработки delete-запроса по указанному пути.

delete("/events/:id", EventController, :action)

Сведения о параметрах см. в разделе match/5.

Перенаправляет запрос по указанному пути в plug.

Чаще всего это используется для перенаправления всех вложенных маршрутов в другой Plug. Например:

forward "/admin", SomeLib.AdminDashboard

Это позволит SomeLib.AdminDashboard обрабатывать /admin, /admin/foo, /admin/bar/baz и так далее. Кроме того, SomeLib.AdminDashboard не нужно знать префикс, с которым он подключён. С его точки зрения, указанные выше маршруты обрабатываются как /, /foo и /bar/baz.

Обычный сценарий использования forward — совместное использование маршрутизатора несколькими приложениями или разделение большого маршрутизатора на несколько меньших. Однако для корректной генерации маршрутов можно перенаправить запросы только в один экземпляр Phoenix.Router.

Перед перенаправлением соединения будут выполнены конвейеры маршрутизатора.

Примеры

scope "/", MyApp do
  pipe_through [:browser, :admin]

  forward "/admin", SomeLib.AdminDashboard
  forward "/api", ApiRouter
end

Создаёт маршрут для обработки get-запроса по указанному пути.

get("/events/:id", EventController, :action)

Сведения о параметрах см. в разделе match/5.

Создаёт маршрут для обработки head-запроса по указанному пути.

head("/events/:id", EventController, :action)

Сведения о параметрах см. в разделе match/5.

Совместимость с Plug.Head

По умолчанию приложения Phoenix включают Plug.Head в свою конечную точку, где HEAD-запросы преобразуются в обычные GET-запросы. Поэтому, если вы хотите использовать head/4 в маршрутизаторе, необходимо переместить Plug.Head внутрь маршрутизатора так, чтобы он не конфликтовал с путями, указанными в head/4.

Создаёт маршрут, соответствующий произвольному методу HTTP.

Полезно для определения маршрутов, не включённых во встроенные макросы.

Также можно использовать универсальный метод :* для сопоставления со всеми методами HTTP.

Параметры

• :as — задаёт именованный helper. Если указано nil, helper не создаётся. Не действует, если используются только проверяемые маршруты
• :alias — определяет, следует ли применять к маршруту псевдоним области видимости. По умолчанию — true; если задано false, область видимости не применяется.
• :log — уровень журналирования диспетчеризации маршрута; можно задать false. По умолчанию — :debug. Запись диспетчеризации содержит сведения об обработке маршрута (какое действие контроллера вызывается, какие параметры доступны и какие конвейеры используются) и ведётся отдельно от журналирования на уровне plug. Чтобы изменить уровень журналирования plug, см. https://phoenix.hexdocs.pm/Phoenix.Logger.html#module-dynamic-log-level.
• :private — карта приватных данных, добавляемых к соединению при совпадении маршрута
• :assigns — карта данных, добавляемых к соединению при совпадении маршрута
• :metadata — карта метаданных, используемых событиями telemetry и возвращаемых функцией route_info/4. Поле :mfa используется telemetry для вывода журналов, а маршрутизатором — для выполнения проверок во время компиляции. Можно добавлять пользовательские поля.
• :warn_on_verify — логическое значение, определяющее, будет ли совпадение с этим маршрутом вызывать предупреждение о несопоставленном маршруте для Phoenix.VerifiedRoutes. Это позволяет исключить из проверки маршрутов совпадение с определением маршрута, которое в противном случае охватывало бы все случаи. По умолчанию — false.

Примеры

match(:move, "/events/:id", EventController, :move)

match(:*, "/any", SomeController, :any)

Создаёт маршрут для обработки options-запроса по указанному пути.

options("/events/:id", EventController, :action)

Сведения о параметрах см. в разделе match/5.

Создаёт маршрут для обработки patch-запроса по указанному пути.

patch("/events/:id", EventController, :action)

Сведения о параметрах см. в разделе match/5.

Определяет список plug (и конвейеров), через которые проходит соединение.

Plug указываются атомарным именем любой импортированной функции с арностью 2, которая принимает Plug.Conn и параметры и возвращает Plug.Conn. Например, :require_authenticated_user.

Конвейеры определяются в маршрутизаторе; дополнительную информацию см. в разделе pipeline/2.

pipe_through [:require_authenticated_user, :my_browser_pipeline]

Несколько вызовов

Функцию pipe_through/1 можно вызывать несколько раз в одной области видимости. Каждый вызов добавляет новые plug и конвейеры, которые будут применяться ко всем маршрутам, определённым после вызова pipe_through/1. Например:

scope "/" do
  pipe_through [:browser]
  get "/", HomeController, :index

  pipe_through [:require_authenticated_user]
  get "/settings", UserController, :edit
end

В примере выше / проходит только через browser, а /settings — через browser и require_authenticated_user. Поэтому, чтобы избежать путаницы, рекомендуем использовать один pipe_through в начале каждой области видимости:

scope "/" do
  pipe_through [:browser]
  get "/", HomeController, :index
end

scope "/" do
  pipe_through [:browser, :require_authenticated_user]
  get "/settings", UserController, :edit
end

Определяет конвейер plug.

Конвейеры определяются в корне маршрутизатора и могут использоваться из любой области видимости.

Примеры

pipeline :api do
  plug :token_authentication
  plug :dispatch
end

Затем область видимости может использовать этот конвейер следующим образом:

scope "/" do
  pipe_through :api
end

При каждом вызове pipe_through/1 новые конвейеры добавляются к указанным ранее.

Определяет plug внутри конвейера.

Дополнительную информацию см. в разделе pipeline/2.

Создаёт маршрут для обработки post-запроса по указанному пути.

post("/events/:id", EventController, :action)

Сведения о параметрах см. в разделе match/5.

Создаёт маршрут для обработки put-запроса по указанному пути.

put("/events/:id", EventController, :action)

Сведения о параметрах см. в разделе match/5.

См. resources/4.

См. resources/4.

Определяет маршруты «RESTful» для ресурса.

Указанное определение:

resources "/users", UserController

будет включать маршруты для следующих действий:

• GET /users => :index
• GET /users/new => :new
• POST /users => :create
• GET /users/:id => :show
• GET /users/:id/edit => :edit
• PATCH /users/:id => :update
• PUT /users/:id => :update
• DELETE /users/:id => :delete

Параметры

Этот макрос принимает набор параметров:

• :only — список действий, для которых нужно создать маршруты, например: [:show, :edit]
• :except — список действий, для которых не нужно создавать маршруты, например: [:delete]
• :param — имя параметра этого ресурса; по умолчанию — "id"
• :name — префикс этого ресурса. Используется для именованного helper и как префикс параметра во вложенных ресурсах. Значение по умолчанию автоматически определяется по имени контроллера: например, UserController будет иметь имя "user"
• :as — задаёт именованный helper. Если указано nil, helper не создаётся. Не действует, если используются только проверяемые маршруты
• :singleton — определяет маршруты для одиночного ресурса, который клиент запрашивает без указания идентификатора. Подробнее см. ниже

Одиночные ресурсы

Если ресурс нужно запрашивать без указания идентификатора, поскольку в заданном контексте он содержит только одну запись, можно использовать параметр :singleton, чтобы создать набор маршрутов для такого одиночного ресурса:

• GET /user => :show
• GET /user/new => :new
• POST /user => :create
• GET /user/edit => :edit
• PATCH /user => :update
• PUT /user => :update
• DELETE /user => :delete

Пример использования:

resources "/account", AccountController, only: [:show], singleton: true

Вложенные ресурсы

Этот макрос также поддерживает передачу вложенного блока определений маршрутов. Это удобно для вложения дочерних ресурсов в родительские и создания вложенных маршрутов.

Указанное определение:

resources "/users", UserController do
  resources "/posts", PostController
end

будет включать следующие маршруты:

user_post_path  GET     /users/:user_id/posts           PostController :index
user_post_path  GET     /users/:user_id/posts/:id/edit  PostController :edit
user_post_path  GET     /users/:user_id/posts/new       PostController :new
user_post_path  GET     /users/:user_id/posts/:id       PostController :show
user_post_path  POST    /users/:user_id/posts           PostController :create
user_post_path  PATCH   /users/:user_id/posts/:id       PostController :update
                PUT     /users/:user_id/posts/:id       PostController :update
user_post_path  DELETE  /users/:user_id/posts/:id       PostController :delete

Возвращает сведения обо всех маршрутах указанного маршрутизатора.

Определяет область видимости, внутри которой можно размещать вложенные маршруты.

Примеры

scope path: "/api/v1", alias: API.V1 do
  get "/pages/:id", PageController, :show
end

Созданный маршрут будет соответствовать пути "/api/v1/pages/:id" и направлять запрос к действию :show в API.V1.PageController. Также будет создан именованный helper api_v1_page_path.

Параметры

Поддерживаются следующие параметры:

• :path — строка, содержащая область видимости пути.
• :as — строка или атом, содержащие область видимости именованного helper. Если задано false, сбрасывает вложенные области видимости helper. Не действует, если используются только проверяемые маршруты
• :alias — псевдоним (атом), содержащий область видимости контроллера. Если задано false, сбрасывает все вложенные псевдонимы.
• :host — строка или список строк, содержащих область видимости хоста либо префикс области видимости хоста, например "foo.bar.com", "foo."
• :private — карта приватных данных, добавляемых к соединению при совпадении маршрута
• :assigns — карта данных, добавляемых к соединению при совпадении маршрута
• :log — уровень журналирования диспетчеризации маршрута; можно задать false. По умолчанию — :debug. Запись диспетчеризации содержит сведения об обработке маршрута (какое действие контроллера вызывается, какие параметры доступны и какие конвейеры используются) и ведётся отдельно от журналирования на уровне plug. Чтобы изменить уровень журналирования plug, см. https://phoenix.hexdocs.pm/Phoenix.Logger.html#module-dynamic-log-level.

Определяет область видимости с указанным путём.

Эта функция является сокращённой записью для:

scope path: path do
  ...
end

Примеры

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

Определяет область видимости с указанными путём и псевдонимом.

Эта функция является сокращённой записью для:

scope path: path, alias: alias do
  ...
end

Примеры

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

Создаёт маршрут для обработки trace-запроса по указанному пути.

trace("/events/:id", EventController, :action)

Сведения о параметрах см. в разделе match/5.