маршрут

Буквально и как единое целое оценивает группу директив.

Директивы, содержащиеся в блоке маршрута, не будут переупорядочены внутри. В блоке маршрута можно использовать только директивы обработчиков HTTP (директивы, которые добавляют обработчики или промежуточное ПО в цепочку).

Эта директива является особым случаем, так как ее поддирективы также являются обычными директивами.

Синтаксис

route [<matcher>] {
	<directives...>
}

• <directives...> — это список директив или блоков директив, по одной на строке, точно так же, как и вне блока маршрута; за исключением того, что эти директивы не будут переупорядочены. Можно использовать только директивы обработчиков HTTP.

Утилита

Директива route полезна в некоторых сложных случаях или особых ситуациях для полного контроля над частями цепочки обработчиков HTTP.

Поскольку порядок оценки промежуточного ПО HTTP важен, Caddyfile обычно переупорядочивает директивы после парсинга, чтобы Caddyfile было проще использовать; вам не нужно беспокоиться о том, в каком порядке вы набираете вещи.

Хотя встроенный порядок совместим со многими сайтами, иногда вам нужно взять на себя ручное управление порядком, либо для всего сайта, либо только для его части. Для этого предназначена директива route.

Рассмотрим случай двух завершающих обработчиков: redir и file_server. Оба записывают ответ в клиент и не вызывают следующий обработчик в цепочке, поэтому только один из них будет выполнен для определенного запроса. Так какой идёт первым? Обычно redir выполняется перед file_server, поскольку обычно вы хотите выполнить переадресацию только в определённых случаях и обслуживать файлы в общем случае.

Однако могут быть случаи, когда вторая директива (redir) имеет более специфический сопоставитель, чем вторая (file_server). Другими словами, вы хотите перенаправить в общем случае и обслуживать только определённый файл.

Поэтому вы можете попробовать Caddyfile, похожий на этот (но это не будет работать так, как ожидается!):

example.com {
	file_server /specific.html
	redir https://anothersite.com{uri}
}

Проблема в том, что после сортировки директив redir идёт перед file_server.

Но в этом случае сопоставитель для redir (явный *) является супермножеством сопоставителя для file_server (* является супермножеством /specific.html).

К счастью, решение простое: просто оберните эти две директивы в блок route, чтобы убедиться, что file_server выполняется перед redir:

example.com {
	route {
		file_server /specific.html
		redir https://anothersite.com{uri}
	}
}

И теперь file_server будет включена в цепочку до redir, потому что порядок взят буквально.

Похожие директивы

Существуют и другие директивы, которые могут обернуть директивы обработчиков HTTP, но каждая имеет своё применение в зависимости от желаемого поведения:

• handle оборачивает другие директивы, как и route, но с двумя отличиями: 1) блоки handle взаимно исключают друг друга, и 2) директивы внутри handle переупорядочиваются обычно.

• handle_path делает то же самое, что и handle, но удаляет префикс из запроса перед запуском обработчиков.

• handle_errors похожа на handle, но вызывается только тогда, когда Caddy обнаруживает ошибку во время обработки запроса.

Примеры

Запрашивает прокси-запросы к /api как есть, и переписывает все другие запросы на основе соответствия файлу на диске, иначе /index.html. Затем этот файл отображается.

Поскольку try_files имеет более высокий порядок директивы, чем reverse_proxy, то она обычно сортируется выше и выполняется первой; это приведет к тому, что все запросы API будут переписаны на /index.html и не будут соответствовать /api*, поэтому ни один из них не будет проксирован, а вместо этого будет получен ответ 404 от file_server. Обертка всего в route гарантирует, что reverse_proxy всегда выполняется первой, прежде чем запрос перепишется.

example.com {
	root * /srv
	route {
		reverse_proxy /api* localhost:9000
		try_files {path} /index.html
		file_server
	}
}