企业官网建设流程全解析

• 后端
• RPC框架
• 微服务

本篇基于 rpcx 仓库中 方法级注册设计文档（配套需求见 PRD）解读一个安全特性：服务端注册 struct 时通过白名单精确圈定哪些方法暴露为 RPC 端点。读完你将理解"整个 struct 全量注册"这一默认行为的源码源头、白名单过滤与校验的实现位置、四条关键取舍（单一路径、白名单而非黑名单、报错而非静默、空名单报错），以及该特性在 server/service.go 与 server/service_test.go 中的完整落地证据。

背景：注册的粒度今天是"整个 struct"，而真实需求是"一个子集"

rpcx 服务端注册一个 struct，就把它所有签名合适的导出方法全开成 RPC。这条路径的源头在 server/service.go 的内部register函数中：

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

suitableMethods 会扫描typ的每个方法，把导出且签名匹配的全部收进service.method这张 map。签名校验规则很明确：方法必须是导出的、入参共 4 个（receiver、context.Context、参数、指针回复）、出参 1 个且为error、参数与回复类型必须导出。注册完成后，这些方法就都能被远程调用。

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

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

设计的第一原则是不另起炉灶。现有register(rcvr, name, useName)已经是Register和RegisterName共用的核心，给它加第四个参数methods []string：nil表示"全要"（旧行为），非 nil 表示"只要名单里的"。一条内部路径，两种公开入口。

四个公开入口，两条行为路径

当前仓库中四个入口都已落地，见 server/service.go：

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

新入口在公开层先做一道空名单拦截：

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) ... }

注意nil与空切片在这两个层面的语义不同：内部register收到nil才走旧的"全量"路径（只有公开的Register/RegisterName这么传）；公开的RegisterWithMethods/RegisterNameWithMethods收到nil或空切片都按"空名单"直接报错。

用法示例（README 中的真实示例，README.md）：

// Arith 有 Mul、Add、Sub 三个合适方法，但只允许 Mul/Add 被远程调用 s := server.NewServer() err := s.RegisterWithMethods(new(example.Arith), []string{"Mul", "Add"}, "") // 或者指定服务名： // err := s.RegisterNameWithMethods("Arith", new(example.Arith), []string{"Mul", "Add"}, "") s.Serve("tcp", addr)

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

核心逻辑就在 register 内部，suitableMethods先照常算出"所有合适方法"的 map，然后按白名单过滤；对名单里每个没命中的名字，再分流出具体错误原因：

// server/service.go register 内部 all := suitableMethods(service.typ, true) // 既有逻辑，全量 if methods == nil { // 无白名单：注册所有合适方法（原始行为） service.method = all } else { // 白名单：只注册点名的方法。调用方 //（RegisterWithMethods/RegisterNameWithMethods）已保证非空。 picked := make(map[string]*methodType) for _, m := range methods { if mt, ok := all[m]; ok { picked[m] = mt continue } // 不合适：区分"不存在这样的导出方法"与 // "存在但签名不是合适的 RPC 方法"两种情况。 if _, exists := service.typ.MethodByName(m); exists { errorStr := fmt.Sprintf("rpcx.Register: method %q of %s is not a suitable RPC method", m, sname) log.Error(errorStr) return sname, errors.New(errorStr) } errorStr := fmt.Sprintf("rpcx.Register: method %q not found on %s", m, sname) log.Error(errorStr) return sname, errors.New(errorStr) } service.method = picked }

两个边界值得注意：

• 过滤只决定"哪些方法进service.method"，不碰方法本身的调用、编解码、selector——下游一律照旧。
• 校验失败时的return发生在写入s.serviceMap之前（写入语句在 server/service.go#L245），所以不会留下半注册的 service。另外过滤后的service.method若最终为空，还会落到既有的 "no exported methods of suitable type"（含指针接收者提示）分支统一报错。

改造前 vs 改造后

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

理由与取舍：四个关键决策

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

最朴素的做法是新写一个registerWithMethods函数与register并存。设计文档明确没选，理由是两者除了"过滤那几行"几乎完全一样——并存等于把 service 构造、指针接收者提示、错误处理、写 map 这一长串逻辑抄两份，日后改一处要记得改两处。给register加一个methods参数、旧入口传nil，让新旧共用同一条路径，是改动最小、最不容易长歪的接法。代价是register的签名多了一个参数，但它是非导出函数，只需在包内调用点补nil，对包外用户完全不可见。

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

可以做成"排除某些方法"的黑名单。选白名单是因为这个特性的初衷是安全——"避免暴露不该暴露的方法"。白名单默认不暴露：你新加一个方法，除非显式列进名单，否则它不会悄悄变成 RPC 端点；黑名单则相反，新方法默认暴露，忘了加进黑名单就漏了。安全的默认应该是"默认关"，所以白名单。

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

静默忽略看着"宽容"，实则危险。你把"Add"拼成"add"，或把一个签名不符 RPC 形态的方法写进名单，静默忽略的结果是这个接口没被注册、却没人告诉你——直到线上调用方收到"方法不存在"才发现。实现上选用service.typ.MethodByName(m)把"根本不存在/非导出"和"存在但签名不符"分成两条错误信息：

• 不存在：rpcx.Register: method %q not found on %s
• 存在但签名不符：rpcx.Register: method %q of %s is not a suitable RPC method

宁可注册时吵一句，也不让接口静默缺失。

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

空名单（nil 或len==0）有三种可能的语义：全要、全不要、报错。"全要"会和Register重复且容易误用（本想填名单却传了空，结果全暴露，正好踩中要避免的事）；"全不要"注册一个零方法的 service 毫无意义。所以让它报错并提示"要全部就用Register/RegisterName"——把模糊地带关掉，逼调用方表达清楚意图。

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

Register/RegisterName的公开签名不变，行为不变——它们内部给register传nil，走的还是service.method = all那条老路，注册结果逐字节一致。新增的只有两个公开方法和一个非导出函数的参数。

唯一代价：内部register的签名多了一个参数。这是包内改动，需同步更新包内所有调用点（Register、RegisterName两处，各加一个nil），对包外用户完全不可见。没有迁移路径要写——老代码不用动，想用新能力的人改调一个新方法即可。

实现与验证：单文件改动 + 六组单测

改动集中在一个文件 server/service.go，分三步、可独立验证：

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

仓库中的测试 server/service_test.go 用一个专门的测试 struct 覆盖了全部四类分支：

// 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" }

运行方式：go test ./server/即可复现上述断言。

运行时视角：白名单外的方法会发生什么

过滤只影响注册，不影响调用链路。请求进来时，handleRequest 先按服务名查serviceMap，再查service.method[methodName]：

mtype := service.method[methodName] if mtype == nil { if service.function[methodName] != nil { // check raw functions return s.handleRequestForFunction(ctx, req) } err = errors.New("rpcx: can't find method " + methodName) return s.handleError(res, err) }

也就是说，白名单外的那个导出方法仍然存在于 struct 上、可被同进程代码正常调用，只是远程调用会收到rpcx: can't find method xxx错误——这正是"给本地用、别开成 RPC"的预期效果。并发安全沿用现有的serviceMapMu读写锁（见 server/server.go），没有引入新的并发模型。

未决问题

设计文档保留了三个开放项：

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

参考文件

• 设计文档：tasks/design-method-level-registration.md
• 需求文档：tasks/prd-method-level-registration.md
• 核心实现：server/service.go（四个入口 + 内部register）、suitableMethods
• 单元测试：server/service_test.go
• 请求分发（未注册方法的运行时行为）：server/server_dispatch.go
• 使用说明：README.md

• 后端
• RPC框架
• 微服务