# gateway

**Repository Path**: dlsingous/gateway

## Basic Information

- **Project Name**: gateway
- **Description**: 网关-go语言
- **Primary Language**: Go
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-13
- **Last Updated**: 2026-06-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Gin Gateway - 微服务网关

<div align="center">

一个基于 Gin 框架的高性能微服务网关，支持 HTTP/HTTPS、TCP、gRPC、WebSocket 等多种协议代理。

[![Go Version](https://img.shields.io/badge/Go-1.25-blue.svg)](https://golang.org)
[![Gin Version](https://img.shields.io/badge/Gin-1.11-green.svg)](https://github.com/gin-gonic/gin)
[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

[功能特性](#功能特性) • [快速开始](#快速开始) • [部署方式](#部署方式) • [文档](#文档) • [贡献](#贡献)

</div>

---

## 📖 项目简介

Gin Gateway 是一个功能完整的微服务网关解决方案，包含管理后台（Dashboard）和代理服务（Server）两个核心组件。项目采用现代化的 Go 开发实践，提供了丰富的流量管理、安全控制和服务治理功能。

**前端项目地址**: [gateway-vue3](https://gitee.com/dlsingous/gateway-vue3)

## ✨ 功能特性

### 协议支持
- ✅ **HTTP/HTTPS** - 支持域名和路径两种接入方式
- ✅ **TCP** - 支持 Thrift、Redis 等 TCP 协议代理
- ✅ **gRPC** - 完整的 gRPC 代理支持
- ✅ **WebSocket** - WebSocket 协议代理

### 核心功能
- 🚀 **流量统计** - 实时统计服务流量和 QPS
- 🛡️ **限流熔断** - 支持限流、熔断、降级策略
- 🔐 **安全控制** - IP 黑白名单、JWT 认证
- ⚖️ **负载均衡** - 支持轮询、加权轮询、一致性哈希等算法
- 🔍 **服务发现** - 集成 Etcd 实现服务注册与发现
- 📊 **监控告警** - 完善的日志和监控体系
- 🎯 **读写分离** - MySQL 读写分离支持

### 架构特点
- 🏗️ **依赖注入** - 使用 ServiceContext 统一管理依赖
- 📝 **结构化日志** - 集成 Zap 高性能日志库
- ⚡ **高性能** - 优化的代理性能和资源管理
- 🔧 **配置热更新** - 支持配置动态加载
- 🧪 **易于测试** - 接口抽象，便于单元测试

## 🎉 最新改进 (2026-03)

本项目最近进行了全面的架构优化和代码重构：

- ✅ **依赖注入改造** - 引入 ServiceContext，移除全局变量
- ✅ **接口抽象和解耦** - 定义核心接口，降低模块耦合
- ✅ **错误处理统一化** - 统一错误码体系，支持错误链追踪
- ✅ **日志结构化** - 集成 Zap，支持结构化日志输出
- ✅ **配置热更新** - 配置变更自动通知相关组件
- ✅ **HTTP 代理优化** - 清理冗余代码，提升性能
- ✅ **完善文档** - 新增使用指南和优化总结

详细信息请查看 [优化总结文档](docs/optimization_summary.md)
## 🛠️ 技术栈

### 后端技术
- **框架**: Gin (Web 框架)、gRPC (RPC 框架)
- **数据库**: MySQL (主数据库)、Redis (缓存)
- **服务发现**: Etcd
- **日志**: Zap (高性能日志库)
- **ORM**: GORM (数据库 ORM)
- **熔断器**: Hystrix
- **认证**: JWT
- **文档**: Swagger (API 文档)

### 部署技术
- **容器化**: Docker、Docker Compose
- **编排**: Kubernetes (K8s)
- **操作系统**: Linux

## 🚀 快速开始

### 环境要求

- Go 1.25+
- MySQL 5.7+
- Redis 5.0+
- Etcd 3.5+ (可选，用于服务发现)

### 1. 克隆项目

```bash
git clone https://github.com/yourusername/gin-gateway.git
cd gin-gateway
```

### 2. 初始化数据库

```bash
# 创建数据库
mysql -h 127.0.0.1 -u root -p -e "CREATE DATABASE gin-gateway DEFAULT CHARACTER SET utf8 COLLATE utf8_general_ci;"

# 导入数据
mysql -h 127.0.0.1 -u root -p gin-gateway < gin-gateway.sql --default-character-set=utf8
```

### 3. 配置文件

修改配置文件 `./etc/dev/conf.yaml`，配置数据库和 Redis 连接信息：

```yaml
base:
  mysql:
    host: 127.0.0.1
    port: 3306
    user: root
    password: your_password
    database: gin-gateway

  redis:
    host: 127.0.0.1
    port: 6379
    password: ""
```

### 4. 安装依赖

```bash
go mod download
```

### 5. 启动服务

#### 启动管理后台

```bash
go run cmd/dashboard/main.go -config=./etc/dev/conf.yaml
```

访问地址: `http://localhost:8880`

#### 启动代理服务

```bash
go run cmd/server/main.go -config=./etc/dev/conf.yaml
```

代理服务端口：
- HTTP: `:8080`
- HTTPS: `:4433`
- TCP: `:8081`
- gRPC: `:8082`

### 6. 访问前端

配合前端项目使用，详见 [gin-gateway-vue3](https://gitee.com/Vallenbo/gin-gateway-vue3)

## 📦 部署方式

### Linux 部署

#### 1. 创建数据库并导入数据

```bash
mysql -h 127.0.0.1 -u root -p -e "CREATE DATABASE gin-gateway DEFAULT CHARACTER SET utf8 COLLATE utf8_general_ci;"
mysql -h 127.0.0.1 -u root -p gin-gateway < gin-gateway.sql --default-character-set=utf8
```

#### 2. 调整配置文件

修改 `./etc/dev/conf.yaml` 为你的环境配置。

#### 3. 运行服务

**运行管理面板**（配合前端项目使用）：

```bash
go run cmd/dashboard/main.go -config=./etc/dev/conf.yaml
```

**运行代理服务**：

```bash
go run cmd/server/main.go -config=./etc/dev/conf.yaml
```

### Docker Compose 部署

#### 1. 交叉编译环境设置

```bash
go env -w GOOS=linux
go env -w CGO_ENABLED=0
```

#### 2. 编译主程序

```bash
# 编译主程序
go build -o ./bin/server

# 构建 dashboard 镜像
docker build -f dockerfile-dashboard -t server-dashboard .

# 构建 server 镜像
docker build -f dockerfile-server -t server-server .
```

#### 3. 编译后端服务示例

```bash
# HTTP 后端服务
go build -o ./bin/httpbackend1 ./k8s/example/httpbackend1/main.go
go build -o ./bin/httpbackend2 ./k8s/example/httpbackend2/main.go
docker build -f dockerfile-httpbackend1 -t server-httpbackend1 .
docker build -f dockerfile-httpbackend2 -t server-httpbackend2 .

# HTTPS 后端服务
go build -o ./bin/httpsbackend ./k8s/example/httpsbackend/main.go
docker build -f dockerfile-httpsbackend -t server-httpsbackend .

# gRPC 后端服务
go build -o ./bin/grpcbackend ./example/grpcserver/main.go
docker build -f dockerfile-grpcbackend -t server-grpcbackend .

# TCP 后端服务
go build -o ./bin/tcpbackend ./example/tcpserver/main.go
docker build -f dockerfile-tcpbackend -t server-tcpbackend .

# WebSocket 后端服务
go build -o ./bin/websocketbackend ./example/websocket/main.go
docker build -f dockerfile-websocketbackend -t server-websocketbackend .
```

#### 4. 启动服务

```bash
docker compose up
```

### Kubernetes 部署

详细的 K8s 部署说明请参考 [K8s 部署文档](k8s/readme.md)

```bash
# 启动服务
kubectl apply -f k8s_dashboard.yaml
kubectl apply -f k8s_server.yaml

# 查看所有部署
kubectl get all
```

## 🧪 测试

### 访问服务

#### 管理后台
```bash
http://localhost:8880
```

#### HTTP 服务测试
```bash
# 路径接入方式
curl http://localhost:8080/test_strip_uri

# 域名接入方式（需配置 hosts）
curl http://test.com:8080/
```

#### HTTPS 服务测试
```bash
# 需配置 hosts: server.https.gateway.local -> 127.0.0.1
curl https://server.https.gateway.local:4433/test_https_server
```

#### WebSocket 测试
```bash
# 访问 WebSocket 测试页面
http://localhost:8080/websocket
```

#### gRPC 服务测试
```bash
# 1. 获取访问 token
curl --location --request POST 'http://localhost:8080/oauth/tokens' \
  --header 'Authorization: Basic YXBwX2lkX2I6OGQ3YjExZWM5YmUwZTU5YTM2YjUyZjMyMzY2YzA5Y2I=' \
  --form 'grant_type="client_credentials"' \
  --form 'scope="read_write"'

# 2. 运行 gRPC 客户端
go run example/grpcclient/main.go
```

#### TCP 服务测试
```bash
# 修改代码中的服务端地址后运行
go run example/tcpclient/main.go
```

### 性能测试

#### HTTP 压测
```bash
# 使用 wrk 进行压测
docker pull williamyeh/wrk
docker run --rm williamyeh/wrk -t24 -c1000 -d30s --latency "http://localhost:8080/test_strip_uri"
```

#### TCP 代理压测
```bash
# 运行压测代码
cd test/thrift_server_client/concurrency_bench
go run main.go
# 预期结果: QPS ~82950
```

#### gRPC 代理压测
```bash
# 运行压测代码
cd test/grpc_bench
go run main.go
# 预期结果: QPS ~2826
```


## 📁 项目结构

```
gin-gateway/
├── cmd/                    # 应用程序入口
│   ├── dashboard/         # 管理后台服务
│   └── server/            # 代理服务
├── internal/              # 内部代码
│   ├── config/           # 配置管理
│   ├── handler/          # HTTP 处理器
│   ├── logic/            # 业务逻辑
│   ├── middleware/       # 中间件
│   ├── model/            # 数据模型
│   ├── proxy/            # 代理实现
│   ├── svc/              # 服务上下文
│   └── types/            # 类型定义
├── pkg/                   # 公共包
│   ├── dal/              # 数据访问层
│   ├── errors/           # 错误定义
│   ├── log/              # 日志工具
│   ├── utils/            # 工具函数
│   └── zaplog/           # Zap 日志封装
├── docs/                  # 文档
├── example/               # 示例代码
├── etc/                   # 配置文件
│   ├── dev/              # 开发环境配置
│   └── pro/              # 生产环境配置
├── deploy/                # 部署相关
├── test/                  # 测试代码
└── gin-gateway.sql        # 数据库初始化脚本
```

## 📚 文档

- [使用指南](docs/usage_guide.md) - 详细的使用说明和最佳实践
- [优化总结](docs/optimization_summary.md) - 项目优化历史和改进说明
- [Zap 日志设置](docs/zap_logger_setup.md) - 日志系统配置指南
- [Zap 快速开始](docs/zap_quickstart.md) - 日志使用快速入门
- [API 文档](docs/swagger.json) - Swagger API 文档
- [K8s 部署](k8s/readme.md) - Kubernetes 部署详细说明

## 🤝 贡献

欢迎贡献代码！请遵循以下步骤：

1. Fork 本项目
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 提交 Pull Request

### 代码规范

- 遵循 Go 官方代码规范
- 运行 `gofmt -w .` 格式化代码
- 添加必要的注释和文档
- 编写单元测试

## 📝 许可证

本项目采用 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件

## 🙏 致谢

感谢所有为本项目做出贡献的开发者！

## 📮 联系方式

如有问题或建议，请提交 [Issue](https://github.com/yourusername/gin-gateway/issues)

---

<div align="center">
Made with ❤️ by Gin Gateway Team
</div>