From 5cf3d38e3db4f7c4ac94f6b10d2581aabb5f7e13 Mon Sep 17 00:00:00 2001
From: gitee-bot <no-reply@git.oschina.net>
Date: Tue, 30 Sep 2025 05:19:55 +0000
Subject: [PATCH] Add README.md

---
 README.en.md | 160 +++++++++++++++++++++++++++++++++++++++++++++++++++
 README.md    | 160 +++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 320 insertions(+)
 create mode 100644 README.en.md
 create mode 100644 README.md

diff --git a/README.en.md b/README.en.md
new file mode 100644
index 0000000..a24abc6
--- /dev/null
+++ b/README.en.md
@@ -0,0 +1,160 @@
+# Hyperf Micro gRPC Project Documentation
+
+## Introduction
+
+This project is a gRPC service project built using the [Hyperf](https://github.com/hyperf/hyperf) framework within a microservices architecture. It includes multiple service modules, such as the user service (`user-service`) and gateway service (`gateway-api`), making it suitable for building high-performance distributed systems.
+
+The project uses gRPC for inter-service communication and combines Protobuf to define service interfaces and data structures, providing efficient and reliable service invocation capabilities.
+
+## System Requirements
+
+- PHP >= 8.0
+- Swoole PHP Extension >= 4.5 (recommended; set `swoole.use_shortname = Off` in `php.ini`)
+- OpenSSL PHP Extension (required for HTTPS support)
+- PDO PHP Extension (required for MySQL client support)
+- Redis PHP Extension (required for Redis client support)
+- Protobuf PHP Extension (required for gRPC service or client usage)
+- Docker (optional, for quick deployment)
+
+## Installation and Deployment
+
+### Creating the Project with Composer
+
+```bash
+$ composer create-project hyperf/hyperf-skeleton path/to/install
+```
+
+### Starting the Service
+
+Navigate to the project directory and start the Hyperf service:
+
+```bash
+$ cd path/to/install
+$ php bin/hyperf.php start
+```
+
+By default, the service runs on port `9501` and binds to all network interfaces. You can access the default homepage by visiting `http://localhost:9501/`.
+
+### Deploying with Docker
+
+We provide a Dockerfile and docker-compose configuration files for quick deployment in development, testing, and production environments.
+
+1. Build the Docker image:
+
+```bash
+$ docker build -t hyperf-micro-grpc .
+```
+
+2. Start the container:
+
+```bash
+$ docker run -d -p 9501:9501 hyperf-micro-grpc
+```
+
+Or use `docker-compose`:
+
+```bash
+$ docker-compose up -d
+```
+
+## Project Structure Overview
+
+The project is primarily divided into the following modules:
+
+- **gateway-api**: Gateway service that provides external RESTful API interfaces and integrates gRPC clients to call internal services.
+- **user-service**: User service that provides fundamental functionalities such as user management, address management, and shopping cart operations, offering service interfaces via gRPC.
+
+### Main Directory Structure
+
+- `app/Controller`: API controllers for handling HTTP requests.
+- `app/Grpc`: gRPC service interface definitions and client invocation logic.
+- `app/Model`: Database models for data persistence.
+- `app/Logic`: Business logic layer for encapsulating core business logic.
+- `config/autoload`: Configuration files directory, including configurations for databases, gRPC, caching, etc.
+- `proto`: Protobuf interface definition files (`.proto`) used to generate gRPC interface code.
+- `public`: Static resource directory.
+- `Dockerfile`: Docker build file.
+- `docker-compose.yaml`: Docker Compose configuration file for multi-container deployments.
+
+## Service Overview
+
+### Gateway Service (`gateway-api`)
+
+The gateway service acts as the entry point of the system, responsible for receiving HTTP requests and invoking internal service modules via gRPC. It integrates the following features:
+
+- User authentication (JWT)
+- Rate limiting
+- File upload (supports local storage, MinIO, and OSS)
+- Message queue (RabbitMQ)
+- Search service (Elasticsearch)
+- Distributed transactions (DTM)
+
+### User Service (`user-service`)
+
+The user service provides fundamental functionalities such as user management, address management, and shopping cart operations. It exposes service interfaces via gRPC for invocation by other services.
+
+- User registration, login, and profile management
+- User address management (CRUD operations)
+- Shopping cart management (CRUD operations, batch processing)
+
+## gRPC Interface Definitions
+
+gRPC interface definitions are located in `.proto` files within the `proto` directory, including:
+
+- `user.proto`: User service interface definition
+- `userAddress.proto`: User address service interface definition
+- `userCart.proto`: User shopping cart service interface definition
+- `params.proto`: Common parameter definitions
+- `result.proto`: Common result response definitions
+
+## Development and Debugging
+
+### Dependency Management
+
+Use Composer to manage project dependencies:
+
+```bash
+$ composer install
+```
+
+### Configuration Files
+
+- `.env.dev` / `.env.prod` / `.env.test`: Environment-specific configuration files
+- `config/autoload`: Hyperf auto-loaded configuration files, such as database, gRPC, and cache configurations
+
+### Logging and Debugging
+
+- **Log Output**: `app/Exception/Handler/AppExceptionHandler.php` handles global exception handling and logging.
+- **Unit Testing**: PHPUnit test cases are located in the `test/` directory.
+
+## Service Startup and Execution
+
+### Starting the Service
+
+```bash
+$ php bin/hyperf.php start
+```
+
+### Stopping the Service
+
+```bash
+$ php bin/hyperf.php stop
+```
+
+### Restarting the Service
+
+```bash
+$ php bin/hyperf.php reload
+```
+
+## Service Interface Documentation
+
+All gRPC interface definitions are located in the `proto` directory. Client and server code can be generated using the `protoc` tool.
+
+## Contributing and Maintenance
+
+Contributions of code and issue reports are welcome. Please follow the project's coding standards and submit Pull Requests to the main repository.
+
+## License
+
+This project uses the [MIT License](https://opensource.org/licenses/MIT). For details, please refer to the `LICENSE` file.
\ No newline at end of file
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..4d6a04c
--- /dev/null
+++ b/README.md
@@ -0,0 +1,160 @@
+# 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` 文件。
\ No newline at end of file
-- 
Gitee