rewrite 지시문

rewrite 지시문 (URI 내부 재작성)

rewrite 지시문은 요청 URI를 내부적으로 재작성해요. 주로 **경로(path)**와 **쿼리 문자열(query)**을 조작하는 데 사용해요.

출처: Caddy 공식 문서

본문

요청 URI를 내부적으로 재작성해요.

재작성은 요청 URI의 일부 또는 전체를 바꿔요. URI에는 scheme이나 authority(호스트와 포트)가 포함되지 않고, 클라이언트는 보통 fragment를 보내지 않아요. 그래서 이 지시문은 주로 경로와 쿼리 문자열 조작에 쓰여요.

rewrite 지시문은 요청을 수정된 형태로 받아들이겠다는 의도를 나타내요.

같은 블록 안에서 다른 rewrite 지시문과 상호 배타적이에요. 그래서 서로 연쇄적으로 이어지는 재작성을 정의해도 안전해요. 첫 번째로 맞는 재작성만 실행되거든요.

rewrite 전에 요청에 맞던 요청 matcher는 rewrite 후에는 같은 요청에 맞지 않을 수 있어요. rewrite가 다른 핸들러와 route를 공유하게 하려면 route 또는 handle 지시문을 사용해요.

문법 (Syntax)

rewrite [<matcher>] <to>

• ****는 요청을 재작성할 URI예요. 재작성에 지정된 URI의 구성 요소(경로 또는 쿼리 문자열)만 처리돼요. URI 경로는 ? 앞에 오는 부분 문자열이에요. ?를 생략하면 토큰 전체가 경로로 간주돼요.

  경로 안의 placeholder가 ?를 포함한 값으로 확장되는 경우(예: 헤더 값이 /file?v=2일 때 rewrite {rp.header.X-Accel-Redirect}), ? 뒤 부분은 <to>에서 ? 뒤에 쿼리 문자열도 주어지지 않았을 때 쿼리 문자열을 대체해요. #로 시작하는 값의 모든 부분은 버려져요.

v2.8.0 이전에는 <to> 인자가 /로 시작하면 파서가 matcher 토큰으로 혼동할 수 있어서 와일드카드 matcher 토큰(*)을 지정해야 했어요.

비슷한 지시문 (Similar directives)

재작성을 수행하지만 의도가 다르거나, URI를 완전히 대체하지 않고 재작성하는 다른 지시문도 있어요:

• uri는 URI를 조작해요(접두사·접미사 제거 또는 부분 문자열 치환).

• try_files는 파일 존재 여부에 따라 요청을 재작성해요.

예시 (Examples)

모든 요청을 index.html로 재작성하고 쿼리 문자열은 그대로 두어요:

example.com {
	rewrite /index.html
}

v2.8.0 이전에는 첫 인자가 경로 matcher와 모호하기 때문에 와일드카드 matcher가 필요했어요. 즉 rewrite * /foo처럼요. 이제는 rewrite /foo로 단순화할 수 있어요.

모든 요청 앞에 /api를 붙이고 URI 나머지를 보존한 뒤 앱으로 리버스 프록시해요:

api.example.com {
	rewrite /api{uri}
	reverse_proxy localhost:8080
}

API 요청의 쿼리 문자열을 a=b로 바꾸고 경로는 그대로 둬요:

example.com {
	rewrite ?a=b
}

/api/ 요청에 대해서만 기존 쿼리 문자열을 보존하면서 키-값 쌍을 추가해요:

example.com {
	rewrite /api/* ?{query}&a=b
}

경로와 쿼리 문자열을 모두 바꾸면서, 원래 쿼리 문자열은 보존하고 원래 경로는 p 매개변수로 추가해요:

example.com {
	rewrite /index.php?{query}&p={path}
}

더 알아보기 (Learn more)

• Caddy 공식 문서