@micl/grpc-client

一个基于 Proxy 代理的 Node.js gRPC 客户端管理器，支持多种 RPC 调用方式。

✨ 特性

1. 单例模式管理多个 gRPC 客户端
2. 基于 Proxy 代理的自然 API 调用
3. 支持全部四种 RPC 类型（一元、服务端流、客户端流、双向流）
4. 基于 proto 文件加载服务定义
5. 内置连接保活机制
6. 完整的 TypeScript 类型支持

📦 安装

npm install @micl/grpc-client
# or
pnpm add @micl/grpc-client
# or
yarn add @micl/grpc-client

🎯 快速使用

注册和使用客户端

import { grpc, grpcClientManager, GrpcMethodType } from '@micl/grpc-client';

// 注册 gRPC 客户端（第一个参数是 package name）
grpcClientManager.register('example', {
  address: 'localhost:50051',
  credentials: grpc.credentials.createInsecure(),
  protos: ['./path/to/your/proto/file.proto'],
});

// 获取客户端
const client = grpcClientManager.get('example');

// 调用一元方法（通过 Proxy 代理）
const response = await client.Greeter.SayHello({ name: 'World' });

console.log(response.message); // Hello World

服务端流式调用

const stream = client.Greeter.StreamGreetings({ name: 'World' });

stream.on('data', (data) => {
  console.log(data.message);
});

stream.on('end', () => {
  console.log('Stream ended');
});

客户端流式调用

const stream = client.Greeter.ClientStreamGreetings((err, response) => {
  if (err) {
    console.error(err);
    return;
  }
  console.log('Final response:', response);
});

stream.write({ name: 'World 1' });
stream.write({ name: 'World 2' });
stream.end();

双向流式调用

const stream = client.Greeter.BidiStreamGreetings();

stream.on('data', (data) => {
  console.log(data.message);
});

stream.write({ name: 'World 1' });
stream.write({ name: 'World 2' });
stream.end();

📚 API 参考

grpcClientManager (GrpcClientManagerClass)

register(packageName, params)

注册一个 gRPC 客户端。

参数：

| 参数 | 类型 | 描述 | |------|------|------| | packageName | string | proto 文件中的包名称 | | params.address | string | gRPC 服务地址 | | params.credentials | grpc.ChannelCredentials | 通道凭证 | | params.protos | string[] | proto 文件路径数组 | | params.options | Record | 可选配置项 |

grpcClientManager.register('example', {
  address: 'localhost:50051',
  credentials: grpc.credentials.createInsecure(),
  protos: ['./proto/greeter.proto'],
  options: {
    'grpc.keepalive_time_ms': 60000,
  },
});

get(packageName)

获取已注册的客户端代理。

const client = grpcClientManager.get('example');

remove(packageName)

移除并关闭客户端。

grpcClientManager.remove('example');

clearAll()

移除并关闭所有已注册的客户端。

grpcClientManager.clearAll();

Proxy Client API

通过 get() 返回的客户端是一个 Proxy 对象，支持如下调用方式：

client.<ServiceName>.<MethodName>(...args)

一元 RPC (UNARY)

const response = await client.ServiceName.MethodName(request, metadata?);

服务端流式 RPC (SERVER_STREAM)

const stream = client.ServiceName.MethodName(request, metadata?);
stream.on('data', (data) => { /* ... */ });
stream.on('end', () => { /* ... */ });

客户端流式 RPC (CLIENT_STREAM)

const stream = client.ServiceName.MethodName(metadata?, callback);
stream.write(request1);
stream.write(request2);
stream.end();

双向流式 RPC (BIDI_STREAM)

const stream = client.ServiceName.MethodName(metadata?);
stream.on('data', (data) => { /* ... */ });
stream.write(request1);
stream.write(request2);
stream.end();

GrpcMethodType

导出的 RPC 类型常量：

import { GrpcMethodType } from '@micl/grpc-client';

GrpcMethodType.UNARY;        // 'unary'
GrpcMethodType.SERVER_STREAM; // 'server_stream'
GrpcMethodType.CLIENT_STREAM; // 'client_stream'
GrpcMethodType.BIDI_STREAM;  // 'bidi_stream'

📝 完整示例

import { grpc, grpcClientManager } from '@micl/grpc-client';

async function main() {
  // 注册客户端
  grpcClientManager.register('example', {
    address: 'localhost:50051',
    credentials: grpc.credentials.createInsecure(),
    protos: ['./proto/greeter.proto'],
  });

  const client = grpcClientManager.get('example');

  if (!client) {
    console.error('Client not found');
    return;
  }

  // 调用一元方法
  try {
    const response = await client.Greeter.SayHello({ name: 'World' });
    console.log('Response:', response);
  } catch (error) {
    console.error('Error:', error);
  }

  // 调用服务端流式方法
  try {
    const stream = client.Greeter.StreamGreetings({ name: 'World' });

    stream.on('data', (data) => {
      console.log('Stream data:', data);
    });

    stream.on('error', (err) => {
      console.error('Stream error:', err);
    });

    stream.on('end', () => {
      console.log('Stream completed');
    });
  } catch (error) {
    console.error('Stream error:', error);
  }

  // 清理资源
  grpcClientManager.clearAll();
}

main().catch(console.error);

🤝 贡献

欢迎提交 Issue 和 Pull Request 来完善这个模块。

📄 许可证

本项目采用 ISC 许可证 - 查看 LICENSE 文件了解详情。

Copyright (c) alexgogoing [email protected]

📞 支持

如有问题或建议，请提交 Issue 或联系维护者。

@micl/grpc-client - Proxy 代理的 gRPC 客户端管理器 🚀