首页 / 工程规范 / gRPC 契约与接口安全
gRPC 契约与接口安全
Java/Go 双方 proto 契约、调用约定、接口分层与权限安全规则。
接口分层
| 层 | 前缀/入口 | 面向主体 |
|---|---|---|
| Admin Controller | /admin-api/...（Web Starter 按包匹配自动加前缀） | 后台 system_users 权限体系 |
| App Controller | /app-api/... | member_user 与 APP 登录上下文 |
| OpenAPI | /v3/api-docs、/swagger-ui | 接口文档（暴露与否由 springdoc 配置决定） |
| 内部调用 | Feign / gRPC / 同 JVM Bean | 模块间协作 |
示例：Admin 的 /system/user Controller 在单体中的完整前缀是 /admin-api/system/user；权限标识以 @PreAuthorize 为准。
gRPC 契约总表
Java 对外（Go 调用 Java）
| 模块 | proto 文件 | 服务/用途 |
|---|---|---|
| iot | grpc_iot_master_data.proto、grpc_iot_cache_out.proto | IoT 网关元数据、缓存输出 |
| prod-gps | grpc_prod_gps_geofence.proto、grpc_prod_gps_trip.proto、grpc_prod_gps_trip_data_report.proto | 围栏、行程、行程数据报表 |
| alarm | grpc_alarm_rule.proto、grpc_alarm_rule_cache_out.proto | 告警规则查询与缓存输出 |
| subscription | grpc_subscription_entitlement.proto | 权益鉴权（HasDeviceCapability 等） |
Go 对外（Java 调用 Go）
| 服务 | proto | 用途 |
|---|---|---|
| dmsvr | dm.proto | 设备 CRUD、物模型、分组 |
| dgsvr | dg.proto | 设备认证、下行链路控制 |
| geosvr | geo.proto | 最新位置、轨迹、DAU |
| videosvr | video.proto | StartLive、QueryRecordings、PtzControl |
| eventsvr | event.proto | RegisterRule、MatchEvent |
| iamsvr | iam.proto | PII 加解密、审计日志 |
| otasvr | ota.proto | 固件与升级任务 |
权限与敏感数据
- Controller 上的
@PreAuthorize权限标识、租户上下文和登录用户类型是接口契约的一部分，改动即破坏契约。 - 设备密钥、产品密钥、MFA secret、支付凭据与推送 Token 不得写入日志或 Wiki；排障只记录脱敏后的 ID、状态和时间。
- 视频流使用动态生成的短效临时凭证（WebRTC/HLS 阶段）。
- MCP 路径走独立端口，不纳入普通业务接口鉴权体系；AI 调用复用业务 Service 时按调用方身份隔离。
契约维护规则
- 修改 proto 后同步生成 Java 与 Go 代码（
mvn -pl ... -am compile触发 protoc；Go 用 goctl rpc protoc），生成代码不手改。 - 字段兼容：只增不改不删；废弃字段标记 reserved，避免二进制协议错位。
- 跨语言调用必须透传
Trace-Id、User-ID & Tenant-ID、Region。 - 接口变更需同步更新知识库契约页与相关调用方，评审环节列为必查项。