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 các chi tiết thực hiện nội bộ hoặc đồng bộ hóa các 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ó cơ sở dữ liệu 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á đơ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 đề hiện có hoặc các mảng JSON

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 (string, boolean, number) khi sử dụng thêm hoặc bổ sung.
config.append.headers	Bổ sung các giá trị vào các tiêu đề hiện có. Định dạng: header-name:value
config.append.json	Bổ sung 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, number).

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

Bổ Sung 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 ký hiệu mảng (ví dụ: mảng JSON).
• Plugin này giữ toàn bộ thân phản hồi trong bộ nhớ trong quá trình chuyể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 chuyển đổi các payload nén gzip, hãy đảm bảo 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 ghi bởi Nginx.
• Các loại giá trị khóa JSON (json_types) là rất quan trọng khi bổ sung hoặc thêm 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 này, vui lòng tham khảo hướng dẫn này: Response Transformer - Plugin | Kong Docs