# gin-im

**Repository Path**: go_27/gin-im

## Basic Information

- **Project Name**: gin-im
- **Description**: No description available
- **Primary Language**: Go
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-08
- **Last Updated**: 2025-11-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# gin-im

## 项目简介
基于 Gin 框架和 MongoDB 数据库开发的即时通讯系统，提供实时消息传输、用户管理和房间聊天等功能。

## 功能特性
- ✅ 用户注册与登录
- ✅ 发送邮件验证码
- ✅ 好友管理（添加、删除）
- ✅ 实时消息通信（基于 WebSocket）
- ✅ 聊天室管理
- ✅ 消息历史记录查询（支持分页）
- ✅ 用户身份认证（基于 JWT）
- ✅ 支持多用户在线聊天
- ✅ 用户个人信息查询

## 技术栈

| 类别 | 技术 | 描述 | 官方网站 |
|------|------|------|----------|
| 后端框架 | Gin Web Framework | 轻量级高性能的HTTP Web框架，提供路由、中间件等功能，适合构建RESTful API | [https://gin-gonic.com/](https://gin-gonic.com/) |
| 数据库 | MongoDB | NoSQL文档数据库，灵活存储半结构化数据，适合存储消息和用户信息 | [https://www.mongodb.com/](https://www.mongodb.com/) |
| 缓存 | Redis | 高性能键值存储，用于缓存验证码和临时数据 | [https://redis.io/](https://redis.io/) |
| 实时通信 | Gorilla WebSocket | Go语言的WebSocket实现，支持双向实时通信 | [https://github.com/gorilla/websocket](https://github.com/gorilla/websocket) |
| 身份认证 | JWT (JSON Web Token) | 无状态的身份认证机制，便于分布式系统使用 | [https://jwt.io/](https://jwt.io/) |
| 邮件服务 | jordan-wright/email | Go语言的电子邮件发送库，支持HTML内容和TLS加密 | [https://github.com/jordan-wright/email](https://github.com/jordan-wright/email) |
| 开发语言 | Go | 编译型语言，具有高性能、并发处理能力强的特点 | [https://golang.org/](https://golang.org/) |

## 核心依赖包

| 包名 | 版本 | 用途 | 文档地址 |
|------|------|------|----------|
| gin-gonic/gin | v1.9.x | 处理HTTP请求、路由分发和中间件管理 | [https://gin-gonic.com/docs/](https://gin-gonic.com/docs/) |
| gorilla/websocket | v1.5.x | 实现客户端与服务器之间的实时双向通信 | [https://pkg.go.dev/github.com/gorilla/websocket](https://pkg.go.dev/github.com/gorilla/websocket) |
| go.mongodb.org/mongo-driver | v1.12.x | 连接MongoDB数据库，执行CRUD操作 | [https://pkg.go.dev/go.mongodb.org/mongo-driver](https://pkg.go.dev/go.mongodb.org/mongo-driver) |
| go-redis/redis/v8 | v8.11.x | 连接Redis缓存服务器，存储验证码等临时数据 | [https://pkg.go.dev/github.com/go-redis/redis/v8](https://pkg.go.dev/github.com/go-redis/redis/v8) |
| dgrijalva/jwt-go | v3.2.x | 生成和验证JWT令牌，实现身份认证 | [https://pkg.go.dev/github.com/dgrijalva/jwt-go](https://pkg.go.dev/github.com/dgrijalva/jwt-go) |
| jordan-wright/email | v4.0.x | 电子邮件发送功能，支持HTML内容和附件 | [https://pkg.go.dev/github.com/jordan-wright/email](https://pkg.go.dev/github.com/jordan-wright/email) |
| satori/go.uuid | v1.2.x | 生成全局唯一标识符(UUID) | [https://pkg.go.dev/github.com/satori/go.uuid](https://pkg.go.dev/github.com/satori/go.uuid) |

## 软件架构
系统采用前后端分离架构：
- **后端**：Go + Gin 提供 RESTful API 和 WebSocket 服务
- **数据库**：MongoDB 存储用户信息、消息记录和房间数据
- **通信层**：WebSocket 实现实时消息推送
- **认证层**：JWT 实现无状态身份认证

## 数据模型设计
系统采用MongoDB文档数据库，主要包含以下核心数据集合：
- **用户集合 (user_basic)**：存储用户基本信息，包括账号、密码（MD5加密）、昵称、邮箱等
- **消息集合 (message_basic)**：存储聊天消息，包含发送者、接收者、内容、发送时间等字段
- **房间集合 (room_basic)**：存储聊天室信息，包括房间名称、创建者、创建时间等
- **用户房间关联集合 (user_room)**：管理用户与房间的多对多关联关系

数据模型设计遵循NoSQL最佳实践，每个集合都包含标准的_id、created_at和updated_at字段，确保数据完整性和可追溯性。

详细数据模型定义请参考 [models/model.md](models/model.md) 文件。

## 安装教程

### 1. 安装依赖包
```bash
go get -u github.com/gin-gonic/gin
go get github.com/gorilla/websocket
go get go.mongodb.org/mongo-driver
go get github.com/dgrijalva/jwt-go
go get github.com/jordan-wright/email
go get github.com/go-redis/redis/v8
go get github.com/satori/go.uuid
```

### 2. 启动 MongoDB 服务
```bash
docker run -d --name some-mongo \
-e MONGO_INITDB_ROOT_USERNAME=admin \
-e MONGO_INITDB_ROOT_PASSWORD=admin \
-p 27017:27017 \
mongo:latest
```

### 3. 启动 Redis 服务
```bash
docker run -d --name some-redis \
-p 6379:6379 \
redis:latest

### 4. 克隆项目
```bash
git clone https://gitee.com/your-username/gin-im.git
cd gin-im
```

### 4. 编译运行
```bash
go build
gin-im  # 运行编译后的二进制文件
```

## 使用说明
1. 服务启动后，默认监听 8080 端口
2. 使用浏览器或客户端连接 WebSocket 服务：`ws://localhost:8080/ws`
3. 通过 RESTful API 进行用户注册、登录等操作

## 项目结构
```
gin-im/
├── helper/           # 工具函数（如JWT、加密等）
├── models/           # 数据模型定义
├── router/           # 路由配置
├── service/          # 业务逻辑层
├── test/             # 测试文件
├── main.go           # 程序入口
├── go.mod            # Go模块依赖
└── go.sum            # 依赖校验
```

## API 接口

### 用户认证与管理
- `POST /login` - 用户登录
  - **参数**：账号(account)、密码(password)
  - **返回**：JWT令牌和用户基本信息
  
- `POST /send-code` - 发送注册验证码
  - **参数**：邮箱(email)
  - **返回**：操作结果状态
  
- `POST /register` - 用户注册
  - **参数**：账号(account)、密码(password)、邮箱(email)、验证码(code)
  - **返回**：注册结果和用户基本信息
  
- `GET /u/user/detail` - 获取当前用户详情
  - **参数**：JWT令牌(Authorization头)
  - **返回**：用户详细信息
  
- `GET /u/user/query` - 查询指定用户信息
  - **参数**：JWT令牌(Authorization头)、用户标识(identity)
  - **返回**：用户信息
  
- `POST /u/user/add` - 添加好友
  - **参数**：JWT令牌(Authorization头)、好友用户标识(identity)
  - **返回**：添加结果
  
- `POST /u/user/delete` - 删除好友
  - **参数**：JWT令牌(Authorization头)、好友用户标识(identity)
  - **返回**：删除结果
  
### 聊天相关
- `GET /u/chat/list` - 获取聊天记录列表
  - **参数**：JWT令牌(Authorization头)、房间标识(room_identity)、页码(page_index)、每页数量(page_size)
  - **返回**：分页的聊天记录数据
  - **说明**：仅返回用户有权限访问的房间消息

### WebSocket
- `GET ws://localhost:8080/u/websocket/message` - WebSocket连接入口
  - **参数**：JWT令牌(Authorization头或query参数)
  - **功能**：建立实时通信连接，支持消息收发和广播
  - **消息格式**：WebSocket消息采用JSON格式，测试示例：
  ```json
  {
    "room_identity": "room_identity",
    "message": "message - 2"
  }
  ```
  - **说明**：
    - `room_identity`：目标聊天室的标识
    - `message`：发送的消息内容
    - 消息会自动保存到数据库并发送给房间内所有在线用户

### 测试用令牌
以下令牌可用于API测试：
```json
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZGVudGl0eSI6IjY5MGYyY2JmZTcwNzAwMDBiNTAwMjRhNCIsImVtYWlsIjoi6YKu566xIn0.NYepgBwBYaF1ak1u-hf-tUWOGj56enB0658YJKFeeJM
```

```json
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZGVudGl0eSI6IjBiYzkyZWZiLTM5YzktNDFhZS1hY2JlLWEzYjZhY2U3ZjM2MyIsImVtYWlsIjoiZ2V0Y2hhcnpwQHFxLmNvbSJ9.teABGFbxEpVhfvTDXfM1AjXIaiU7eqBFOJHybeTGY2g
```

### 身份认证说明
- 除登录接口外，所有API接口和WebSocket连接都需要JWT令牌验证
- JWT令牌应在请求头中以`Bearer {token}`格式提供
- 令牌有效期可在系统配置中设置

## 贡献指南
1. Fork 本仓库
2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
3. 提交代码 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request