首页 / 系统架构 / 跨语言协作机制

跨语言协作机制

gRPC、NATS 主题、Redis 共享状态、TDengine 读写边界与鉴权上下文透传。

gRPCNATS集成
本页目录

协议边界与数据归属图

Java 与 Go 的协议边界与数据归属图
跨语言边界参考：权限与主数据归 Java，实时计算与状态机归 Go；gRPC 承担同步主数据/规则查询与缓存失效，NATS/JetStream 承担跨平台事件，Redis 保存可重建状态，MySQL/TDengine 分别保存业务与时序事实。来源：architecture/ChatGPT Image 2026年8月19日 15_17_55 (5).png。

同步调用：gRPC

Java → Go

Java 侧作为业务发起方调用 Go 获取设备详情或下发指令：

  • 设备管理 dmsvr：dm.proto（设备 CRUD、物模型解析、分组管理）
  • 设备接入 dgsvr：dg.proto（设备认证、下行链路控制）
  • 寻址：Nacos 服务发现获取 Go 实例 IP/Port；Java 通过 Nacos-Discovery 调用

Go → Java

Go 通过 Nacos 服务发现调用 Java gRPC，实例 metadata 约定：

Key类型说明
gRPC_portstring实例 gRPC 监听端口（引用 entrax.grpc.server.port）
gRPC_enabledstring固定 true，标识实例提供 gRPC 服务

Go 侧只配服务名（如 java-iot-server、java-subscription-server），流程：查询 Nacos 健康实例 → 过滤 gRPC_enabled=true → 读取 IP + gRPC_port → grpc.Dial。

对外 gRPC 服务：

Java 服务gRPC 服务用途
iotIotMasterDataServiceIoT 网关元数据
prod-gpsProdGpsGeofenceService、ProdGpsTripService、ProdGpsTripDataReportService围栏、行程与行程数据报表
alarmAlarmRuleService按设备查询启用规则
subscriptionSubscriptionEntitlementService设备能力/权益鉴权

异步事件：NATS 主题规范

主题常量集中在 go-share/events/topics/nats.go，Java/Go 共用同一套命名，禁止各自硬编码字符串。

设备交互主题

主题模式语义
device.up.<protocol>.<handle>.<productID>.<deviceName>设备上行原始消息
device.down.<protocol>.<handle>.<productID>.<deviceName>下行指令（dgsvr/dmsvr 订阅后向设备推送）
device.up.thing.<productID>.<deviceName> / device.down.thing.*物模型属性/事件/服务上下行
device.up.gateway.* / device.down.gateway.*网关与子设备
device.up.ota.* / device.down.ota.*OTA 升级上报与下发
device.up.shadow.* / device.down.shadow.*设备影子
device.up.config.* / device.down.config.*远程配置
device.up.log.* / device.down.log.*设备调试日志
device.up.status.connected / device.up.status.disconnected设备上线/下线内部通知
device.down.<protocol>.status.fix设备在线状态修复

应用事件主题（Java 订阅）

主题模式语义
application.device.<productID>.<deviceName>.status.connected / .disconnected设备登录状态推送
application.device.<productID>.<deviceName>.report.thing.property[.<propertyID>]物模型属性上报
application.device.<productID>.<deviceName>.report.thing.event.<type>.<eventID>物模型事件上报
application.device.<productID>.<deviceName>.report.thing.action.<actionID>.<req/resp>.<direction>服务调用上报
多副本消费必须指定 Queue Group，否则同一条消息被多个节点重复消费；告警、订单状态等不可丢失消息使用 JetStream 持久化模式。

共享状态与数据读写

数据存储Key/约定
设备在线状态Redis Hashthings:device:status:{productID}:{deviceName}
认证 TokenRedisauth:token:{userID}
核心元数据（用户/租户）MySQLJava 主写；Go 只读或缓存用于网关鉴权
GPS 轨迹与遥测TDengineGo 高频写；Java 只读报表，严禁 Java 高频写入关系库
区域隔离字段Go 写入带 region 字段，Java 报表按 region 过滤合规大区

鉴权上下文透传

跨语言调用必须透传以下 Header / Metadata，Go 拦截器据此做数据隔离判定：

  1. Trace-Id：全链路追踪 ID，用于 Java 报错到 Go 接入层的链路串联
  2. User-ID / Tenant-ID：注入 RPC Metadata，数据隔离判定依据
  3. Region：所属合规机房（EU/US/CN），Go 据此路由到正确的数据库分片

故障排查清单

  • Nacos 实例是否健康、metadata 是否携带 gRPC_port / gRPC_enabled。
  • proto 契约版本是否同步（Java 生成代码与 Go proto 是否一致），契约不一致是最常见的静默失败原因。
  • 跨语言调用是否透传 Trace-Id / User-ID / Tenant-ID / Region，缺失可能导致数据隔离拒绝。
  • NATS 主题是否按规范命名；消费端是否配置 Queue Group；不可丢失消息是否走 JetStream。
  • TDengine 写入是否正常；Java 侧只读，确认没有反向高频写入。