Đặt tên chủ đề

Table of Contents

Thiết kế phân cấp Subject

Cách đặt tên subject chính là API của hệ thống nhắn tin của bạn. Một hệ thống phân cấp được thiết kế tốt cho phép định tuyến, lọc và kiểm soát truy cập hiệu quả, đồng thời vẫn trực quan đối với các nhà phát triển.


Nguyên tắc thiết kế

Nguyên tắcLý do
Phân cấpCho phép đăng ký wildcard ở bất kỳ cấp nào
Dễ dự đoánNhà phát triển có thể tự xây dựng subject mà không cần tra cứu
Nhận biết môi trườngTách biệt production khỏi staging/development
Có thể lọcĐăng ký theo một phương tiện, một nhóm hoặc toàn bộ đội phương tiện
Có thể mở rộngThêm loại thông điệp mới mà không cần tái cấu trúc

Mẫu Subject cốt lõi

Tất cả subject của đội phương tiện đều tuân theo mẫu này:

fleet.<env>.veh.<vid>.<category>.<type>
Phân đoạnMô tảVí dụ
fleetKhông gian tên gốcLuôn là “fleet”
<env>Môi trườngprod, staging, dev
vehLoại tài nguyênPhương tiện (tương lai: gcs cho trạm điều khiển mặt đất)
<vid>ID phương tiệnVID-001, drone-alpha-7
<category>Danh mục thông điệpstate, evt, cmd, cmdack
<type>Loại cụ thểposition, battery, takeoff

Danh mục thông điệp

Trạng thái: fleet.<env>.veh.<vid>.state.*

Trạng thái hiện tại của phương tiện, được publish liên tục:

SubjectMô tảTần suất
state.positionVĩ độ/kinh độ/độ cao, vận tốc10 Hz
state.attitudeGóc roll/pitch/yaw10 Hz
state.batteryĐiện áp, dòng điện, dung lượng còn lại1 Hz
state.modeChế độ bay (AUTO, MANUAL, RTL)Khi thay đổi
state.healthTóm tắt tình trạng hệ thống1 Hz

Ví dụ publish:

subject := fmt.Sprintf("fleet.prod.veh.%s.state.position", vehicleID)
nc.Publish(subject, positionJSON)

Sự kiện: fleet.<env>.veh.<vid>.evt.*

Các sự kiện rời rạc, được publish khi chúng xảy ra:

SubjectMô tả
evt.armedPhương tiện đã được kích hoạt (arm)
evt.disarmedPhương tiện đã được vô hiệu hóa (disarm)
evt.takeoffBắt đầu cất cánh
evt.landedHạ cánh hoàn tất
evt.waypointĐã đến điểm tham chiếu (waypoint)
evt.failsafeCơ chế an toàn (failsafe) được kích hoạt
evt.geofenceVi phạm hàng rào địa lý (geofence)
evt.battery.lowCảnh báo pin yếu

Sự kiện là các chuyển đổi trạng thái, không phải dữ liệu liên tục. Chúng có tính bền vững—được lưu trong JetStream để phục vụ nhật ký kiểm toán.

Lệnh: fleet.<env>.veh.<vid>.cmd.*

Các chỉ thị được gửi đến phương tiện:

SubjectMô tả
cmd.armKích hoạt (arm) động cơ
cmd.disarmVô hiệu hóa (disarm) động cơ
cmd.takeoffBắt đầu cất cánh
cmd.landBắt đầu hạ cánh
cmd.rtlQuay về điểm xuất phát
cmd.gotoDi chuyển đến vị trí
cmd.mission.uploadTải lên nhiệm vụ
cmd.mission.startBắt đầu nhiệm vụ
cmd.param.setThiết lập tham số

Lệnh đi theo chiều xuống (downstream) từ hệ thống quản lý đội phương tiện đến các phương tiện.

Xác nhận lệnh: fleet.<env>.veh.<vid>.cmdack.*

Phản hồi cho các lệnh:

SubjectMô tả
cmdack.armKết quả lệnh arm
cmdack.takeoffKết quả lệnh cất cánh
cmdack.gotoKết quả lệnh goto

Payload của ack bao gồm:

{
  "cmd_id": "cmd-123456",
  "status": "accepted|rejected|completed|failed",
  "error": "optional error message",
  "timestamp": "2024-01-15T10:30:00Z"
}

Đăng ký wildcard

Wildcard của NATS cho phép đăng ký linh hoạt:

WildcardÝ nghĩaVí dụ
*Một tokenfleet.prod.veh.*.state.position
>Một hoặc nhiều tokenfleet.prod.veh.VID-001.>

Các mẫu đăng ký phổ biến

MẫuTrường hợp sử dụng
fleet.prod.veh.*.state.positionVị trí của tất cả phương tiện
fleet.prod.veh.VID-001.>Mọi thứ từ một phương tiện
fleet.prod.veh.*.evt.>Tất cả sự kiện từ tất cả phương tiện
fleet.prod.veh.*.state.batteryTất cả trạng thái pin
fleet.*.veh.VID-001.>Một phương tiện trên tất cả môi trường

KV Store: Shadow cho Digital Twin

JetStream KV store duy trì trạng thái mong muốn (desired) và được báo cáo (reported):

Mẫu Subject (KV)

fleet/<env>/veh/<vid>/desired
fleet/<env>/veh/<vid>/reported

Lưu ý: KV sử dụng dấu phân cách / (đường dẫn bucket), trong khi pub/sub sử dụng dấu phân cách ..

Trạng thái mong muốn

Những gì hệ thống quản lý đội phương tiện muốn phương tiện thực hiện:

{
  "mode": "AUTO",
  "mission_id": "mission-456",
  "geofence_enabled": true,
  "max_altitude": 120,
  "home_position": {
    "lat": 37.7749,
    "lon": -122.4194
  }
}

Trạng thái được báo cáo

Những gì phương tiện thực sự báo cáo:

{
  "mode": "AUTO",
  "mission_id": "mission-456",
  "mission_progress": 0.45,
  "geofence_enabled": true,
  "armed": true,
  "in_flight": true,
  "battery_remaining": 0.72
}

Đối chiếu Shadow

Vehicle Gateway liên tục:

  1. Đọc trạng thái mong muốn từ KV
  2. So sánh với trạng thái thực tế của phương tiện
  3. Phát lệnh để đưa thực tế về đúng trạng thái mong muốn
  4. Cập nhật trạng thái được báo cáo

Điều này cho phép quản lý đội phương tiện theo kiểu khai báo—thiết lập trạng thái mong muốn, để các phương tiện tự hội tụ về trạng thái đó.


Kiểm soát truy cập

Cơ chế phân quyền của NATS ánh xạ người dùng tới các subject được phép:

# Vehicle can publish its own state/events
publish: fleet.prod.veh.VID-001.state.>
publish: fleet.prod.veh.VID-001.evt.>
publish: fleet.prod.veh.VID-001.cmdack.>

# Vehicle can subscribe to commands for itself
subscribe: fleet.prod.veh.VID-001.cmd.>

# Vehicle can read/write its own shadow
kv: fleet/prod/veh/VID-001/*
# Fleet operator can subscribe to all state/events
subscribe: fleet.prod.veh.*.state.>
subscribe: fleet.prod.veh.*.evt.>
subscribe: fleet.prod.veh.*.cmdack.>

# Fleet operator can publish commands
publish: fleet.prod.veh.*.cmd.>

# Fleet operator can manage shadows
kv: fleet/prod/veh/*/desired

Điều này đảm bảo phương tiện không thể mạo danh phương tiện khác hoặc publish các lệnh trái phép.

Để tìm hiểu chi tiết về mô hình phân quyền, bao gồm cấp quyền cho bên thứ ba và quản lý thông tin xác thực, xem Phân quyền & Cấp quyền.


Đánh đổi trong thiết kế Subject

Tại sao không dùng subject phẳng?

Các subject phẳng như vehicle-001-position không hỗ trợ:

  • Đăng ký wildcard
  • Kiểm soát truy cập theo phân cấp
  • Nhóm theo logic

Tại sao không dùng phân cấp sâu hơn?

Các subject như fleet.prod.region.us-west.site.warehouse-a.veh.VID-001.state.position:

  • Khó xây dựng bằng lập trình hơn
  • Wildcard trở nên phức tạp
  • Thay đổi lan truyền khắp hệ thống

Phân cấp bốn cấp cân bằng giữa tính linh hoạt và sự đơn giản.


Định dạng thông điệp

Tất cả thông điệp đều sử dụng JSON với cấu trúc nhất quán:

{
  "vid": "VID-001",
  "timestamp": "2024-01-15T10:30:00.123Z",
  "seq": 12345,
  "data": {
    // message-specific payload
  }
}
TrườngMô tả
vidID phương tiện (trùng lặp với subject, nhưng hữu ích cho consumer)
timestampISO 8601 với độ chính xác đến mili giây
seqSố thứ tự tăng đơn điệu để sắp xếp thứ tự
dataPayload riêng của từng loại thông điệp

Tóm tắt

Danh mụcMẫu SubjectHướng
Trạng tháifleet.<env>.veh.<vid>.state.<type>Phương tiện → Hub
Sự kiệnfleet.<env>.veh.<vid>.evt.<type>Phương tiện → Hub
Lệnhfleet.<env>.veh.<vid>.cmd.<type>Hub → Phương tiện
Ackfleet.<env>.veh.<vid>.cmdack.<type>Phương tiện → Hub
Mong muốnfleet/<env>/veh/<vid>/desired (KV)Hub → Phương tiện
Được báo cáofleet/<env>/veh/<vid>/reported (KV)Phương tiện → Hub

Tiếp theo

Cấu hình Stream →