外观
集成指南
面向把业务接入 rust_svc 的开发者:调 API 的应用、机器对机器的凭据、 实时订阅、扩展平台,四种姿态各有一页说明。
六个集成面的导航
前三页是所有调用方的共同前提,后三页按集成深度选读:
| 页面 | 内容 | 适合谁 |
|---|---|---|
| 北向 REST API | 网关入口、路由表、通用约定 | 所有调用方 |
| 认证与令牌 | 登录/刷新、AppToken 生命周期、JWT 结构 | 所有调用方 |
| 错误模型 | problem+json 形状、错误头、重试策略 | 所有调用方 |
| gRPC 契约 | 7 份 proto 的服务与方法、租户上下文传播 | 深度集成方、平台内部 |
| WebSocket 订阅 | 帧格式、topic 授权、心跳与背压 | 实时消费方 |
| 插件 SDK | 插件三层形态、manifest、示例插件 | 平台扩展开发者 |
集成前的五步准备
- 确认平台地址:单机形态为
http://host:8080,云化形态经 ingress; - 向平台方索取租户与管理账号(
--bootstrap自举产物),或由平台方 在既有租户下为你的应用开账号; - 机器流量先建应用与 AppToken(
POST /api/v1/apps、POST /api/v1/tokens),再以POST /api/v1/auth/token换短时 JWT; - 写数据的场景默认拒绝:先由管理员在 IAM 配置 policy 或 access-rule, 再发起调用;
- 客户端实现 problem+json 错误解析与按错误码分段的重试策略。
契约事实源
| 面 | 事实源 | 校验手段 |
|---|---|---|
| REST | api/openapi/v1/openapi.yaml(OpenAPI 3.0.3,224 个路径) | 运行时 /openapi.yaml 与 /docs;解析校验入 CI |
| gRPC | api/proto/(7 份 proto) | buf lint 与 buf breaking |
| 错误码 | platform-core 的 error.rs 分段定义 | Segment::from_code 可反查校验 |
未接线的北向面
/api/v1/authz/*(授权管理)没有网关路由,北向访问返回 404/1004; 授权管理经服务 internal 面(经网关转发的 /api/v1/* 之外的运维通道) 或管理控制台完成。OIDC 一期已落地(IdentitySource 抽象与联邦登录 后端链路,见身份源与 OIDC),但 /oidc/ 回调 HTTP 面二期才开通——一期形态下联邦登录端到端不可用, /oidc/ 前缀仍为预留;LDAP/MFA 分期待办。