Go-Zero on 姚玉亮的网络日志

gRPC 在宠物医疗 SaaS 微服务通信中的落地实践

Fri, 22 Sep 2023 10:30:00 +0800

HTTP+JSON 顶了一阵，问题也攒了一阵

宠物医疗 SaaS 拆成 go-zero 微服务后，挂号、诊疗、收费、库存四个服务之间调用很频繁。最开始图省事，服务间直接用 HTTP+JSON 通信，结果问题很快就来了：接口字段没有强约束，收费服务改了个字段名，挂号服务没同步，直接 panic；JSON 序列化在病历这种嵌套结构上性能也不理想；更头疼的是没有统一的错误码，上游拿到一个 500，完全分不清是业务异常还是系统故障。

我们决定把内部通信统一切到 gRPC。

proto 怎么设计

设计上我们守着一条大原则：每个服务一个独立的 proto package。请求和响应消息都带 BaseResp 作为统一返回体，业务错误码不通过 gRPC status 传，而是放在 BaseResp 里。

为什么不走 status？gRPC status 适合表达 RPC 层的错误，比如超时、服务不可用；业务错误（宠物已建档、医生号源已满这类）要走 status 的话，拦截器很难把两类区分开。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


syntax = "proto3";
package clinic;
option go_package = "./clinic";

message BaseResp {
 int32 code = 1;
 string msg = 2;
}

message CreateMedicalRecordReq {
 int64 pet_id = 1;
 int64 doctor_id = 2;
 string chief_complaint = 3;
 repeated string symptoms = 4;
}

message CreateMedicalRecordResp {
 BaseResp base = 1;
 int64 record_id = 2;
 string record_no = 3;
}

service ClinicService {
 rpc CreateMedicalRecord(CreateMedicalRecordReq) returns (CreateMedicalRecordResp);
}

go-zero 生成的服务端代码里，我们在 etc/*.yaml 配置了监听地址和 etcd 注册：

1
2
3
4
5
6
7


Name: clinic.rpc
ListenOn: 0.0.0.0:8081
Etcd:
 Hosts:
 - etcd:2379
 Key: clinic.rpc
Timeout: 3000

客户端通过 zrpc.MustNewClient 拿到连接，自带轮询负载均衡和重试。我们额外加了一个客户端拦截器做统一的日志和错误处理：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


func UnaryClientInterceptor(ctx context.Context, method string,
 req, reply interface{}, cc *grpc.ClientConn,
 invoker grpc.UnaryInvoker, opts ...grpc.CallOption) error {

 start := time.Now()
 err := invoker(ctx, method, req, reply, cc, opts...)
 cost := time.Since(start)

 var code int32
 if err != nil {
 code = int32(codes.Code(err))
 }
 logx.WithContext(ctx).Infof("rpc call %s, code=%d, cost=%v", method, code, cost)
 return err
}

注册到客户端：

1
2
3


client := zrpc.MustNewClient(c.ClinicRpc,
 zrpc.WithUnaryClientInterceptor(UnaryClientInterceptor),
)

三个坑

第一个坑是 proto 字段的兼容性。gRPC 要求新增字段必须用新的 tag 编号，不能复用已删除字段的编号。我们早期有同事为了"整洁"，把废弃字段删掉后复用了编号，结果老客户端反序列化错乱。后来在 CI 里加了 buf breaking 检查，禁止不兼容变更合入主干。

第二个坑是大消息场景。病历里会附带影像图片（AI 判读结果），最开始直接用 bytes 塞进 gRPC 消息，超过 4MB 默认上限就报错。改法倒不复杂：消息里只传 S3 预签名 URL，影像文件走对象存储直传，gRPC 消息体控制在几十 KB。

第三个坑是错误处理的边界。业务错误码放 BaseResp 之后，调用方每次都得检查 base.code != 0，很容易漏。最后我们在 logic 层封装了一个 ToBaseResp(err) 方法，把业务 error 统一映射成错误码，上游只需要判断 err 是否为 nil，不用再手动解 BaseResp。

回头看

gRPC 在微服务内部通信上，强类型约束和性能提升都是实打实的。配合 go-zero 的 etcd 服务发现，连接管理基本不用自己碰。真正费心思的其实是 proto 设计的纪律：字段编号一旦分配不可复用，业务错误和 RPC 错误分层处理，大载荷走对象存储而不是塞进消息体。

封面图：David Davies / Flickr · CC BY-SA 2.0

从 fasthttp 迁移到 go-zero：一次 C/S 到 B/S 的架构重构实录

Wed, 06 Sep 2023 10:30:00 +0800

老架构走到头了

先交代下背景。我之前在一家做宠物医疗 SaaS 的公司，老版本是典型的 C/S 架构：Windows 客户端通过 fasthttp 与服务端保持长连接，消息分发用自定义二进制协议。早期跑得很稳，但门店扩张到数千家之后，问题一个个冒出来：客户端发版困难，协议升级要双端兼容，服务端没法水平扩容，毕竟长连接是绑在节点上的。最要命的是业务逻辑全塞在一个单体里，改一个挂号流程，整个系统要全量回归。

2023 年我们决定迁到 B/S 架构，浏览器直接访问，后端选了 go-zero。

怎么拆的

go-zero 吸引我的点是它自带的微服务治理能力：熔断、限流、降级、超时控制都是开箱即用，不用自己在业务代码里堆中间件。整体拆成 API 网关层和 RPC 服务层：

API 层用 go-zero 的 .api 文件定义 RESTful 接口，通过 goctl 生成路由、handler、types 骨架。
RPC 层用 goctl rpc new 生成 gRPC 服务，按领域拆成挂号、诊疗、收费、库存四个服务。
服务注册用 etcd，网关通过 zrpc 直连 RPC 客户端，带客户端负载均衡。

下面是 .api 文件的一个片段：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


syntax = "v1"

type (
 RegisterRequest {
 PetId int64 `json:"pet_id"`
 DoctorId int64 `json:"doctor_id"`
 DeptCode string `json:"dept_code"`
 }
 RegisterResponse {
 OrderNo string `json:"order_no"`
 Status int `json:"status"`
 }
)

service clinic-api {
 @handler RegisterHandler
 post /api/v1/register (RegisterRequest) returns (RegisterResponse)
}

生成的 handler 只做参数校验和调用 logic，业务全部下沉到 logic 层，再通过 zrpc 调用下游：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


func (l *RegisterLogic) Register(req *types.RegisterRequest) (*types.RegisterResponse, error) {
 resp, err := l.svcCtx.ClinicRpc.Register(l.ctx, &clinic.RegisterReq{
 PetId: req.PetId,
 DoctorId: req.DoctorId,
 DeptCode: req.DeptCode,
 })
 if err != nil {
 return nil, err
 }
 return &types.RegisterResponse{OrderNo: resp.OrderNo, Status: int(resp.Status)}, nil
}

zrpc 的客户端在 servicecontext.go 里初始化，自带 etcd 服务发现和中间件：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


type ServiceContext struct {
 Config config.Config
 ClinicRpc clinic.ClinicClient
}

func NewServiceContext(c config.Config) *ServiceContext {
 return &ServiceContext{
 Config: c,
 ClinicRpc: clinic.NewClinicClient(zrpc.MustNewClient(c.ClinicRpc).Conn()),
 }
}

迁移路上的三个坑

第一个坑是长连接怎么下线。老客户端还有存量门店在用，不能一刀切，我们在网关侧做了一层协议适配：fasthttp 接收老协议，转成 gRPC 调用新服务，灰度了两个月才彻底切掉。期间最麻烦的是老协议没有 trace 字段，跨协议排查问题完全是黑盒，只能在适配层强制注入 traceId。

第二个坑是 goctl 模板定制。默认生成的代码结构和我们团队的 DAO 规范有出入，我们 fork 了一份 template，把 GORM 和 Zap 日志注入进去，后续新服务直接用定制模板生成，省了不少重复劳动。

第三个坑是超时配置，也是最隐蔽的一个。go-zero 的超时是分层的，API 层、RPC 客户端、RPC 服务端都要设，而且要呈"倒金字塔"：外层超时必须大于内层，否则会出现上游已经返回超时、下游还在执行的空转。我们把 API 设成 5s，RPC 设成 3s，DB 查询设成 1s，基本覆盖了业务场景。

迁完之后

从 fasthttp C/S 迁到 go-zero B/S，最大的收益不是性能，是交付节奏。浏览器即开即用，发版不再依赖客户端升级；微服务拆分之后，单个服务可以独立部署。go-zero 的工具链和治理能力，让我们在没有专职中间件团队的情况下也能把微服务跑起来，这对中小团队很实在。

封面图：cbowns / Flickr · CC BY-SA 2.0