联犀开发者文档

HTTP、RPC 中间件与身份上下文

约 971 字大约 3 分钟

2025-03-03

中间件将认证、上下文、错误和审计能力接入调用链。平台业务通常复用 Core 的认证中间件与 Share 的 RPC 拦截器；独立应用使用 ur-kit 对应接入能力，见应用 SDK。

HTTP 请求链路

外部请求 → 身份校验 → 上下文与资源加载 → 路由/动作权限 → 业务数据权限 → 响应与审计

平台 CheckTokenWareMiddleware 校验用户或开放令牌，注入 ctxs.UserCtx 并加载资源。InitCtxsWare 参与上下文初始化；它本身不是令牌验证器。

在 .api 中声明现有服务已装配的中间件：

@server (
    group: demo/info
    prefix: /api/v1/demo/info
    middleware: CheckTokenWare,InitCtxsWare
)

生成后检查 ServiceContext 中两个字段都已绑定正确 Handle。中间件声明、构造和注册缺一不可；不能在生成文件中手工补一处，下一次生成又丢失。

认证参数

参数用途
ithings-token / token平台用户令牌
Authorization: Bearer <token>开放访问令牌
app-id当前应用 ID
tenant-code当前企业上下文，须由认证结果和权限检查约束
project-id当前项目选择，不能据此直接认定有项目权限
ithings-set-token响应中可能返回的更新令牌

常规 HTTP 客户端将认证信息放请求头。WebSocket 浏览器握手的限制及连接方式见WebSocket。不要把令牌输出到日志或提交到文档。

在 logic 中使用身份

ctxs.GetUserCtx(ctx) 读取已注入身份，ctxs.SetUserCtx 供可信调用链装配身份。业务层仍需处理身份缺失，读取正确企业、用户和项目，再执行资源检查。

身份上下文包含管理员、拥有者、角色及资源提供者结果。跨 RPC 的资源可能经过 JSON 解码，优先调用 Things 的 dataType.GetProjectResource 等统一助手，不能在每个业务中假定 map 一定保持原始 Go 类型。

RPC 服务端

平台 RPC 注册现有拦截器的典型片段：

// 为已创建的 zrpc 服务注入身份上下文与平台业务错误转换。
s.AddUnaryInterceptors(interceptors.Ctxs, interceptors.Error)

对应包为 gitee.com/unitedrhino/share/interceptors。Ctxs 解析约定 metadata 中的身份，Error 统一 RPC 业务错误与日志，并根据上下文处理语言。

身份 metadata 是内部传输格式，不是认证凭证。 ithings-user 的 base64 JSON 可以被构造；RPC 监听口必须有独立网络/传输访问控制，外部访问先经过可信认证入口。业务不能因 UserCtx 缺失就默认放行外部调用。

操作日志与基础安全

复用统一响应和错误格式，避免 handler 直接泄漏数据库错误。日志保留追踪标识和业务对象，密码、token、授权正文和文件二进制不得完整记录。

CORS、可信代理头、上传大小和安全头在实际 HTTP 入口统一配置。经过反向代理时，先验证代理配置是否保留认证头、状态码及 WebSocket Upgrade，不把代理任意传入的身份头直接信任。

最小验证矩阵

  1. 未登录、过期 token 返回正确错误；正常用户可访问自己获准的资源。
  2. 伪造身份头、切换企业或项目、直接构造对象 ID 均不能越权。
  3. HTTP 到 RPC 再到仓储的身份和取消信号能传递。
  4. 业务错误的编码、语言及空值与客户端合同一致。
  5. 审计不包含令牌和敏感正文；旧端网关受影响时单独验证。

路由动作与数据范围是两个层次，继续阅读接口权限和项目与区域数据权限。

更新日志

2026/10/16 19:46
查看所有更新日志
  • b3b4d-docs(平台开发): 恢复有效专题并更新当前实现示例于