Skip to content

集成指南 ​

面向把业务接入 rust_svc 的开发者:调 API 的应用、机器对机器的凭据、 实时订阅、扩展平台,四种姿态各有一页说明。

六个集成面的导航 ​

前三页是所有调用方的共同前提,后三页按集成深度选读:

页面内容适合谁
北向 REST API网关入口、路由表、通用约定所有调用方
认证与令牌登录/刷新、AppToken 生命周期、JWT 结构所有调用方
错误模型problem+json 形状、错误头、重试策略所有调用方
gRPC 契约7 份 proto 的服务与方法、租户上下文传播深度集成方、平台内部
WebSocket 订阅帧格式、topic 授权、心跳与背压实时消费方
插件 SDK插件三层形态、manifest、示例插件平台扩展开发者

集成前的五步准备 ​

  1. 确认平台地址:单机形态为 http://host:8080,云化形态经 ingress;
  2. 向平台方索取租户与管理账号(--bootstrap 自举产物),或由平台方 在既有租户下为你的应用开账号;
  3. 机器流量先建应用与 AppToken(POST /api/v1/apps、 POST /api/v1/tokens),再以 POST /api/v1/auth/token 换短时 JWT;
  4. 写数据的场景默认拒绝:先由管理员在 IAM 配置 policy 或 access-rule, 再发起调用;
  5. 客户端实现 problem+json 错误解析与按错误码分段的重试策略。

契约事实源 ​

面事实源校验手段
RESTapi/openapi/v1/openapi.yaml(OpenAPI 3.0.3,224 个路径)运行时 /openapi.yaml 与 /docs;解析校验入 CI
gRPCapi/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 分期待办。

相关页面 ​

以仓库代码为事实源构建 · RC Hardening 阶段