Response Transformer

Tổng Quan

Chính sách Response Transformer là một chính sách outbound, và nó sửa đổi phản hồi được trả về từ dịch vụ upstream trước khi gửi đến khách hàng. Sự chuyển đổi này cho phép:

• Thêm, xóa, thay thế, đổi tên hoặc bổ sung các tiêu đề phản hồi hoặc các trường JSON.
• Lọc hoặc cấu trúc lại các thân phản hồi.
• Che giấu hoặc chuyển đổi các trường nhạy cảm.
• Đảm bảo tính nhất quán của các payload phản hồi giữa các dịch vụ khác nhau.

Điều này đặc biệt hữu ích khi bạn muốn ẩn chi tiết triển khai nội bộ hoặc đồng bộ hóa phản hồi API với các hợp đồng của khách hàng bên ngoài.

ghi chú

Plugin này tương thích với chế độ không có DB và hỗ trợ các giao thức grpc, grpcs, http và https.

Chi Tiết Cấu Hình

Cấu hình sử dụng định dạng khóa-giá trị đơn giản để khai báo các hoạt động chuyển đổi. Mỗi hoạt động được định nghĩa dưới một không gian tên cụ thể và hỗ trợ cả tiêu đề và các trường thân JSON.

Thứ Tự Chuyển Đổi

Các chuyển đổi được thực hiện theo thứ tự sau:

1. Xóa
2. Đổi tên
3. Thay thế
4. Thêm
5. Bổ sung

Các Trường Chuyển Đổi Hỗ Trợ

Field	Description
remove	Xóa các tiêu đề phản hồi hoặc khóa JSON cụ thể
rename	Đổi tên các tiêu đề phản hồi hoặc khóa JSON hiện có
replace	Thay thế giá trị của các tiêu đề phản hồi hoặc khóa JSON hiện có
add	Thêm các tiêu đề phản hồi hoặc các trường JSON mới (thay thế các trường hiện có nếu đã có)
append	Bổ sung các giá trị bổ sung vào các tiêu đề hoặc mảng JSON hiện có

Các Tùy Chọn Cấu Hình Chính

Field	Description
config.add.headers	Thêm các tiêu đề phản hồi mới. Định dạng: header-name:value
config.add.json	Thêm các khóa JSON mới vào thân phản hồi. Định dạng: key:value
config.add.json_types	Thiết lập rõ ràng các loại giá trị JSON (chuỗi, boolean, số) khi sử dụng thêm hoặc nối.
config.append.headers	Nối các giá trị vào các tiêu đề hiện có. Định dạng: header-name:value
config.append.json	Nối các giá trị vào các khóa JSON hiện có.
config.remove.headers	Xóa các tiêu đề phản hồi hiện có. Định dạng: header-name
config.remove.json	Xóa các khóa JSON cụ thể khỏi phản hồi.
config.rename.headers	Đổi tên các tiêu đề. Định dạng: old-name:new-name
config.rename.json	Đổi tên các khóa JSON. Định dạng: old-key:new-key
config.replace.headers	Thay thế các giá trị tiêu đề. Định dạng: header-name:new-value
config.replace.json	Thay thế các giá trị khóa JSON. Định dạng: key:new-value
config.replace.json_types	Cần thiết khi thay thế các giá trị JSON bằng các loại không phải chuỗi (boolean, số).

Ví dụ

Ví dụ cơ bản - Thêm tiêu đề và khóa 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"]
		}
	}
}'

Nối tiêu đề và xóa trường 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"]
		}
	}
}'

Đổi tên khóa JSON và tiêu đề

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"

Ví dụ đầy đủ với nhiều hành động

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"]
		}
	}
}'

Ghi chú bổ sung

• Nếu một giá trị chứa dấu phẩy (,), thì phải sử dụng cú pháp mảng (ví dụ: mảng JSON).
• Plugin này giữ toàn bộ nội dung phản hồi trong bộ nhớ trong quá trình biến đổi, điều này có thể ảnh hưởng đến hiệu suất trên các phản hồi lớn.
• Khi biến đổi các payload nén gzip, hãy đảm bảo rằng tiêu đề Content-Encoding: gzip được xử lý đúng cách.
• Plugin này không sửa đổi các tiêu đề x-forwarded-* được viết bởi Nginx.
• Các loại giá trị khóa JSON (json_types) là rất quan trọng khi thêm hoặc bổ sung các trường số hoặc boolean.

Để biết thêm hướng dẫn và ví dụ nâng cao về việc sử dụng chính sách, vui lòng tham khảo hướng dẫn này: Response Transformer - Plugin | Kong Docs