tmg-gw-r

tmg-gw-r คือ RESTful API Gateway ที่พัฒนาด้วย NestJS โดยใช้แนวทาง Clean Architecture และเชื่อมต่อ service ภายในผ่าน gRPC

จุดประสงค์ของโปรเจกต์

• เปิด REST API ให้ client ภายนอกใช้งานได้ง่าย
• แปลง request/response ระหว่าง REST กับ gRPC
• ควบคุมโครงสร้างให้ maintain ง่ายด้วย Clean Architecture
• มี Swagger สำหรับเอกสาร API ที่ดูและลองยิงได้ทันที

โครงสร้างแบบ Clean Architecture

src/
  application/
    ports/                  # สัญญา interface สำหรับติดต่อโลกภายนอก
    use-cases/              # business flow หลักของระบบ
  domain/
    entities/               # โมเดลหลักของโดเมน
  infrastructure/
    grpc/                   # ตัวเชื่อม gRPC ที่ implement port
  interfaces/
    rest/
      controllers/          # REST endpoints
      dto/                  # request/response models + validation + swagger metadata
  modules/                  # composition root ของแต่ละ bounded context

การใช้งาน CLI Generator

ติดตั้ง CLI:

npm i -g tmg-gw-r

ตัวเลือกคำสั่ง:

• --outDir <path> กำหนดโฟลเดอร์ปลายทาง (default: current directory)
• --overwrite เขียนทับโฟลเดอร์เดิมถ้ามีอยู่แล้ว
• -s, --service <serviceName...> ระบุรายชื่อ service ที่ต้องการ integrate (ใส่ได้หลายตัว)
• -sdir, --sdir, --servicesDir <path> ระบุโฟลเดอร์ services (default: services)

ตัวอย่าง:

tmg-gw-r g my-gateway --outDir . --overwrite

ตัวอย่าง integrate หลาย service:

tmg-gw-r g my-gateway \
  -s my-service users-service wallet-service \
  -sdir services \
  --outDir gateways \
  --overwrite

Service Integration (-s, -sdir)

เมื่อระบุ -s ตอน generate ระบบจะ:

• เพิ่ม env ต่อ service ใน .env.example เช่น USERS_SERVICE_GRPC_URL=localhost:50051
• ค้นหาไฟล์ proto จาก <servicesDir>/<service>/proto/*.proto
• คัดลอกไฟล์ .proto ไปไว้ใน <gateway>/proto

ตัวอย่างโครงสร้าง:

projectA/
  gateways/
  services/
    my-service/
    users-service/
    wallet-service/

REST และ gRPC Mapping

Users

• POST /api/v1/users -> UserService.CreateUser
• GET /api/v1/users/:id -> UserService.GetUser

Wallets

• POST /api/v1/wallets -> WalletService.CreateWallet
• GET /api/v1/wallets/:id -> WalletService.GetWallet

วิธีติดตั้งและรัน

1. ติดตั้ง dependencies

npm install

2. สร้างไฟล์ environment

cp .env.example .env

3. รันแบบ development

npm run start:dev

4. เปิด Swagger UI

• http://localhost:3002/docs

ค่าที่ต้องตั้งใน .env

• PORT พอร์ตของ gateway (default: 3002)
• TMG_B_GRPC_URL ที่อยู่ gRPC ของ service ภายใน (default: localhost:50051)

ตัวอย่างการเรียก REST API

สร้างผู้ใช้งาน

curl --location 'http://localhost:3002/api/v1/users' \
--header 'Content-Type: application/json' \
--data '{
  "name": "Tommy"
}'

ดึงผู้ใช้งาน

curl --location 'http://localhost:3002/api/v1/users/usr_01JXYZ'

สร้างกระเป๋าเงิน

curl --location 'http://localhost:3002/api/v1/wallets' \
--header 'Content-Type: application/json' \
--data '{
  "walletName": "Main Wallet"
}'

ดึงกระเป๋าเงิน

curl --location 'http://localhost:3002/api/v1/wallets/wlt_01JXYZ'

คำอธิบายการไหลของ request

1. Client เรียก REST endpoint ที่ controller
2. Controller validate ข้อมูลด้วย DTO + class-validator
3. Controller ส่งต่อไปยัง Use Case ในชั้น application
4. Use Case เรียก port interface โดยไม่รู้รายละเอียด infra
5. gRPC repository ในชั้น infrastructure เป็นผู้ implement port และเรียก gRPC service จริง
6. ผลลัพธ์ถูก map กลับเป็น domain entity แล้วแปลงเป็น REST response DTO

วิธีนี้ช่วยให้เปลี่ยน infra ภายหลัง (เช่นจาก gRPC ไป HTTP service) ได้ง่าย โดย business logic เดิมแทบไม่ต้องแก้