连接平台服务与 RPC 调用

约 864 字大约 3 分钟

2025-03-03

平台服务间调用需要同时处理连接方式、客户端生命周期、身份上下文和业务错误。此处使用授权平台源码中的客户端；独立应用应使用公开 SDK，不要依赖私有服务实现。

direct 与 grpc

conf.RpcClientConf 包含 Mode 和 Conf 两部分：

模式	调用边界	使用前提
`direct`（默认）	AllInOne 进程内调用	被调用服务已完成同进程注册和初始化
`grpc`	网络 RPC	服务独立运行，可达且有访问控制

其他进程不能使用 direct 来访问平台。仅配置 Conf.Endpoints 而未改 Mode，也可能仍走默认 direct。

SysRpc:
  Mode: grpc
  Conf:
    Endpoints:
      - ${SYS_RPC_ENDPOINT}
    Timeout: 5000

Timeout 按 go-zero 客户端配置使用毫秒。也可使用 Target 或 Etcd 配置服务发现，具体字段以项目锁定版本为准；不添加不存在的 MaxIdle、MaxRetries 等配置。

在 ServiceContext 创建并复用客户端

以下函数展示系统用户客户端的初始化方式，可由本服务 NewServiceContext 调用：

// 本文件装配平台用户 RPC 客户端。
package svc

import (
    user "gitee.com/unitedrhino/core/service/syssvr/client/usermanage"
    "gitee.com/unitedrhino/core/service/syssvr/sysdirect"
    "gitee.com/unitedrhino/share/conf"
    "github.com/zeromicro/go-zero/zrpc"
)

// NewUserClient 按平台运行模式创建用户客户端；错误交由启动层处理。
func NewUserClient(c conf.RpcClientConf) (user.UserManage, error) {
    if c.Mode == conf.ClientModeDirect {
        return sysdirect.NewUser(), nil
    }
    client, err := zrpc.NewClient(c.Conf)
    if err != nil {
        return nil, err
    }
    return user.NewUserManage(client), nil
}

在 ServiceContext 中保留结果，logic 从 svcCtx 使用。不能在每次 HTTP 请求中建立 RPC 连接。direct 初始化失败要修正启动顺序，不能临时绕过校验。

业务调用与上下文

使用当前请求 ctx 传递取消、追踪和经过验证的身份。
平台客户端与调用链负责约定的身份 metadata，不能将用户自报身份当作可信来源。
后台任务明确绑定所属企业和执行身份，不能默认以全局管理员处理全部数据。
根据具体操作设置截止时间，不以全局无限超时掩盖依赖故障。

原生 gRPC pb 客户端与平台包装客户端并非同一层。自行使用 grpc.NewClient 时，还需按接入要求配置连接安全、拦截器和上下文传输；不要仅“能编译”就认为鉴权完成。

错误处理与重试

错误	建议处理
参数或业务条件不满足	返回平台业务错误，修正请求
未认证、无权限	修正身份、角色或资源授权，不重试绕过
超时、连接中断	根据操作幂等性决定是否重试
写请求返回不确定	使用业务幂等键查询结果，再决定补偿

控制设备、创建任务、扣减配额等写操作不能通用自动重试。调用端失败并不证明服务端没有执行成功。

验证与定位

先用只读请求确认端点、模式和身份，再验证受保护的读写接口。排查时按“进程是否启动 → 网络可达 → 模式与配置 → 服务注册 → metadata → 业务权限”定位。

至少覆盖 direct 与实际部署的 grpc 模式、正常/过期身份、跨企业/项目访问、调用取消及错误码透传。HTTP 入口和内部 RPC 的安全边界见中间件。

更新日志

2026/10/16 19:46

查看所有更新日志

b3b4d-docs(平台开发): 恢复有效专题并更新当前实现示例于 2026/10/16

后端专题

实时通信

业务能力