feat(grpc-client): add support for multiple client pool and load balancing by huangdijia · Pull Request #7667 · hyperf/hyperf · GitHub

Summary

Add support for client_count option to create multiple gRPC clients
Implement random client selection from pool for load distribution
Refactor init() method to handle single and multiple client scenarios
Add property for storing multiple gRPC client instances
Improve code comments for better understanding

Description

This enhancement allows for better load balancing and connection pooling when dealing with high-load gRPC scenarios. By specifying a client_count option greater than 1, multiple gRPC client instances will be created, and requests will be randomly distributed across them.

Usage Example

// Single client (existing behavior)
$client = new BaseClient('localhost:50051', [
    'options' => [...]
]);

// Multiple clients with load balancing (new feature)
$client = new BaseClient('localhost:50051', [
    'client_count' => 3,  // Create 3 client instances
    'options' => [...]
]);

Test plan

Test single client creation (backward compatibility)
Test multiple client creation with client_count option
Verify random client selection works correctly
Test with invalid client_count values
Performance testing under load

Files changed

src/grpc-client/src/BaseClient.php - Add support for multiple client pool and load balancing

Breaking changes

None. This is a backward-compatible enhancement.

Checklist

Code follows the style guidelines of this project
I have performed a self-review of my own code
I have made corresponding changes to the documentation
My changes generate no new warnings
I have added tests that prove my fix is effective or that my feature works
New and existing unit tests pass locally with my changes
Any dependent changes have been merged and published

🔍 代码审查报告

✅ 优点

实现了多客户端池功能，支持负载均衡
代码结构清晰，完全符合 PSR-12 标准
很好地保持了向后兼容性
将配置验证移到构造函数是好的实践

⚠️ 必须修复的问题

1. 资源泄漏风险（严重）

public function __destruct()
{
    $this->grpcClient?->close(false);
    // 缺少对 grpcClients 数组中其他客户端的清理
}

建议修复为：

public function __destruct()
{
    $this->grpcClient?->close(false);
    if ($this->grpcClients !== null) {
        foreach ($this->grpcClients as $client) {
            $client?->close(false);
        }
    }
}

2. 并发安全问题

$this->grpcClient 在多线程环境下可能被并发修改
每次调用 _getGrpcClient() 都可能改变客户端引用，可能影响事务一致性

💡 建议改进

1. 改进负载均衡策略
当前使用随机选择可能导致负载分布不均，建议考虑轮询或其他更可控的策略。

2. 添加配置验证
建议限制 client_count 的最大值，避免创建过多客户端导致资源耗尽：

if ($count > 50) {
    throw new InvalidArgumentException('client_count should not exceed 50');
}

3. 线程安全优化
考虑缓存选中的客户端，避免每次调用都重新选择。

📝 其他建议

添加单元测试覆盖多客户端场景
在文档中说明多客户端的内存和连接影响
考虑添加客户端健康检查机制

总结

功能实现正确，代码质量良好。在修复资源清理问题后可以合并。

Pull request overview

This PR introduces client pooling and load balancing capabilities to the gRPC client implementation, allowing users to create multiple gRPC client instances and distribute requests across them for improved performance in high-load scenarios.

Key changes:

Add client_count option to enable creation of multiple client instances
Implement random client selection from pool for load distribution
Refactor initialization logic to handle single client, multiple clients, and custom client scenarios

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

…ncing - Add support for client_count option to create multiple gRPC clients - Implement random client selection from pool for load distribution - Refactor init() method to handle single and multiple client scenarios - Add property for storing multiple gRPC client instances - Improve code comments for better understanding This enhancement allows for better load balancing and connection pooling when dealing with high-load gRPC scenarios.

…or multiple clients

…ructor

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

… retrieval

…Connected method

… mechanism for client access

…o use unique lock keys

…thod

…s for client access

Copilot AI review requested due to automatic review settings December 13, 2025 01:33

Copilot started reviewing on behalf of huangdijia December 13, 2025 01:35 View session

huangdijia commented Dec 13, 2025

View reviewed changes

Copilot AI reviewed Dec 13, 2025

View reviewed changes

Comment thread src/grpc-client/src/BaseClient.php Outdated

Comment thread src/grpc-client/src/BaseClient.php Outdated

Comment thread src/grpc-client/src/BaseClient.php Outdated

Comment thread src/grpc-client/src/BaseClient.php Outdated

Comment thread src/grpc-client/src/BaseClient.php Outdated

huangdijia and others added 11 commits December 14, 2025 20:07

feat(grpc-client): enhance client count handling in constructor

cb1a1ad

feat(grpc-client): initialize clientCount to 1 and update condition f…

78ed78a

…or multiple clients

feat(grpc-client): close all gRPC clients in destructor

b38465b

fix(grpc-client): ensure all gRPC clients are closed properly in dest…

ad7b805

…ructor

更新 BaseClient.php

fa6a91b

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

refactor(grpc-client): simplify GrpcClient instantiation in constructor

fb280c9

Update BaseClient.php

8c5bf21

Update BaseClient.php

d4ea7f1

refactor(grpc-client): remove unused get() method and optimize client…

40681d7

… retrieval

feat(grpc-client): add support for client_count option and improve is…

d7b59bb

…Connected method

huangdijia force-pushed the feature/grpc-client-pool-support branch from 6ccbb4a to d7b59bb Compare December 14, 2025 12:07

huangdijia added 4 commits December 16, 2025 14:24

fix(grpc-client): ensure proper cleanup in destructor and add locking…

bfe44bb

… mechanism for client access

fix(grpc-client): update locking mechanism in _getGrpcClient method t…

0d07184

…o use unique lock keys

fix(grpc-client): improve initialization locking mechanism in init me…

bcd9107

…thod

fix(grpc-client): update locking mechanism to use unique object hashe…

0ab607c

…s for client access

limingxinleo approved these changes Dec 16, 2025

View reviewed changes

limingxinleo merged commit 53f2d38 into hyperf:master Dec 16, 2025
77 checks passed

huangdijia deleted the feature/grpc-client-pool-support branch December 16, 2025 08:26

feat(grpc-client): add support for multiple client pool and load balancing by huangdijia · Pull Request #7667 · hyperf/hyperf · GitHub

Uh oh!

Uh oh!

feat(grpc-client): add support for multiple client pool and load balancing - #7667

feat(grpc-client): add support for multiple client pool and load balancing#7667
limingxinleo merged 15 commits into
hyperf:masterfrom
huangdijia:feature/grpc-client-pool-support

huangdijia commented Dec 13, 2025

Uh oh!

huangdijia left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

feat(grpc-client): add support for multiple client pool and load balancing by huangdijia · Pull Request #7667 · hyperf/hyperf · GitHub

Uh oh!

Uh oh!

feat(grpc-client): add support for multiple client pool and load balancing - #7667

feat(grpc-client): add support for multiple client pool and load balancing#7667limingxinleo merged 15 commits intohyperf:masterhyperf/hyperf:masterfrom huangdijia:feature/grpc-client-pool-supporthuangdijia/hyperf:feature/grpc-client-pool-supportCopy head branch name to clipboard

Conversation

huangdijia commented Dec 13, 2025

Summary

Description

Usage Example

Test plan

Files changed

Breaking changes

Checklist

Uh oh!

huangdijia left a comment

Choose a reason for hiding this comment

🔍 代码审查报告

✅ 优点

⚠️ 必须修复的问题

💡 建议改进

📝 其他建议

总结

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

feat(grpc-client): add support for multiple client pool and load balancing#7667
limingxinleo merged 15 commits into
hyperf:masterfrom
huangdijia:feature/grpc-client-pool-support