用 rdmanet.Conn 薄适配器替掉 rsocket：rpcx RDMA 传输重构全解析

• 后端
• 微服务

rpcx 通过一个 "network" 字符串（tcp、http、kcp、quic、unix、memu、iouring 等）选择底层传输，其中实验性的rdma传输藏在 Go 构建标签rdma之后。本篇围绕 tasks/prd-rdma-conn-transport.md 这份 PRD 展开，讲清楚一次典型的传输层替换是如何设计的：把 RDMA 数据路径从第三方rsocket包切换到github.com/smallnest/gordma/rdmanet的Conn，并只用一层薄适配器补齐net.Conn接口缺口。读完后，你能掌握 rpcx 传输注册机制的工作原理、rdmanet.Conn与net.Conn的适配细节，以及一套"默认构建逐字节不变"的兼容性验收方法。

背景：rpcx 用两张注册表选择传输

rpcx 的传输选择建立在两张 map 之上：

• 客户端：client.ConnFactories[network]，工厂函数返回net.Conn；
• 服务端：server.makeListeners[network]，工厂函数返回net.Listener。

tcp、http、kcp、quic、unix、memu、iouring 都按同一契约接入，client/connection.go 中的init()注册了 http/kcp/quic/unix/memu/iouring 各工厂，client/connection_rdma.go 和 server/listener_rdma.go 则以//go:build rdma标签注册"rdma"键。Client.Connect的默认分支会查ConnFactories，查不到再回退newDirectConn：

// client/connection.go（节选） default: fn := ConnFactories[network] if fn != nil { conn, err = fn(client, network, address) } else { conn, err = newDirectConn(client, network, address) }

改造前，rdma这一格绑死在第三方github.com/smallnest/rsocket上——rsocket 直接把net.Conn/net.Listener都实现好了，接入只要两行：

// 改造前：client/connection_rdma.go return rsocket.DialTCP(address) // rsocket 直接给一个 net.Conn // 改造前：server/listener_rdma.go return rsocket.NewTCPListener(host, p, blog) // rsocket 直接给一个 net.Listener

代价是整条 RDMA 数据路径锁死在一个演进不受控的第三方库上。PRD 的目标很直接：用rdmanet.Conn/rdmanet.Listener接管这两处，让 rpcx 跑在自家维护的 RDMA 栈（gordma）上。

接口差距：rdmanet.Conn 只差"接口形状"

与底层裸端点rdmanet.RawConn不同，rdmanet.Conn已经内置了消息分帧、基于信用的流控和托管缓冲，自带Read/Write/Close——本质上是一条 RDMA 上的io.ReadWriteCloser。它距离 Go 的net.Conn接口只缺两样东西：

// rdmanet.Conn 已有的能力（已经够用）： func (c *Conn) Read(p []byte) (int, error) func (c *Conn) Write(p []byte) (int, error) func (c *Conn) Close() error func (c *Conn) LocalAddr() string // 注意：string，不是 net.Addr func (c *Conn) RemoteAddr() string // 注意：string，不是 net.Addr // 没有 SetDeadline / SetReadDeadline / SetWriteDeadline // rdmanet.Listener.Accept() 返回 *rdmanet.Conn（不是 net.Conn）；Addr() 返回 string。

所以适配层的全部工作就是把类型对齐：string → net.Addr、补三个 no-op 的 deadline 方法、把Accept()的返回值再包一层。Read/Write/Close原样透传，数据路径一行都不碰。

适配器实现：一个文件封住全部 RDMA 特异性

PRD 的 US-001 和 US-004 两个故事合并落地在 share/rdma_conn.go，整个文件在//go:build rdma标签之后。

net.Conn 适配器

// share/rdma_conn.go（节选） type RDMAConn struct { *rdmanet.Conn // 内嵌：Read/Write/Close 自动透传 } var _ net.Conn = (*RDMAConn)(nil) func (c *RDMAConn) LocalAddr() net.Addr { return RDMAAddr(c.Conn.LocalAddr()) } func (c *RDMAConn) RemoteAddr() net.Addr { return RDMAAddr(c.Conn.RemoteAddr()) } // deadline 三件套：rdmanet.Conn 没有原生 deadline，统一做成 no-op。 func (c *RDMAConn) SetDeadline(t time.Time) error { return nil } func (c *RDMAConn) SetReadDeadline(t time.Time) error { return nil } func (c *RDMAConn) SetWriteDeadline(t time.Time) error { return nil }

几个实现要点：

• 内嵌而非包装：结构体内嵌*rdmanet.Conn，Go 的方法提升机制让Read/Write/Close零成本透传，适配器不重新分帧、不重新缓冲。这是它和裸端点适配方案的本质区别——后者要在适配器里手写长度前缀分帧和残留缓冲，这边一行都不写。
• RDMAAddr类型：把 rdmanet 的字符串地址包成net.Addr，Network()恒返回"rdma"，String()返回原始字符串：

type RDMAAddr string func (a RDMAAddr) Network() string { return "rdma" } func (a RDMAAddr) String() string { return string(a) }

• 编译期接口断言：var _ net.Conn = (*RDMAConn)(nil)让"形状对齐"在编译期就有保证——这是薄适配器最强的正确性证明。

net.Listener 适配器

// share/rdma_conn.go（节选） type RDMAListener struct { *rdmanet.Listener } var _ net.Listener = (*RDMAListener)(nil) func (l *RDMAListener) Accept() (net.Conn, error) { c, err := l.Listener.Accept() // 返回 *rdmanet.Conn if err != nil { return nil, err } return NewRDMAConn(c), nil } func (l *RDMAListener) Addr() net.Addr { return RDMAAddr(l.Listener.Addr()) }

Accept()调用底层rdmanet.Listener.Accept()拿到*rdmanet.Conn，包成RDMAConn返回；Addr()完成string → net.Addr转换；Close()直接依赖内嵌的*rdmanet.Listener提升。

客户端与服务端接线：工厂函数各改几行

客户端工厂：rdmanet.DialTimeout

client/connection_rdma.go 对应 PRD 的 US-002，完整实现只有二十几行：

//go:build rdma // +build rdma package client import ( "errors" "net" "github.com/smallnest/gordma/rdmanet" "github.com/smallnest/rpcx/share" ) func init() { ConnFactories["rdma"] = newRDMAConn } func newRDMAConn(c *Client, network, address string) (net.Conn, error) { if network != "rdma" { return nil, errors.New("network is not rdma") } conn, err := rdmanet.DialTimeout(address, c.option.ConnectTimeout) if err != nil { return nil, err } return share.NewRDMAConn(conn), nil }

要点：

• 使用rdmanet.DialTimeout(address, c.option.ConnectTimeout)而非无超时版本，直接复用 rpcx 客户端已有的ConnectTimeout配置项，语义与 tcp 等其他传输保持一致；
• 返回前先经share.NewRDMAConn包成net.Conn，对上层Client完全透明；
• network != "rdma"的防御性检查原样保留，文件保持//go:build rdma标签。

服务端工厂：rdmanet.Listen 与 host:port

server/listener_rdma.go 对应 PRD 的 US-003：

func rdmaMakeListener(s *Server, address string) (ln net.Listener, err error) { // Validate and normalize the host:port form rdmanet uses for its TCP // out-of-band handshake address. rdmanet.Listen exposes no backlog knob, // so the former RDMA_BACKLOG env var no longer applies. host, port, err := net.SplitHostPort(address) if err != nil { return nil, err } l, err := rdmanet.Listen(net.JoinHostPort(host, port)) if err != nil { return nil, err } return share.NewRDMAListener(l), nil }

地址沿用host:port形式——这是rdmanet.Conn做 TCP 带外握手（out-of-band handshake）所用的地址，net.SplitHostPort+net.JoinHostPort完成校验与归一化，保证与现状相比无回归。值得注意的是源码注释明确说明：rdmanet.Listen不再暴露 backlog 参数，因此旧版RDMA_BACKLOG环境变量已失效——PRD 中"保留或映射 RDMA_BACKLOG"这条验收项，最终以"不再适用"收口。

init()中的makeListeners["rdma"] = rdmaMakeListener注册模式原样不动：接入点没变，只换了返回值的来源。

依赖治理：把 rsocket 连根拔掉

PRD 的 US-005 要求依赖图彻底干净，验收标准是grep -r rsocket --include=*.go .零命中。从 go.mod 可以看到最终状态：github.com/smallnest/rsocket已不在依赖列表中，取而代之的是github.com/smallnest/gordma v0.3.0（子包rdmanet）。CHANGELOG.md 的 1.9.4 条目也印证了这次切换：

switch the experimentalrdmatransport from rsocket to gordma's rdmanet.Conn (build tagrdma)

选择彻底删除而非并存的理由很实际：留着 rsocket 当备选，等于让模块多扛一个不维护的依赖、多一条没人走的代码路径；既然rdmanet.Conn全面接管了 RDMA 路径，就从go.mod/go.sum连根拔掉。

关键设计取舍

PRD 与配套设计文档（tasks/design-rdma-conn-transport.md）对四个核心取舍给出了明确论证。

为什么用 rdmanet.Conn 而不是 RawConn

这是本次设计最关键的岔路：

PRD 的 Non-Goals 明确了边界：不使用RawConn、不在 rpcx 侧做手工分帧/批处理/流控、不在 RPC 数据路径中使用单边 RDMA Write/Read 动词。取舍逻辑是：本次目标是"干净地替掉 rsocket、让 rpcx 跑在自家 RDMA 栈上"，正确和薄比"榨干线速"更重要。若未来要打满线速，再回到 RawConn 路线。

为什么是"适配器"而不是改传输抽象

最朴素的做法是让 rpcx 协议层直接认识rdmanet.Conn，但这会侵入核心读写循环、破坏net.Conn这层统一抽象，只为一个实验性传输买单。适配器把 RDMA 特异性关在一个文件里（share/rdma_conn.go被 client 和 server 共用），上层零改动——直接服务于"默认构建不变"的硬承诺。PRD 的 Open Questions 曾权衡"单文件共享 vs 各自一份"，最终落地为单个共享文件，由NewRDMAConn/NewRDMAListener两个构造函数对外提供。

为什么 deadline 做成静默 no-op 而不是报错

rdmanet.Conn没有原生 deadline 支持，选项有三个：报not supported错、给读写加尽力而为的超时、或静默 no-op。rpcx 的调用路径会主动SetDeadline——例如 client/connection.go 中IdleTimeout逻辑会执行conn.SetDeadline(...)；若 RDMA 连接返回错误会直接打断正常 RPC 流程。硬塞超时又是在 v1 引入一套未经真机验证的半成品语义。最终选择：返回 nil、不生效、注释写清是已知 no-op。宁可诚实地"暂不支持"，也不假装支持——FR-4 把它写成了硬性需求，源码中三个方法的注释也都如实标注了这一点。

构建隔离：rdma 标签就是总开关

全部 RDMA 代码待在//go:build rdma之后，这是 PRD 的 FR-9，也是整个方案的硬约束：

• 不开rdma标签时，默认构建产物与 rpcx 公开 API 一个字节都不变；
• gordma 的 Linux 实现路径走 cgo + libibverbs，stub 构建返回gordma.ErrNotSupported，所以非 RDMA 主机上跑默认构建与 CI 完全不受影响；
• 只有真正开启-tags rdma才需要在装了 libibverbs 的 Linux 主机上编译。

兼容性：谁会被影响，怎么迁移

对默认用户，这不是破坏性变更。全部改动在 build tag 后面，不开标签的人无需任何动作。

对已经在用-tags rdma+ rsocket 的用户，这是破坏性变更，代价有三：

1. 线缆不兼容：rdmanet.Conn的握手与分帧和 rsocket 不互通，两端必须同时升级，不能混部；
2. 行为变化：deadline 从"由 rsocket/TCP 实现"变成 no-op，依赖 RDMA 连接读写超时的代码需知晓；
3. 依赖变化：go.mod移除 rsocket、新增 gordma，下游执行go mod tidy会看到依赖图变动。

迁移路径很直接：rdma标签本身就是特性开关，在 RDMA 主机上重新构建、两端同时切换即可。由于这是藏在 build tag 后的实验性传输，破坏面有限，不提供线缆层兼容垫片。

验收标准与验证方式

PRD 的 Success Metrics 给出了一套可机械执行的验收闸门：

• grep -r rsocket --include=*.go .零命中；
• go build ./...（默认标签）通过；
• go build -tags rdma ./...在 libibverbs Linux 主机上编译通过；
• rpcx 客户端能通过rdmanetwork 调用 rpcx 服务端，且 RPC 语义与tcp一致。

由于适配器不碰数据路径，逻辑层几乎没有可单独单测的东西——编译期接口断言（var _ net.Conn = (*RDMAConn)(nil)）承担形状正确性，真正的功能验证落在真机端到端：rpcx client overrdma调通 server，依赖 libibverbs 的 Linux 主机。

遗留问题

PRD 结尾的 Open Questions 也值得记录，它们定义了 v1 之后的演化方向：

• 真机-tags rdma端到端验证能否在现有 CI 环境完成，还是只能在独立 RDMA Linux 主机上做？
• 是否把WithBufferSize/WithQueueDepth等rdmanet选项经环境变量（类似旧RDMA_BACKLOG）透出？PRD 倾向 v1 全用默认值，因为Conn自管缓冲——最终实现也遵循了这一倾向（rdmanet.Listen未暴露 backlog 旋钮）；
• 与姊妹方案（RawConn 路线）的关系：两版设计文档并存于 tasks/ 目录，未来若要极限吞吐再评估切换。

小结

这次重构的价值在于示范了一种低风险的传输替换范式：接口差多少，就只写多少适配代码。rdmanet.Conn距离net.Conn只差net.Addr类型和 deadline 方法族，于是全部新增代码就是一个约百行的 share/rdma_conn.go 加两个各二十几行的工厂函数；协议、编解码、字节流零改动；默认构建逐字节不变；依赖图干净到grep可验证。对于任何想把 rpcx（或同架构框架）接到自定义底层网络栈上的开发者，这套"注册表 + build tag + 薄适配器"的组合都值得直接参照。

• 后端
• 微服务