企业官网建设流程全解析

• 后端
• 微服务

本文基于 rpcx 仓库中的设计文档 design-method-level-registration.md 展开，完整介绍该特性的设计脉络：为什么 rpcx 原本"整个 struct 全量开 RPC"的粒度不够用、白名单式注册入口RegisterWithMethods/RegisterNameWithMethods如何设计、为什么选白名单而不是黑名单、为什么拼错方法名要报错而不是静默忽略，并对照仓库中已落地的实现 server/service.go、单测 server/service_test.go 与请求分发路径 server/server_dispatch.go，讲清这一特性的端到端行为。读完本文，你既能理解这套 API 的使用方式与校验规则，也能看懂其底层实现与"零破坏兼容"是如何保证的。

一、背景：注册粒度是"整个 struct"，但真实需求是"一个子集"

rpcx 服务端通过Register/RegisterName注册一个 struct 时，框架会用反射扫描它所有签名合适的导出方法，并把它们全部变成可被远程调用的 RPC 端点。设计文档指出，源头是 server/service.go 内部register中的这一行：

// server/service.go:172 —— register 内部 service.method = suitableMethods(service.typ, true) // 全部合适方法，无从挑选

suitableMethods（server/service.go#L329-L399）会遍历类型上的每个方法，按一组硬性规则筛选，只有全部满足的才会进入service.method这张方法表：

• 方法必须导出（非导出方法直接跳过）；
• 方法需要 4 个输入参数：接收者、context.Context、*args、*reply，其中第一个参数必须实现context.Context接口；
• 第二个参数类型必须是导出类型或内置类型；第三个参数必须是导出类型的指针；
• 有且只有一个返回值，且类型必须是error。

注册完成后，service.method中的方法就都能被远程调用——请求分发时 server/server_dispatch.go#L36-L43 直接以service.method[methodName]查表，命中即调用。

问题在于：导出 ≠ 想开成 RPC。一个 service struct 上常有些导出方法是给同进程其他代码复用的——比如同一份业务逻辑，既要被 rpcx 暴露，又要被 HTTP handler 或 jsonrpc 调用。在方法级注册出现之前，开发者没法表达"这个方法给本地用、别开成 RPC"：要么把方法改成非导出（同包代码也调不到了），要么把 struct 拆开。设计文档对应的用户诉求（GitHub Issue #581）正是"注册时指定具体注册哪些方法"，归因是避免暴露不该暴露的方法，并归入8.0版本规划。

设计文档用一句话给这个问题定性：

注册的粒度今天是"整个 struct"，而真实需求是"struct 上的一个子集"。缺的就是让调用方圈定子集的入口。

二、设计：白名单是 register 的一个可选参数，旧入口传 nil

核心设计原则只有一条：现有Register/RegisterName的签名与行为逐字节不变，零破坏是硬约束。

实现方式不另起炉灶：现有内部函数register(rcvr, name, useName)本就是Register和RegisterName共用的核心，给它加第四个参数methods []string即可——nil表示"全要"（旧行为），非 nil 表示"只要名单里的"。一条内部代码路径，两种公开入口。

公开 API 形态

// 旧入口：行为、签名都不动，内部传 nil func (s *Server) Register(rcvr interface{}, metadata string) error { sname, err := s.register(rcvr, "", false, nil) // ← 多一个 nil ... } // 新入口：白名单式 func (s *Server) RegisterWithMethods(rcvr interface{}, methods []string, metadata string) error func (s *Server) RegisterNameWithMethods(name string, rcvr interface{}, methods []string, metadata string) error

仓库中这两个入口已经落地，签名与设计文档完全一致，见 server/service.go#L118-L150：

// RegisterWithMethods is like Register but only registers the methods named in // the methods whitelist; all other exported methods of the receiver are not // exposed as RPC. It returns an error if methods is empty, or if any named // method does not exist on the receiver or is not a suitable RPC method. func (s *Server) RegisterWithMethods(rcvr any, methods []string, metadata string) error { if len(methods) == 0 { return errors.New("rpcx.Register: empty methods whitelist; use Register to register all methods") } sname, err := s.register(rcvr, "", false, methods) ... }

注意一个细节：两个新入口在进入内部register之前就做了len(methods) == 0的空白名单拦截（nil 与空切片都会命中），而旧入口Register/RegisterName固定传nil走全量路径。也就是说，"nil = 全量"这条语义只存在于包内部，公开 API 层面RegisterWithMethods收到 nil/空一律报错。

用法示例

以一个带 3 个导出方法的计算服务为例，只开放 2 个（README 中也给出了同样的最小示例，见 README.md 的 "Registering only selected methods" 小节）：

type Calc struct{} func (c *Calc) Add(ctx context.Context, args *Args, reply *Reply) error { ... } // 想开 func (c *Calc) Sub(ctx context.Context, args *Args, reply *Reply) error { ... } // 想开 func (c *Calc) Reset(ctx context.Context, ...) error { ... } // 仅本地 s.RegisterWithMethods(new(Calc), []string{"Add", "Sub"}, "") // Reset 不暴露

过滤 + 校验：在 suitableMethods 之后做一次分流

核心逻辑只有几行：suitableMethods先照常算出"所有合适方法"的 map，然后按白名单过滤；对名单里每个没命中的名字，再分流出具体错误原因。仓库中的实际实现（server/service.go#L178-L247）与设计文档中的骨架一致：

func (s *Server) register(rcvr any, name string, useName bool, methods []string) (string, error) { ... // Install the methods all := suitableMethods(service.typ, true) // 既有逻辑，全量 if methods == nil { // 旧路径：全要，行为不变 service.method = all } else { // 公开入口已保证 methods 非空，这里逐名过滤 + 校验 picked := make(map[string]*methodType) for _, m := range methods { if mt, ok := all[m]; ok { // 命中：合适且导出 picked[m] = mt continue } // 没命中：区分"根本不存在/非导出" vs "存在但签名不符" if _, exists := service.typ.MethodByName(m); exists { errorStr := fmt.Sprintf("rpcx.Register: method %q of %s is not a suitable RPC method", m, sname) ... return sname, errors.New(errorStr) } errorStr := fmt.Sprintf("rpcx.Register: method %q not found on %s", m, sname) ... return sname, errors.New(errorStr) } service.method = picked } ... s.serviceMap[service.name] = service // 写入 serviceMap 是最后一步 return sname, nil }

三个关键设计点：

1. 两条错误信息可区分。名单里的名字"根本不存在（或非导出）"与"存在但签名不是合法 RPC 方法"分别给出not found与not a suitable RPC method两种错误——用reflect.Type.MethodByName判断方法在类型上是否存在，一眼就能看出是拼错了名字还是方法签名不对。
2. 不会留下半注册的 service。校验失败时return发生在写入s.serviceMap之前（serviceMap的赋值是register的最后一个动作），所以任何一条校验错误都意味着这个 service 完全没有被注册。
3. 过滤只决定"哪些方法进service.method"，不碰方法本身的调用、编解码、selector 等下游逻辑——请求到来后的分发、解码、对象池、插件钩子一律照旧。

改造前 vs 改造后

改造前：Register(new(Calc)) → suitableMethods → {Add, Sub, Reset 中所有合适的} 全部开成 RPC 改造后：RegisterWithMethods(new(Calc), []string{"Add","Sub"}) → suitableMethods 算全量 → 按 {Add,Sub} 过滤 → 只开 Add、Sub （名单写错名字 / 写了签名不符的方法 / 空名单 → 直接报错，不注册）

三、理由与取舍：为什么是这些"反直觉"的决定

设计文档的 Rationale 一节给出了四个明确取舍，每一条都对应一种被否决的备选方案，值得逐条对照理解。

为什么加参数走一条路径，而不是另写一个 registerWithMethods

最朴素的做法是新写一个registerWithMethods函数与register并存。但两者除了"过滤那几行"几乎完全一样——并存等于把 service 构造、pointer-receiver 提示、错误处理、写 map 这一长串逻辑抄两份，日后改一处要记得改两处。给register加一个methods参数、旧入口传nil，是改动最小、最不容易长歪的接法。代价是register的签名多了一个参数，但它是非导出函数，只在包内几个调用点补一个nil，不影响任何用户。

为什么用白名单，而不是黑名单

可以做成"排除某些方法"的黑名单，但最终选白名单，因为特性的初衷是安全——"避免暴露不该暴露的方法"。两种模式的默认行为正好相反：

安全的默认应该是"默认关"，所以是白名单。

为什么名单里有不存在/签名不符的方法名要报错，而不是静默忽略

静默忽略看着"宽容"，实则危险：把"Add"拼成"add"，或把一个签名不符 RPC 形态的方法写进名单，静默忽略的结果是这个接口没被注册、却没人告诉你——直到线上调用方收到"方法不存在"才发现（这个"方法不存在"正是 server/server_dispatch.go#L36-L43 中mtype == nil分支返回的rpcx: can't find method ...）。设计上选择注册时直接报错，并用两条不同文案区分拼错与签名不符——宁可注册时吵一句，也不让接口静默缺失。

为什么空名单报错，而不是当成"全部"或"全不要"

空名单（nil 或len==0）有三种可能的语义，被逐一否决：

• "全要"：会和Register重复且容易误用——本想填名单却传了空，结果全暴露，正好踩中要避免的事；
• "全不要"：注册一个零方法的 service 毫无意义；
• "报错"：最终选择，并提示"要全部就用Register/RegisterName"——把模糊地带关掉，逼调用方表达清楚意图。

同时文档特别点明了nil与空切片的语义分界：内部register收到nil才是旧的"全量"路径（只有公开的Register/RegisterName这么传），而公开的RegisterWithMethods收到 nil/空都按空名单报错——这一点在实现中由新入口最前面的len(methods) == 0守卫保证（server/service.go#L122-L125、server/service.go#L138-L141）。

四、兼容性：纯增量变更，对现有用户零破坏

这是文档 Compatibility 一节的原话级结论，并且可以从当前仓库源码逐条验证：

• 公开签名不变：Register/RegisterName的函数签名与文档注释保持原样（server/service.go#L97-L116），内部改为s.register(rcvr, "", false, nil)/s.register(rcvr, name, true, nil)，走的仍是service.method = all那条老路，注册结果与旧版一致。
• 唯一代价是包内改动：内部register的签名多了一个参数，需要同步更新包内所有调用点（Register、RegisterName两处各加一个nil，另加两个新入口）。对包外用户完全不可见。
• 没有迁移路径要写：老代码不用动，想用新能力的人改调一个新方法即可。
• 并发模型不变：沿用现有serviceMapMu锁，不引入新的并发原语。

五、实现与过渡：三步改动，可独立验证

设计文档把实现拆成三步，改动集中在单个文件server/service.go：

1. 改内部register签名加methods []string，实现"nil 走全量、非 nil 走过滤+校验"的分流；更新Register/RegisterName两处调用传nil。
2. 加两个公开入口RegisterWithMethods/RegisterNameWithMethods，各自把名单透传给register，注册成功后照旧走Plugins.DoRegister。
3. 补单测：白名单子集生效、名单含不存在方法报错、含签名不符方法报错（两条错误信息不同）、空名单报错、且任一错误下 service 未进serviceMap。

这三步在当前仓库中均已落地，可以直接作为"证据链"逐条对照：

证据一：现有行为无回归

现有 server 包的测试套件全部通过，证明Register/RegisterName没有回归。

证据二：新单测覆盖子集生效与四类错误分支

server/service_test.go 用一个精心构造的WhitelistArith类型覆盖了所有验收分支（server/service_test.go#L37-L118）：

// WhitelistArith exposes two suitable RPC methods (Add, Sub), one exported // method with an unsuitable signature (NotRPC), and one unexported method. type WhitelistArith int func (t *WhitelistArith) Add(ctx context.Context, args *Args, reply *Reply) error { ... } func (t *WhitelistArith) Sub(ctx context.Context, args *Args, reply *Reply) error { ... } // NotRPC is exported but is not a suitable RPC method (wrong signature). func (t *WhitelistArith) NotRPC() string { return "not rpc" }

对应的五个测试函数与断言要点：

这里正好印证了文档"形状的证据"：白名单过滤后service.method的 key 集合等于名单集合，可直接断言。

证据三：白名单外的方法确实不可被远程调用

PRD 验收标准要求"白名单外的导出方法不可被远程调用（调用返回方法不存在错误）"。从源码结构看，这一点由分发路径天然保证：server/server_dispatch.go 的handleRequest中，service.method[methodName]查不到且service.function[methodName]也没有时，直接返回rpcx: can't find method <name>。白名单过滤只是让这张表变小，分发逻辑无需任何改动。

另外两处佐证可以在仓库中找到：CHANGELOG.md 记录了该特性（"add RegisterWithMethods/RegisterNameWithMethods to register only a whitelist of a struct's methods (#581)"），README.md 的 Examples 一节给出了带Arith的最小示例及三条白名单规则（白名单式、坏名字报错、空名单报错）。

六、Open Questions：文档中留白的问题与设计边界

设计文档末尾的 Open Questions 给出了当前定论，以及配套的 PRD prd-method-level-registration.md 中明确的 Non-Goals，共同划定了这个特性的边界：

未决/后续增强：

• 方法名匹配是否需要大小写不敏感？当前定：精确匹配——Go 方法名本就大小写敏感，跟随语言语义。
• 是否提供辅助函数列出"某 struct 上所有可注册方法名"，方便用户构造白名单？倾向后续增强，不进本版。
• RegisterFunction系列要不要类似能力？当前定：不在范围——函数级注册本就是单个函数，没有子集问题。

明确不做（Non-Goals）：

• 不支持黑名单，只做白名单；
• 不改Register/RegisterName的签名（不引入可变参数或 functional option）；
• 不做方法级访问控制/鉴权——白名单只决定"是否注册为 RPC"，不涉及调用时的权限；
• 不支持运行时动态增删已注册 service 的方法（注册即固定）；
• 不统一 HTTP handler / jsonrpc 的导出模型；不改RegisterFunction/RegisterFunctionName。

七、小结

这套方法级注册的设计可以浓缩为三句话：

1. 一条内部路径，两种公开入口——内部register增加methods []string参数，nil走全量、非 nil 走过滤，新旧入口共用同一套 service 构造与错误处理逻辑；
2. 白名单 + 全量校验——没列名的方法默认不暴露；名单里任何不存在、签名不符或整体为空的名字都会让注册立刻失败且不留半成品，错误信息区分"拼错"与"签名不符"两种情况；
3. 零破坏——Register/RegisterName签名与行为逐字节不变，下游分发、编解码、插件链路完全复用，改动收敛在 server/service.go 一个文件内。

对使用者的实际意义是：同一个 struct 上的方法，从此可以精确区分"对外 RPC"与"本地复用"两个用途，而安全默认从"导出即暴露"翻转为"点名才暴露"。

• 后端
• 微服务