# Hyperf之Grpc微服务框架V3.0

**Repository Path**: trident-framework/hyperf-micro-grpc-v3.0

## Basic Information

- **Project Name**: Hyperf之Grpc微服务框架V3.0
- **Description**: Hyperf grpc微服务框架V3.0
- **Primary Language**: PHP
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2024-10-21
- **Last Updated**: 2025-09-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Hyperf Micro gRPC 项目文档

## 简介

本项目是基于 [Hyperf](https://github.com/hyperf/hyperf) 框架构建的微服务架构下的 gRPC 服务项目。它包含多个服务模块，例如用户服务（user-service）、网关服务（gateway-api）等，适用于构建高性能的分布式系统。

该项目使用 gRPC 进行服务间通信，并结合 Protobuf 定义服务接口和数据结构，提供高效、可靠的服务调用能力。

## 环境要求

- PHP >= 8.0
- Swoole PHP 扩展 >= 4.5（推荐使用，需在 `php.ini` 中设置 `swoole.use_shortname = Off`）
- OpenSSL PHP 扩展（如需使用 HTTPS）
- PDO PHP 扩展（如需使用 MySQL 客户端）
- Redis PHP 扩展（如需使用 Redis 客户端）
- Protobuf PHP 扩展（如需使用 gRPC 服务或客户端）
- Docker（可选，用于快速部署）

## 安装与部署

### 使用 Composer 创建项目

```bash
$ composer create-project hyperf/hyperf-skeleton path/to/install
```

### 启动服务

进入项目目录并启动 Hyperf 服务：

```bash
$ cd path/to/install
$ php bin/hyperf.php start
```

默认情况下，服务会运行在 `9501` 端口，并绑定所有网络接口。你可以通过访问 `http://localhost:9501/` 来查看默认首页。

### 使用 Docker 部署

我们提供了 Dockerfile 和 docker-compose 配置文件，便于快速部署开发、测试和生产环境。

1. 构建镜像：

```bash
$ docker build -t hyperf-micro-grpc .
```

2. 启动容器：

```bash
$ docker run -d -p 9501:9501 hyperf-micro-grpc
```

或使用 `docker-compose`：

```bash
$ docker-compose up -d
```

## 项目结构说明

本项目主要分为以下几个模块：

- **gateway-api**：网关服务，提供对外的 RESTful API 接口，同时集成 gRPC 客户端调用内部服务。
- **user-service**：用户服务，提供用户管理、地址管理、购物车等基础功能，基于 gRPC 提供服务接口。

### 主要目录结构

- `app/Controller`：API 控制器，处理 HTTP 请求。
- `app/Grpc`：gRPC 服务接口定义和客户端调用逻辑。
- `app/Model`：数据库模型，用于数据持久化。
- `app/Logic`：业务逻辑层，封装核心业务逻辑。
- `config/autoload`：配置文件目录，包含数据库、gRPC、缓存等配置。
- `proto`：Protobuf 接口定义文件（`.proto`），用于生成 gRPC 接口代码。
- `public`：静态资源目录。
- `Dockerfile`：Docker 构建文件。
- `docker-compose.yaml`：Docker Compose 配置文件，用于多容器部署。

## 服务说明

### 网关服务（gateway-api）

网关服务作为系统的入口，负责接收 HTTP 请求，并通过 gRPC 调用内部服务模块。它集成了以下功能：

- 用户认证（JWT）
- 限流（Rate Limit）
- 文件上传（支持本地、MinIO、OSS）
- 消息队列（RabbitMQ）
- 搜索服务（Elasticsearch）
- 分布式事务（DTM）

### 用户服务（user-service）

用户服务提供用户管理、地址管理、购物车等基础功能，通过 gRPC 提供服务接口，供其他服务调用。

- 用户注册、登录、信息管理
- 用户地址管理（增删改查）
- 购物车管理（增删改查、批量操作）

## gRPC 接口定义

gRPC 接口定义在 `proto` 目录下的 `.proto` 文件中，包括：

- `user.proto`：用户服务接口定义
- `userAddress.proto`：用户地址服务接口定义
- `userCart.proto`：用户购物车服务接口定义
- `params.proto`：通用参数定义
- `result.proto`：通用返回结果定义

## 开发与调试

### 依赖管理

使用 Composer 管理项目依赖：

```bash
$ composer install
```

### 配置文件

- `.env.dev` / `.env.prod` / `.env.test`：不同环境的配置文件
- `config/autoload`：Hyperf 自动加载的配置文件，如数据库、gRPC、缓存等配置

### 日志与调试

- 日志输出：`app/Exception/Handler/AppExceptionHandler.php` 负责全局异常处理和日志记录。
- 单元测试：`test/` 目录下包含 PHPUnit 测试用例。

## 服务启动与运行

### 启动服务

```bash
$ php bin/hyperf.php start
```

### 停止服务

```bash
$ php bin/hyperf.php stop
```

### 重启服务

```bash
$ php bin/hyperf.php reload
```

## 服务接口文档

所有 gRPC 接口定义在 `proto` 目录中，可通过 `protoc` 工具生成客户端和服务端代码。

## 贡献与维护

欢迎贡献代码和提交 Issue。请遵循项目代码规范，并提交 Pull Request 到主仓库。

## 许可证

本项目采用 [MIT License](https://opensource.org/licenses/MIT)，详情请查看 `LICENSE` 文件。