279 lines
12 KiB
Markdown
279 lines
12 KiB
Markdown
---
|
||
tags: [gRPC, Go, Server, Service]
|
||
create time: 2026-05-13 23:25
|
||
---
|
||
|
||
# Service Registration — 服务注册详解
|
||
|
||
## 概述
|
||
|
||
Service Registration 是把你的业务实现"告诉"gRPC server 的过程。你调用一次 `RegisterXxxServer()`，proto 编译器生成的元数据（`ServiceDesc`）就会被写入 server 内部的 dispatch table——此后每个到达的请求都能被正确路由到你的 handler。
|
||
|
||
本文聚焦三个核心问题：
|
||
1. Proto 到底生成了什么？ServiceDesc 在其中扮演什么角色？
|
||
2. 怎么把多个 service 注册到一个 server？底层路由怎么走？
|
||
3. 注册函数内部原理是什么？为什么签名是 `ServiceRegistrar` 而不是 `*grpc.Server`？
|
||
|
||
> [!tip] 前置知识
|
||
> 阅读本文建议先了解 [[hhs/gRPC/2. gRPC 核心篇/06-Service 定义与代码生成]]（proto 生成机制）和 [[hhs/gRPC/3. 服务端实现/08-Server 搭建与注册/00-Unimplemented 零-Stub 模式]]（Unimplemented 基类的作用）。
|
||
|
||
## Proto 生成的三类关键符号
|
||
|
||
看一段最普通的 proto 定义：
|
||
|
||
```proto
|
||
service UserService {
|
||
rpc CreateUser(CreateUserRequest) returns (CreateUserResponse);
|
||
rpc GetUser(GetUserRequest) returns (GetUserResponse);
|
||
}
|
||
```
|
||
|
||
运行 protoc 后，与你接下来要写的**业务代码**直接相关的有三类符号：
|
||
|
||
| 生成物 | 类型 | 你在业务代码中的用法 |
|
||
|--------|------|---------------------|
|
||
| `UserServiceServer` | interface | **嵌入 Unimplemented + 实现方法**来创建实现体 |
|
||
| `UnimplementedUserServiceServer` | struct | 嵌入到你自己的 struct 中获取默认行为 |
|
||
| `RegisterUserServiceServer()` | 函数 | 在 server 启动时调用，完成注册 |
|
||
| `UserService_ServiceDesc` | `grpc.ServiceDesc` | 自动注入到 Register 函数中，**你不需要直接操作它** |
|
||
|
||
### 生成的 Interface —— 封闭接口技巧
|
||
|
||
```go
|
||
type UserServiceServer interface {
|
||
CreateUser(context.Context, *CreateUserRequest) (*CreateUserResponse, error)
|
||
GetUser(context.Context, *GetUserRequest) (*GetUserResponse, error)
|
||
mustEmbedUnimplementedUserServiceServer() // ← 未导出
|
||
}
|
||
```
|
||
|
||
`mustEmbedUnimplementedUserServiceServer()` 是**未导出方法**（首字母小写），这就是 Go 社区经典的"封闭接口"技巧——其他任何想满足此接口的结构体必须显式嵌入 `UnimplementedUserServiceServer`，否则编译失败。
|
||
|
||
> [!question] 为什么这么设计？
|
||
> Proto 文件随时可能新增 RPC 方法。如果没有这个强制嵌入规则，开发者可能在升级 proto 后忘记补上新方法，导致线上服务静默返回错误。封闭接口把"漏实现"变成编译错误，把风险挡在开发阶段。
|
||
|
||
详细的零-Stub 模式机制参见 [[hhs/gRPC/3. 服务端实现/08-Server 搭建与注册/00-Unimplemented 零-Stub 模式]]。
|
||
|
||
### ServiceDesc —— 注册的真正核心
|
||
|
||
`ServiceDesc`（Service Descriptor）是所有注册逻辑的**元数据枢纽**。它描述了 service 的名称、所有方法的签名、处理函数等完整信息。Register 函数的本质就是把 ServiceDesc 塞进 server 的 internal map：
|
||
|
||
```go
|
||
var UserService_ServiceDesc = grpc.ServiceDesc{
|
||
ServiceName: "user.v1.UserService", // 全限定名，用于路由匹配
|
||
HandlerType: (*UserServiceServer)(nil), // 接口类型（仅用于类型检查）
|
||
Methods: []grpc.MethodDesc{ // Unary / Streaming 方法列表
|
||
{
|
||
MethodName: "CreateUser",
|
||
Handler: _UserCreateUser_Handler, // 实际的分发函数
|
||
},
|
||
{
|
||
MethodName: "GetUser",
|
||
Handler: _UserGetUser_Handler,
|
||
},
|
||
},
|
||
Streams: []grpc.StreamDesc{}, // 流式方法（本例没有）
|
||
Metadata: "user/v1/user.proto",
|
||
}
|
||
```
|
||
|
||
关键点：
|
||
- **`ServiceName`** 决定了请求的路由前缀——客户端调用的完整方法名就是 `user.v1.UserService/CreateUser`
|
||
- **`Methods`** 里列出了所有注册的服务方法，每个方法对应一个 `_XXX_Handler` 分发函数
|
||
- **`HandlerType`** 是个 nil 指针，纯粹用于编译期类型检查——确保传给 Register 的对象确实实现了该 interface
|
||
|
||
## 注册函数的内部原理
|
||
|
||
很多人以为 `RegisterXxxServer(s, srv)` 只是简单地把对象存起来。实际上它做了两件事：
|
||
|
||
```go
|
||
// 简化后的源码逻辑
|
||
func RegisterUserServiceServer(s grpc.ServiceRegistrar, srv UserServiceServer) {
|
||
s.RegisterService(&UserService_ServiceDesc, srv)
|
||
}
|
||
```
|
||
|
||
一行代码——把 ServiceDesc 和你的实现一起交给 server。但真正的逻辑在 `s.RegisterService()` 里面：
|
||
|
||
1. **校验**：检查 method name 是否已被注册过（重复注册会导致 panic）
|
||
2. **封装**：用你的 `srv` 实例包装 `_XXX_Handler` 分发函数，绑定上下文
|
||
3. **存储**：写入 server 内部的 `map[string]*method` dispatch table
|
||
|
||
### 为什么签名是 ServiceRegistrar 而不是 *grpc.Server？
|
||
|
||
仔细看生成代码的函数签名：
|
||
|
||
```go
|
||
func RegisterUserServiceServer(s grpc.ServiceRegistrar, srv UserServiceServer)
|
||
```
|
||
|
||
参数类型是 `grpc.ServiceRegistrar`（一个 interface），不是 `*grpc.Server`（一个 concrete type）：
|
||
|
||
```go
|
||
type ServiceRegistrar interface {
|
||
RegisterService(desc *ServiceDesc, svc any)
|
||
}
|
||
```
|
||
|
||
这看似多余，实际上有两个好处：
|
||
|
||
- **可测试性**：单元测试中可以 mock `ServiceRegistrar`，无需启动真实的 server 进程
|
||
- **扩展性**：任何实现了 `RegisterService` 的结构体都可以接受注册——比如自定义 wrapper、多端口路由器等未来场景
|
||
|
||
> [!important] 理解层次
|
||
> `*grpc.Server` 实现了 `ServiceRegistrar` + 更多方法（如 `Serve`, `Stop`, `GracefulStop`）。注册只需要 "注册服务的能力"，不关心 "如何监听网络"——这是典型的单一职责设计。
|
||
|
||
## 服务端实现的标准模式
|
||
|
||
结合 proto 生成的符号，标准的业务实现模板如下：
|
||
|
||
```go
|
||
// userService 是你的业务实现
|
||
type userService struct {
|
||
pb.UnimplementedUserServiceServer // ① 嵌入基类 → 零值安全
|
||
|
||
userStore UserStore // ② 依赖注入 → 数据库、缓存等
|
||
logger *zap.Logger // ③ 基础设施
|
||
}
|
||
|
||
// NewUserService 构造器：集中管理依赖
|
||
func NewUserService(store UserStore, logger *zap.Logger) *userService {
|
||
return &userService{
|
||
userStore: store,
|
||
logger: logger,
|
||
}
|
||
}
|
||
|
||
// ④ 只实现你需要暴露的方法——其余由 Unimplemented 提供默认拒绝响应
|
||
func (s *userService) CreateUser(ctx context.Context, req *pb.CreateUserRequest) (*pb.CreateUserResponse, error) {
|
||
user := &ModelUser{
|
||
Name: req.GetName(),
|
||
...
|
||
}
|
||
id, err := s.userStore.Create(ctx, user)
|
||
if err != nil {
|
||
return nil, status.Errorf(codes.Internal, "create user failed: %v", err)
|
||
}
|
||
return &pb.CreateUserResponse{Id: id}, nil
|
||
}
|
||
```
|
||
|
||
四个要点：
|
||
|
||
| 步骤 | 目的 | 说明 |
|
||
|------|------|------|
|
||
| ① 嵌入 Unimplemented | 防止 proto 升级后漏实现新方法 | 详见 [[hhs/gRPC/3. 服务端实现/08-Server 搭建与注册/00-Unimplemented 零-Stub 模式]] |
|
||
| ② 注入依赖 | 解耦业务逻辑与基础设施 | 通过构造器传入，而非全局变量 |
|
||
| ③ 注入日志 | 统一追踪体系 | 使用 zap 或 slog 均可 |
|
||
| ④ 选择性实现 | 灵活控制暴露面 | 只能整体注册 service，不能逐个方法注册 |
|
||
|
||
> [!warning] 常见反模式
|
||
> - ❌ 在 struct 中直接用全局变量拿 DB 连接 → 不可测试、线程不安全
|
||
> - ❌ 手动实现所有方法而不嵌入 Unimplemented → proto 升级时漏掉新方法
|
||
> - ❌ 在一个 service 里塞过多职责 → 考虑拆成独立的 proto service
|
||
|
||
## 单 Server 多 Service
|
||
|
||
单个 gRPC server 天然支持多个 service registration，互不影响：
|
||
|
||
```go
|
||
s := grpc.NewServer(opts...)
|
||
|
||
// 全部挂到同一个 server
|
||
pb.RegisterUserServiceServer(s, NewUserService(store))
|
||
pb.RegisterOrderServiceServer(s, NewOrderService(store))
|
||
pb.RegisterPaymentServiceServer(s, NewPaymentService(store))
|
||
|
||
s.Serve(lis) // 一个端口对外暴露三个 service
|
||
```
|
||
|
||
每个 service 完全独立：有自己的方法名空间、自己的 handler、自己的错误处理。它们共享同一个 listener 和连接池。
|
||
|
||
### 路由链路——从请求到你的 handler
|
||
|
||
一个完整的 RPC 请求到达 server 后的流转路径：
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant C as Client
|
||
participant H as HTTP/2 Layer
|
||
participant D as Dispatch Table
|
||
participant M as Method Handler
|
||
participant B as Your Business Logic
|
||
|
||
C->>H: gRPC request<br/>"/user.v1.UserService/CreateUser"
|
||
H->>D: 提取 method path 作为 key
|
||
D->>D: 查找 dispatch table
|
||
alt 找到匹配 entry
|
||
D->>M: _UserCreateUser_Handler(req)
|
||
M->>B: 调用 svc.(*userService).CreateUser(ctx, req)
|
||
B->>B: 执行业务逻辑 (DB / 缓存 / ...)
|
||
B-->>M: response + error
|
||
M-->>H: protobuf-encoded response
|
||
H-->>C: gRPC response
|
||
else 未找到匹配
|
||
D-->>H: UNIMPLEMENTED status
|
||
H-->>C: error response
|
||
end
|
||
```
|
||
|
||
路由 key 是完整的方法名 `/package.ServiceName/MethodName`，来源是 HTTP/2 的 header。server 内部维护了一个 `map[string]*MethodInfo` 结构的 dispatch table，key 就是 method name，value 就是你注册时绑定好的 handler。
|
||
|
||
### 什么时候需要多 Server？
|
||
|
||
虽然可以一个 server 挂所有 service，但有些场景你会**有意分开**：
|
||
|
||
| 场景 | 做法 | 原因 |
|
||
|------|------|------|
|
||
| 微服务拆分 | 每个服务独立进程 | 独立部署、独立扩缩容 |
|
||
| 内外网隔离 | 内网 server 只挂核心 service | 安全隔离，网关聚合 |
|
||
| 不同协议 | HTTP + gRPC | 不同 listener |
|
||
|
||
见 [[hhs/gRPC/3. 服务端实现/08-Server 搭建与注册/05-Multi-Port 多端口暴露]]。
|
||
|
||
## Service 的全生命周期
|
||
|
||
从 proto 定义到线上运行的完整链路：
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A["定义 .proto<br/>service Xxx { ... }"] --> B["protoc 生成代码<br/>_grpc.pb.go"]
|
||
B --> C["实现 XxxServer interface<br/>嵌入 Unimplemented"]
|
||
C --> D["构造器注入依赖<br/>NewXxxService(...)"]
|
||
D --> E["RegisterXxxServer(s, impl)"]
|
||
E --> F["s.Serve(lis)<br/>阻塞等待请求"]
|
||
F --> G["Client RPC 请求到达"]
|
||
G --> H["dispatch table 路由"]
|
||
H --> I["执行你的业务逻辑"]
|
||
|
||
style A fill:#E3F2FD
|
||
style B fill:#FFF4CC
|
||
style E fill:#A8E6CF
|
||
style I fill:#FFD43B,color:#000
|
||
```
|
||
|
||
## 常见问题
|
||
|
||
> [!question] 我可以只注册部分方法吗？
|
||
> 不行。注册的是整个 service（整个 interface），不是单个方法。如果你不想暴露某个方法，要么从 proto 里拆出去单独一个 service，要么在方法内部返回 permission denied。
|
||
|
||
> [!question] 同一个 service 能注册多次吗？
|
||
> 不能。对同一个 method name 调用两次 `RegisterXxxServer()` 会导致 server 启动时 panic。如果你在测试代码中反复创建了 server 实例，记得每次用 `grpc.NewServer()` 创建新的——不要复用旧实例。
|
||
|
||
> [!warning] ServiceName 必须唯一
|
||
> 如果你的 proto 文件中有两个 service 起了相同的 `ServiceName`（全限定名），第二个注册时会 panic。命名时养成习惯：始终带上 package 前缀（如 `user.v1.UserService`）。
|
||
|
||
> [!tip] 注册顺序不重要
|
||
> 无论你先注册 UserService 还是 OrderService，server 都会正确路由。因为 dispatch table 是按 method name 查找的，与注册先后无关。
|
||
|
||
> [!note] 生产环境：反射开关
|
||
> 开发时可以开启 reflection（[[hhs/gRPC/3. 服务端实现/08-Server 搭建与注册/04-Reflection 开发调试利器]]）方便用 grpcurl 调试，生产环境务必关闭——它会暴露完整的 API 结构给外部。
|
||
|
||
## 关联笔记
|
||
|
||
- [[hhs/gRPC/3. 服务端实现/08-Server 搭建与注册/00-Unimplemented 零-Stub 模式]]
|
||
- [[hhs/gRPC/3. 服务端实现/08-Server 搭建与注册/01-Hello World 最小可运行 Server]]
|
||
- [[hhs/gRPC/3. 服务端实现/08-Server 搭建与注册/04-Reflection 开发调试利器]]
|
||
- [[hhs/gRPC/3. 服务端实现/08-Server 搭建与注册/05-Multi-Port 多端口暴露]]
|
||
- [[hhs/gRPC/2. gRPC 核心篇/06-Service 定义与代码生成]]
|