Nhảy đến nội dung chính

2. API Design & Response Standard

2.1. Mục Tiêu Chương

Chương này quy định cấu trúc chuẩn của mỗi integration flow và trách nhiệm của từng artifact layer nhằm:

  • Tách biệt rõ ràng các tầng xử lý trong luồng tích hợp
  • Giảm phụ thuộc giữa các thành phần artifact
  • Dễ bảo trì, mở rộng và kiểm thử từng layer độc lập
  • Đảm bảo tính nhất quán giữa các flow trong toàn hệ thống

2.2. Khái Niệm / Phạm Vi Áp Dụng

Quy tắc này áp dụng cho:

  • Tất cả các integration flow trong thư mục artifacts/**
  • Cả Core Team và Partner Team
  • Tất cả các luồng tích hợp mới được phát triển

Cấu Trúc Artifact Chuẩn

Mỗi integration flow gồm các thành phần sau:image.png

Ý Nghĩa Từng Artifact Layer
Layer Artifact Vai trò Ví dụ
API Layer apis/*.xml Nhận request từ client và trả response
KafkaProducerApi.xml, 
PlanningDirectApi.xml
Mediation Layer sequences/*-inboundSequence.xml Xử lý logic, điều phối luồng
Load_balance_example-inboundSequence.xml
Error Layer sequences/*-inboundErrorSequence.xml Xử lý và cô lập lỗi
Load_balance_example-inboundErrorSequence.xml
Consumer Layer inbound-endpoints/*.xml Nhận message từ Kafka topic
Load_balance_example.xml
Connection Layer local-entries/*.xml Cấu hình kết nối dùng chung
KafkaConnection.xml
Endpoint Layer endpoints/*.xml Định nghĩa backend endpoint Backend API address

2.3. Quy Định Chính

Trách Nhiệm Từng Layer

API Layer (apis/)

  • Nhận request HTTP từ client (hoặc từ WSO2 APIM Gateway)
  • Gọi backend trực tiếp hoặc publish message lên Kafka
  • Trả response chuẩn về client
  • Không chứa logic nghiệp vụ phức tạp

Mediation Layer (sequences/*-inboundSequence.xml)

  • Xử lý message nhận từ Kafka consumer
  • Điều phối lời gọi đến backend API
  • Phân loại kết quả theo HTTP status code (2xx / 4xx / 5xx)
  • Publish kết quả vào processed_topic hoặc error_topic
  • Không xử lý lỗi kỹ thuật (dành cho Error Layer)

Error Layer (sequences/*-inboundErrorSequence.xml)

  • Bắt lỗi kỹ thuật khi consume message từ Kafka
  • Log đầy đủ thông tin: ERROR_CODE, ERROR_MESSAGE, ORIGINAL_PAYLOAD
  • Đóng gói và publish message lỗi vào error_topic
  • Không retry — chỉ ghi nhận và chuyển sang error topic

Consumer Layer (inbound-endpoints/)

  • Kết nối đến Kafka broker và subscribe topic
  • Khai báo sequence (luồng thành công) và onError (luồng lỗi)
  • Không chứa logic xử lý

Connection Layer (local-entries/)

  • Lưu thông tin kết nối Kafka dùng chung toàn hệ thống
  • Chỉ Core Team được phép chỉnh sửa

Quy Tắc Bắt Buộc

 API Layer không được chứa logic nghiệp vụ phức tạp

Mọi response trả về client phải theo cấu trúc JSON chuẩn

Error sequence phải luôn publish message vào error_topic

Mediation sequence phải phân loại HTTP status (2xx / 4xx / 5xx)

Cấu Trúc Response Chuẩn

Thành công:

Thành công kèm data:

Lỗi từ API Layer:

Lỗi kỹ thuật (Error Sequence ghi vào error_topic):

2.4. Cách Thực Hiện / Quy Trình

Quy Trình Phát Triển Một Integration Flow Mới

Bước 1: Khai báo Connection (nếu chưa có)

Tạo hoặc tái sử dụng 

Chỉ Core Team thực hiện bước này.

Bước 2: Tạo Inbound Endpoint

Tạo file inbound-endpoints/<flow-name>.xml:

Bước 3: Tạo Error Sequence

Tạo file sequences/<flow-name>-inboundErrorSequence.xml:

Bước 4: Tạo Inbound Sequence

Tạo file sequences/<flow-name>-inboundSequence.xml:

Bước 5: Tạo API (nếu cần điểm vào HTTP)

Tạo file apis/<flow-name>Api.xml:

ho-so-core-flow (1).jpg

 Ví Dụ Đúng — Inbound Sequence phân loại HTTP Status

Đúng vì:

Ví Dụ Đúng — Error Sequence đóng gói lỗi chuẩn

 Ví Dụ Sai — Không phân loại HTTP Status

Sai vì:

 Ví Dụ Sai — API trả về raw data không theo chuẩn

Sai vì:

[Chỗ này thêm ảnh: Screenshot log WSO2 MI cho thấy STATUS, HTTP_STATUS, PAYLOAD được log đúng chuẩn]

2.6. Checklist Áp Dụng

Trước khi commit integration flow mới:

Tài liệu này thuộc phạm vi quản lý của Core Team — mọi thay đổi phải được Core Team phê duyệt.

Lên đầu trang