# learning-go

**Repository Path**: angry/learning-go

## Basic Information

- **Project Name**: learning-go
- **Description**: go 语言学习项目
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-30
- **Last Updated**: 2025-12-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Go Multi-Auth Demo Project

这是一个使用Gin框架的多认证方式Web API项目示例，支持JWT、Basic和Key三种认证方式。

## 项目结构

```
go-demo/
├── go.mod              # Go模块文件
├── main.go             # 主程序入口
├── .env                # 环境变量配置文件
├── config/             # 配置管理
│   └── config.go       # 应用配置
├── handlers/           # HTTP处理器
│   ├── auth.go         # 认证相关接口
│   └── protected.go    # 受保护的接口
├── middleware/         # 中间件
│   ├── auth.go         # JWT认证中间件
│   ├── basic_auth.go   # Basic认证中间件
│   ├── key_auth.go     # Key认证中间件
│   └── factory.go      # 认证工厂模式
├── models/             # 数据模型
│   └── user.go         # 用户模型
└── utils/              # 工具函数
    └── jwt.go          # JWT工具函数
```

## 功能特性

- 🔐 **多种认证方式**: JWT、Basic、Key三种认证方式可选
- ⚙️ **配置驱动**: 通过环境变量灵活配置认证方式
- 👤 **用户管理**: 支持多种用户认证方式
- 🛡️ **受保护的API**: 所有认证方式都支持受保护的端点
- 🔄 **Token管理**: JWT认证支持Token刷新
- 📊 **认证状态**: 提供认证状态查询接口
- 💾 **灵活配置**: 支持自定义用户和密钥

## 快速开始

### 1. 安装依赖

```bash
go mod tidy
```

### 2. 配置环境变量

编辑 `.env` 文件，设置认证方式：

```env
PORT=8080
AUTH_TYPE=jwt

JWT_SECRET=your-secret-key-here
JWT_EXPIRE_HOURS=24

BASIC_USERS=admin:password123,user:user123

API_KEYS=key123:user1,key456:user2,admin_key:admin
```

### 3. 运行项目

```bash
go run main.go
```

服务器将在 `http://localhost:8080` 启动。

## 配置认证方式

### 环境变量说明

| 变量名 | 描述 | 默认值 | 适用认证方式 |
|--------|------|--------|-------------|
| `AUTH_TYPE` | 认证方式类型 | `jwt` | 所有 |
| `PORT` | 服务器端口 | `8080` | 所有 |
| `JWT_SECRET` | JWT签名密钥 | `your-secret-key-here` | JWT |
| `JWT_EXPIRE_HOURS` | JWT过期时间(小时) | `24` | JWT |
| `BASIC_USERS` | Basic认证用户列表 | `admin:password123,user:user123` | Basic |
| `API_KEYS` | API密钥列表 | `key123:user1,key456:user2` | Key |

### 认证方式类型

- `jwt`: JWT Token认证（默认）
- `basic`: Basic认证
- `key`: API Key认证

## API 接口

### 公共接口（无需认证）

#### 认证信息
- **GET** `/auth/info`
- **响应**:
  ```json
  {
    "auth_type": "jwt",
    "supported_types": ["jwt", "basic", "key"],
    "jwt_login_required": true
  }
  ```

#### 健康检查
- **GET** `/health`
- **响应**:
  ```json
  {
    "status": "OK",
    "message": "Server is running",
    "auth_type": "jwt",
    "supported": ["jwt", "basic", "key"]
  }
  ```

#### 用户登录（JWT模式）
- **POST** `/api/login`
- **请求体**:
  ```json
  {
    "username": "admin",
    "password": "password123"
  }
  ```
- **响应**:
  ```json
  {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "id": 1,
      "username": "admin"
    }
  }
  ```

### 受保护接口（需要认证）

#### 获取用户资料
- **GET** `/api/profile`
- **Headers**: 根据认证方式提供相应凭据

#### 获取受保护数据
- **GET** `/api/protected-data`
- **Headers**: 根据认证方式提供相应凭据

#### 获取用户信息
- **GET** `/api/user-info`
- **Headers**: 根据认证方式提供相应凭据

#### 认证状态（Basic/Key模式）
- **GET** `/api/auth/status`
- **Headers**: 根据认证方式提供相应凭据

#### 刷新Token（JWT模式）
- **POST** `/api/refresh-token`
- **Headers**: `Authorization: Bearer {token}`

## 使用示例

### 1. 检查当前认证方式

```bash
curl http://localhost:8080/auth/info
```

### 2. JWT认证模式

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

#### 使用Token访问接口
```bash
curl -X GET http://localhost:8080/api/profile \
  -H "Authorization: Bearer YOUR_JWT_TOKEN_HERE"
```

#### 刷新Token
```bash
curl -X POST http://localhost:8080/api/refresh-token \
  -H "Authorization: Bearer YOUR_JWT_TOKEN_HERE"
```

### 3. Basic认证模式

#### 登录并访问接口
```bash
# 方式1：使用curl的-u参数
curl -X GET http://localhost:8080/api/profile \
  -u admin:password123

# 方式2：手动设置Authorization header
curl -X GET http://localhost:8080/api/profile \
  -H "Authorization: Basic YWRtaW46cGFzc3dvcmQxMjM="
```

### 4. Key认证模式

#### 使用API Key访问接口
```bash
# 方式1：使用X-API-Key header
curl -X GET http://localhost:8080/api/profile \
  -H "X-API-Key: key123"

# 方式2：使用Authorization header
curl -X GET http://localhost:8080/api/profile \
  -H "Authorization: Key key123"

# 方式3：使用API-Key header
curl -X GET http://localhost:8080/api/profile \
  -H "API-Key: key123"
```

### 5. 完整流程示例

#### JWT模式测试
```bash
# 1. 登录获取token
TOKEN=$(curl -s -X POST http://localhost:8080/api/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"password123"}' | jq -r '.token')

# 2. 访问受保护接口
curl -X GET http://localhost:8080/api/profile \
  -H "Authorization: Bearer $TOKEN"

# 3. 获取用户信息
curl -X GET http://localhost:8080/api/user-info \
  -H "Authorization: Bearer $TOKEN"
```

#### Basic模式测试
```bash
# 直接访问受保护接口
curl -X GET http://localhost:8080/api/profile \
  -u admin:password123
```

#### Key模式测试
```bash
# 使用API Key访问
curl -X GET http://localhost:8080/api/profile \
  -H "X-API-Key: key123"
```

## 测试账号

### JWT认证模式
| 用户名 | 密码 | 权限 |
|--------|------|------|
| admin | password123 | 管理员 |
| user | user123 | 普通用户 |

### Basic认证模式
| 用户名 | 密码 | 权限 |
|--------|------|------|
| admin | password123 | 管理员 |
| user | user123 | 普通用户 |

### Key认证模式
| API Key | 用户名 | 权限 |
|---------|--------|------|
| key123 | user1 | 普通用户 |
| key456 | user2 | 普通用户 |
| admin_key | admin | 管理员 |

## 配置说明

### 环境变量

#### 全局配置
- `AUTH_TYPE`: 认证方式类型，可选值：`jwt`、`basic`、`key`
- `PORT`: 服务器端口，默认 `8080`

#### JWT认证配置
- `JWT_SECRET`: JWT签名密钥（生产环境请使用强密码）
- `JWT_EXPIRE_HOURS`: Token过期时间（小时），默认 24

#### Basic认证配置
- `BASIC_USERS`: 用户列表，格式：`username:password,username:password`

#### Key认证配置
- `API_KEYS`: API密钥列表，格式：`key:username,key:username`

### 认证方式说明

- **JWT认证**: 基于Token的无状态认证，支持Token刷新和过期管理
- **Basic认证**: 基于HTTP Basic Auth的简单认证方式
- **Key认证**: 基于API Key的简单认证方式，支持多种Header格式

## 技术栈

- **Web框架**: [Gin](https://github.com/gin-gonic/gin)
- **JWT库**: [golang-jwt/jwt/v5](https://github.com/golang-jwt/jwt)
- **Go版本**: 1.21+

## 注意事项

1. 生产环境中请使用强密码作为JWT_SECRET
2. Token过期时间根据业务需求调整
3. 可以扩展用户数据模型添加更多字段
4. 建议添加数据库支持进行用户管理

## 许可证

MIT License