Node.js gRPC客户端请求序列化失败，无法与Kotlin服务端通信

问题场景 #

通过buf-build生成TypeScript和Java代码，搭建Node.js gRPC客户端与Kotlin gRPC服务端的跨语言通信时，调用接口出现序列化失败错误：

Error: 13 INTERNAL: Request message serialization failure: Expected argument of type com.example.resources.chat.v1.GetActiveChatSessionsRequest

相关定义与代码如下：

Proto消息定义 (chat.proto) #

syntax = "proto3";

package com.example.resources.chat.v1;
option java_package = "com.example.resources.chat.v1";

import "google/protobuf/timestamp.proto";

message ChatRoomOverviewItem {
    string support_ticket_id = 1;
    string chat_room_id = 2;
    int32 number_of_unread_messages = 3;
    google.protobuf.Timestamp last_message_received = 4;
    repeated string participants = 5;
}

message GetActiveChatSessionsRequest {
    string participant_id = 1;
    int32 page = 2;
    int32 limit = 3;
}

message GetActiveChatSessionsResponse {
    bool last = 1;
    int32 total_elements = 2;
    int32 total_pages = 3;
    int32 number_of_elements = 4;
    bool first = 5;
    int32 number = 6;
    bool empty = 7;
    repeated ChatRoomOverviewItem content = 8;
}

gRPC服务定义 (chat-api.proto) #

syntax = "proto3";

package com.example.resources.chat.v1;
option java_package = "com.example.resources.chat.v1";

import "com/example/resources/chat/v1/chat.proto";

service ChatApiService {
    rpc GetActiveChatSessions (GetActiveChatSessionsRequest) returns (GetActiveChatSessionsResponse);
}

Node.js客户端代码 #

export const chatService = new ChatApiServiceClient(
    process.env.CHAT_GRPC_URI || 'http://localhost:6565', ChannelCredentials.createInsecure())

// 调用逻辑
chatService.getActiveChatSessions(new GetActiveChatSessionsRequest()
                .setParticipantId(userId)
                .setPage(req.params.page ? parseInt(req.params.page) : 0)
                .setLimit(req.params.limit ? parseInt(req.params.init) : 25),
            async (error, response) => {
                if (error) throw error
                else {
                    /* handle logic */
                }
            })

Kotlin服务端代码 #

@GRpcService
class ChatApiService(
    private val streamObserverHandler: GrpcStreamObserverHandler,
    private val chatRoomService: ChatRoomService,
    private val chatMessageService: ChatMessageService
) : ChatApiServiceImplBase() {

    override fun getActiveChatSessions(
        request: Chat.GetActiveChatSessionsRequest,
        responseObserver: StreamObserver<Chat.GetActiveChatSessionsResponse>
    ) {
        streamObserverHandler.accept(
            chatRoomService.getActiveChatRoomsForUser(
                UUID.fromString(request.participantId),
                PageRequest.of(request.page, request.limit)
            ),
            responseObserver
        )
    }
}

排查与解决方法 #

1. 修复客户端参数拼写错误 #

Node.js客户端代码中setLimit的参数存在明显错误：

.setLimit(req.params.limit ? parseInt(req.params.init) : 25)

此处错误引用req.params.init而非req.params.limit，会导致limit字段被赋值为无效值（如NaN），破坏消息序列化结构。修正为：

.setLimit(req.params.limit ? parseInt(req.params.limit) : 25)

2. 统一protobuf代码生成规则 #

• 确保Node.js与Kotlin端使用完全相同版本的proto文件通过buf-build生成代码，避免因定义不一致导致的序列化不兼容。
• 检查buf.yaml配置文件，确认两端的生成参数（如语言版本、插件版本）保持一致。

3. 修正gRPC客户端地址格式 #

gRPC客户端连接地址需使用host:port格式，无需http://前缀：

export const chatService = new ChatApiServiceClient(
    process.env.CHAT_GRPC_URI || 'localhost:6565', ChannelCredentials.createInsecure())

前缀会导致gRPC无法正确解析地址，间接引发通信或序列化错误。

4. 校验参数类型有效性 #

确保page和limit为合法的int32类型，避免传入非数字值：

const page = req.params.page ? parseInt(req.params.page, 10) : 0;
const limit = req.params.limit ? parseInt(req.params.limit, 10) : 25;

// 校验参数合法性
if (isNaN(page) || page < 0) throw new Error("无效的page参数");
if (isNaN(limit) || limit <= 0 || limit > 100) throw new Error("无效的limit参数");

chatService.getActiveChatSessions(new GetActiveChatSessionsRequest()
    .setParticipantId(userId)
    .setPage(page)
    .setLimit(limit),
    // 回调逻辑
)

5. 启用gRPC日志定位细节 #

在Node.js客户端开启详细日志，查看序列化过程的具体报错：

process.env.GRPC_VERBOSITY = 'DEBUG';
process.env.GRPC_TRACE = 'all';

通过日志可精准定位到序列化失败的字段或环节。

内容的提问来源于stack exchange，提问作者J.Pip