kbmMW 5.0 cung cấp khả năng triển khai máy chủ REST một cách nhanh chóng và trực quan trong môi trường Delphi. Dưới đây là hướng dẫn từng bước để tạo một dịch vụ REST cơ bản, từ cấu hình nền tảng đến việc xuất dữ liệu dưới dạng JSON theo nhiều mức độ tự động hóa.

1. Thiết lập dự án VCL và cấu hình máy chủ

Tạo ứng dụng mới: File → New → VCL Forms Application.

Thêm hai thành phần sau vào Form:

• TkbmMWServer
• TkbmMWTCPIPIndyServerTransport

Thiết lập thuộc tính Server của TkbmMWTCPIPIndyServerTransport1 trỏ tới TkbmMWServer1.

Mở trình chỉnh sửa Bindings của bộ vận chuyển, thêm binding với địa chỉ 0.0.0.0 và cổng 80. Bạn có thể thay đổi cổng tùy ý (ví dụ: 8080), nhưng cần thông báo rõ cho người dùng REST.

Đặt thuộc tính StreamFormat của TkbmMWTCPIPIndyServerTransport1 thành REST.

Trong sự kiện OnCreate của Form, kích hoạt máy chủ:

procedure TForm1.FormCreate(Sender: TObject);
begin
  kbmMWServer1.AutoRegisterServices;
  kbmMWServer1.Active := True;
end;

Thêm đơn vị kbmMWRESTTransStream vào danh sách uses trong phần interface:

uses
  Winapi.Windows, Winapi.Messages, System.SysUtils, System.Classes,
  Vcl.Controls, Vcl.Forms, Vcl.Dialogs,
  kbmMWCustomTransport, kbmMWServer, kbmMWTCPIPIndyServerTransport,
  kbmMWRESTTransStream;

2. Tạo dịch vụ REST bằng Wizard

Chọn File → New → Other → Components4Developers → kbmMW Service.

Với mục tiêu xây dựng máy chủ REST thuần túy (không phục vụ file tĩnh), chọn mẫu Smart Service / kbmMW_1.0.

Nhập tên dịch vụ — ví dụ: ApiGateway — rồi nhấn Next cho đến khi hoàn tất.

Sau khi wizard tạo xong, mở tập tin mã nguồn (F12) để xem lớp dịch vụ đã sinh. Khai báo lớp sẽ tương tự như sau:

[kbmMW_Service('name:ApiGateway, flags:[listed]')]
[kbmMW_Rest('path:/api')]

TApiGatewayService = class(TkbmMWCustomSmartService)
public
  [kbmMW_Rest('method:get, path:status')]
  [kbmMW_Method]
  function GetSystemStatus: string;
end;

3. Triển khai phương thức trả về JSON

Dưới đây là ba cách phổ biến để trả về dữ liệu JSON từ phương thức REST:

Cách 1: Thủ công — chuỗi JSON tĩnh

function TApiGatewayService.GetSystemStatus: string;
begin
  Result := '{"status":"online","uptime_ms":12478}';
end;

Cách 2: Bán tự động — dùng TkbmMWONObject và TkbmMWJSONStreamer

uses
  kbmMWObjectNotation, kbmMWJSON;

function TApiGatewayService.GetSystemStatus: string;
var
  payload: TkbmMWONObject;
  serializer: TkbmMWJSONStreamer;
begin
  payload := TkbmMWONObject.Create;
  serializer := TkbmMWJSONStreamer.Create;
  try
    payload.AsString['status'] := 'online';
    payload.AsInt64['uptime_ms'] := GetTickCount64;
    Result := serializer.SaveToUTF16String(payload);
  finally
    serializer.Free;
    payload.Free;
  end;
end;

Cách 3: Tự động hoàn toàn — sử dụng lớp POCO và RTTI

Đầu tiên định nghĩa lớp dữ liệu:

type
  TStatusResponse = class
  private
    FState: string;
    FUptime: Int64;
  public
    property State: string read FState write FState;
    property Uptime: Int64 read FUptime write FUptime;
  end;

Cập nhật khai báo phương thức:

[kbmMW_Rest('method:get, path:status, anonymousResult:true')]
[kbmMW_Method]
function GetSystemStatus: TStatusResponse;

Triển khai phương thức:

function TApiGatewayService.GetSystemStatus: TStatusResponse;
begin
  Result := TStatusResponse.Create;
  Result.State := 'online';
  Result.Uptime := GetTickCount64;
end;

Thêm đoạn khởi tạo sau khối implementation:

initialization
  TkbmMWRTTI.EnableRTTI(TApiGatewayService);
  kbmMWRegisterKnownClasses([TStatusResponse]);

Lưu ý:

• Khi anonymousResult:true, kết quả JSON có dạng: {"State":"online","Uptime":12478}
• Khi anonymousResult:false, kết quả là: {"TStatusResponse":{"State":"online","Uptime":12478}}
• kbmMW tự động giải phóng đối tượng trả về nếu không khai báo freeResult:false trong thuộc tính [kbmMW_Rest]

4. Kiểm thử

Chạy ứng dụng, sau đó truy cập trong trình duyệt:

http://localhost/api/status

Đảm bảo viết đúng phân biệt hoa thường — đường dẫn /API/status hoặc /api/STATUS sẽ thất bại.

Bạn cũng có thể gọi phương thức này từ client kbmMW thông qua [kbmMW_Method], nhờ cơ chế đa giao thức tích hợp sẵn.

kbmMW hỗ trợ trả về nhiều kiểu dữ liệu phức tạp như TkbmMemTable, mảng, danh sách, hoặc thậm chí các đối tượng kế thừa — tất cả đều được tuần tự hóa tự động sang JSON khi dùng StreamFormat = REST.