본문으로 건너뛰기

Response Transformer

개요​

Response Transformer 정책은 아웃바운드 정책으로, 클라이언트에게 전달되기 전에 업스트림 서비스에서 반환된 응답을 수정합니다. 이 변환은 다음을 가능하게 합니다:

  • 응답 헤더 또는 JSON 필드를 추가, 제거, 교체, 이름 변경 또는 추가.
  • 응답 본문 필터링 또는 구조 조정.
  • 민감한 필드 마스킹 또는 변환.
  • 다양한 서비스 간 응답 페이로드의 일관성 보장.

이는 내부 구현 세부정보를 숨기거나 API 응답을 외부 클라이언트 계약에 맞추고자 할 때 특히 유용합니다.

노트

이 플러그인은 DB-less 모드와 호환되며 grpc, grpcs, http 및 https 프로토콜을 지원합니다.

구성 세부정보​

구성은 변환 작업을 선언하기 위해 간단한 키-값 형식을 사용합니다. 각 작업은 특정 네임스페이스 아래에 정의되며, 헤더와 JSON 본문 필드를 모두 지원합니다.

변환 순서​

변환은 다음 순서로 실행됩니다:

  1. 제거
  2. 이름 변경
  3. 교체
  4. 추가
  5. 추가

지원되는 변환 필드​

Field Description
remove특정 응답 헤더 또는 JSON 키 제거
rename기존 응답 헤더 또는 JSON 키 이름 변경
replace기존 응답 헤더 또는 JSON 키의 값 교체
add새로운 응답 헤더 또는 JSON 필드 추가 (이미 존재하는 필드는 교체됨)
append기존 헤더 또는 JSON 배열에 추가 값 추가

주요 구성 옵션​

FieldDescription
config.add.headers새로운 응답 헤더 추가. 형식: header-name:value
config.add.json응답 본문에 새로운 JSON 키를 추가합니다. 형식: key:value
config.add.json_types추가 또는 추가할 때 JSON 값 유형(문자열, 부울, 숫자)을 명시적으로 설정합니다.
config.append.headers기존 헤더에 값을 추가합니다. 형식: header-name:value
config.append.json기존 JSON 키에 값을 추가합니다.
config.remove.headers기존 응답 헤더를 제거합니다. 형식: header-name
config.remove.json응답에서 특정 JSON 키를 제거합니다.
config.rename.headers헤더 이름을 변경합니다. 형식: old-name:new-name
config.rename.jsonJSON 키 이름을 변경합니다. 형식: old-key:new-key
config.replace.headers헤더 값을 교체합니다. 형식: header-name:new-value
config.replace.jsonJSON 키 값을 교체합니다. 형식: key:new-value
config.replace.json_types비문자열 유형(부울, 숫자)으로 JSON 값을 교체할 때 필요합니다.

예제​

기본 예제 - 헤더 및 JSON 키 추가​

curl -X POST [http://localhost:8001/services/example-service/plugins](http://localhost:8001/services/example-service/plugins) \
	--header "Content-Type: application/json" \
	--data '{
		"name": "response-transformer",
		"config": {
			"add": {
				"headers": ["x-new-header:value", "x-another-header:something"],
				"json": ["new-json-key:some_value", "another-json-key:some_value"],
				"json_types": ["string", "boolean", "number"]
		}
	}
}'

헤더 추가 및 JSON 필드 제거​

curl -X POST [http://localhost:8001/services/example-service/plugins](http://localhost:8001/services/example-service/plugins) \
	--header "Content-Type: application/json" \
	--data '{
		"name": "response-transformer",
		"config": {
			"append": {
				"headers": ["x-header-1:v2", "x-header-2:v1"]
			},
			"remove": {
				"json": ["internal-field"]
		}
	}
}'

JSON 키 및 헤더 이름 변경​

curl -X POST [http://localhost:8001/services/example-service/plugins](http://localhost:8001/services/example-service/plugins) \
	--data "name=response-transformer" \
	--data "config.rename.headers=old-header:new-header" \
	--data "config.rename.json=old-key:new-key"

여러 작업이 포함된 전체 예제​

curl -X POST [http://localhost:8001/services/example-service/plugins](http://localhost:8001/services/example-service/plugins) \
	--header "Content-Type: application/json" \
	--data '{
		"name": "response-transformer",
		"config": {
			"remove": {
				"headers": ["x-toremove", "x-another-one"],
				"json": ["json-key-toremove", "another-json-key"]
		},
		"add": {
			"headers": ["x-new-header:value"],
			"json": ["new-json-key:some_value"],
			"json_types": ["string"]
		},
		"append": {
			"headers": ["x-existing-header:some_value", "x-another-header:some_value"]
		}
	}
}'

추가 참고 사항​

  • 값에 쉼표(,)가 포함된 경우 배열 표기법을 사용해야 합니다(예: JSON 배열).
  • 이 플러그인은 변환 중에 전체 응답 본문을 메모리에 유지하므로 큰 응답의 성능에 영향을 미칠 수 있습니다.
  • gzip 압축 페이로드를 변환할 때는 Content-Encoding: gzip 헤더가 올바르게 처리되도록 해야 합니다.
  • 이 플러그인은 Nginx에서 작성한 x-forwarded-* 헤더를 수정하지 않습니다.
  • JSON 키 값 유형(json_types)은 숫자 또는 부울 필드를 추가하거나 추가할 때 중요합니다.

정책 사용에 대한 추가 지침 및 고급 예제는 다음 가이드를 참조하십시오: Response Transformer - Plugin | Kong Docs