# gin-scaffold

**Repository Path**: YCODEMAN/gin-scaffold

## Basic Information

- **Project Name**: gin-scaffold
- **Description**: 基于gin的脚手架
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-27
- **Last Updated**: 2026-01-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# TrustedLauncher

企业级 Golang Web 服务脚手架，基于 Gin + Slog + Viper + Cobra 构建。

## 技术栈

- **Web 框架**: Gin - 高性能 HTTP 框架
- **配置管理**: Viper - 支持多种配置源（CLI > Config File > Defaults）
- **命令行**: Cobra - 强大的 CLI 框架
- **日志系统**: Slog - Go 1.21+ 官方结构化日志
- **安全特性**: CORS, Custom Recovery, HTTPS, mTLS 支持

## 核心特性

✅ **双协议支持**: 同时或独立启动 HTTP/HTTPS  
✅ **mTLS 支持**: 双向认证，客户端证书验证  
✅ **JWT 鉴权**: 基于 Token 的无状态认证  
✅ **AOP 审计**: 请求日志与业务解耦  
✅ **优雅停机**: 双服务并发 Shutdown  
✅ **统一响应**: 标准化 JSON 响应格式  
✅ **生产就绪**: Docker 多阶段构建, Makefile 工程化  

## 项目结构

```
.
├── Makefile                # 工程管理
├── Dockerfile              # 多阶段构建
├── cmd/app                 # 命令行入口
│   ├── main.go
│   ├── root.go             # Viper 绑定
│   ├── start.go            # 启动逻辑（双协议）
│   └── version.go          # 版本信息
├── configs
│   └── config.yaml         # 配置模板
├── internal
│   ├── config              # 配置结构体定义
│   ├── handler             # HTTP 处理器
│   ├── middleware          # 中间件（审计、安全）
│   └── server              # 路由组装
└── pkg
    ├── logger              # Slog 封装
    └── response            # 统一响应
```

## 快速开始

### 🚀 一键演示

运行完整功能演示（推荐首次使用）:

```bash
./demo.sh
```

这会自动演示所有核心功能：编译、证书生成、服务启动、接口测试、优雅停机。

### 1. 安装依赖

```bash
make install-deps
```

### 2. 本地运行

```bash
# 使用默认配置
make run

# 使用自定义配置
go run ./cmd/app start --config ./configs/config.yaml

# 命令行覆盖端口
go run ./cmd/app start --http-port 9090 --https-port 9443
```

### 3. 编译

```bash
make build
./bin/trustedlauncher start
```

### 4. Docker 构建

```bash
make docker
docker run -p 8080:8080 -p 8443:8443 trustedlauncher:latest
```

## 配置说明

配置文件 `configs/config.yaml`:

```yaml
server:
  run_mode: debug          # debug 或 release
  http_port: 8080          # HTTP 端口（0 禁用）
  https_port: 8443         # HTTPS 端口（0 禁用）
  tls:
    cert_path: "./configs/certs/server.crt"
    key_path: "./configs/certs/server.key"
    enable_mtls: false     # 是否启用双向认证
    ca_cert_path: "./configs/certs/ca.crt"

log:
  level: info              # debug, info, warn, error
  format: json             # json 或 text

cors:
  allow_origins:
    - "*"                  # 允许的源（生产环境应配置具体域名）

jwt:
  jwt-private-key: "./configs/key/private-key.pem" # JWT RSA 私钥路径
  jwt-public-key: "./configs/key/public-key.pem" # JWT RSA 公钥路径
  expire_hours: 24                                     # Token 有效期（小时）
  issuer: "trustedlauncher"
  skip_auth_paths:                                     # 跳过鉴权的路径
    - "/health"
    - "/api/v1/auth/login"
```

### 配置优先级

CLI 参数 > 环境变量 (TL_ 前缀) > 配置文件 > 默认值

示例：
```bash
# 环境变量覆盖
export TL_SERVER_HTTP_PORT=9090
./bin/trustedlauncher start
```

## 测试场景

### 场景 A: 仅 HTTP

```yaml
server:
  http_port: 8080
  https_port: 0
```

测试:
```bash
curl http://localhost:8080/health
curl http://localhost:8080/api/v1/hello?name=Alice
```

### 场景 B: 仅 HTTPS（单向认证）

```yaml
server:
  http_port: 0
  https_port: 8443
  tls:
    cert_path: "./configs/certs/server.crt"
    key_path: "./configs/certs/server.key"
    enable_mtls: false
```

测试:
```bash
curl -k https://localhost:8443/health
```

### 场景 C: 双协议 + mTLS

```yaml
server:
  http_port: 8080
  https_port: 8443
  tls:
    enable_mtls: true
    ca_cert_path: "./configs/certs/ca.crt"
```

测试:
```bash
# HTTP 正常访问
curl http://localhost:8080/health

# HTTPS 无客户端证书（失败）
curl -k https://localhost:8443/health

# HTTPS 带客户端证书（成功）
curl -k --cert client.crt --key client.key https://localhost:8443/health
```

### 场景 D: Recovery 测试

访问 panic 接口，服务器不崩溃：
```bash
curl http://localhost:8080/api/v1/panic
# 返回: {"code":50000,"msg":"Internal Server Error"}
# 日志会记录详细堆栈信息
```

## API 接口

### 健康检查
- **GET** `/health` - K8s liveness 探针（无需鉴权）

### 认证接口
- **POST** `/api/v1/auth/login` - 用户登录，获取 JWT Token（无需鉴权）
- **GET** `/api/v1/auth/userinfo` - 获取当前用户信息（需要鉴权）

### 示例接口
- **GET** `/api/v1/hello?name=xxx` - Hello 示例（需要鉴权）
- **GET** `/api/v1/panic` - 测试 Recovery 中间件（需要鉴权）

### JWT 鉴权使用

1. 登录获取 Token:
```bash
curl -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin123"}'
```

2. 使用 Token 访问受保护接口:
```bash
curl -X GET http://localhost:8080/api/v1/hello \
  -H "Authorization: Bearer <your_token>"
```

详细文档请查看: [JWT 鉴权使用文档](docs/JWT_AUTH.md)

## 响应格式

统一 JSON 响应：

```json
{
  "code": 0,
  "msg": "success",
  "data": {...}
}
```

错误响应：
```json
{
  "code": 50000,
  "msg": "error message"
}
```

## 审计日志

使用 AOP 模式，所有请求自动记录：

```json
{
  "time": "2025-11-25T10:30:00Z",
  "level": "INFO",
  "msg": "audit_log",
  "latency": "2.5ms",
  "client_ip": "192.168.1.100",
  "user": "alice",
  "method": "GET",
  "uri": "/api/v1/hello",
  "status": 200,
  "message": "hello request processed"
}
```

## 生成测试证书

```bash
# 创建证书目录
mkdir -p certs && cd certs

# 1. 生成 CA
openssl genrsa -out ca.key 2048
openssl req -new -x509 -days 365 -key ca.key -out ca.crt \
  -subj "/C=CN/ST=Beijing/L=Beijing/O=TrustedLauncher/CN=CA"

# 2. 生成服务器证书
openssl genrsa -out server.key 2048
openssl req -new -key server.key -out server.csr \
  -subj "/C=CN/ST=Beijing/L=Beijing/O=TrustedLauncher/CN=localhost"
openssl x509 -req -in server.csr -CA ca.crt -CAkey ca.key \
  -CAcreateserial -out server.crt -days 365

# 3. 生成客户端证书（mTLS）
openssl genrsa -out client.key 2048
openssl req -new -key client.key -out client.csr \
  -subj "/C=CN/ST=Beijing/L=Beijing/O=Client/CN=client1"
openssl x509 -req -in client.csr -CA ca.crt -CAkey ca.key \
  -CAcreateserial -out client.crt -days 365
```

## Makefile 命令

```bash
make help          # 显示帮助信息
make run           # 本地运行
make build         # 编译二进制
make clean         # 清理编译产物
make docker        # 构建 Docker 镜像
make test          # 运行测试
make tidy          # 整理依赖
```

## 许可证

MIT License