# go-zero-iot

**Repository Path**: go_27/go-zero-iot

## Basic Information

- **Project Name**: go-zero-iot
- **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-12
- **Last Updated**: 2025-11-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# go-zero-iot

## 项目介绍

**go-zero-iot** 是一个基于 go-zero 框架开发的物联网(IoT)后端管理系统，提供用户认证和设备管理功能。该系统采用微服务架构设计，包含用户服务和管理员服务两个核心模块，支持设备信息的查询和管理，以及用户身份认证和权限控制。

### 系统特点

- **微服务架构**：采用 go-zero 框架实现的微服务，支持高并发和可扩展性
- **JWT认证**：基于 JWT 的用户身份验证机制
- **数据库操作**：使用 GORM 进行数据库交互，支持自动迁移
- **API文档化**：通过 goctl 工具自动生成 API 代码和文档
- **模块化设计**：清晰的代码结构和模块划分

## 技术栈

| 类别 | 技术 | 版本/说明 |
|------|------|-----------|
| 后端框架 | go-zero | 微服务框架 |
| ORM | GORM | Go语言ORM库 |
| 数据库 | MySQL | 5.7+ |
| 认证机制 | JWT | JSON Web Token |
| API工具 | goctl | go-zero官方代码生成工具

## 系统架构

### 微服务架构概述

本项目基于 go-zero 框架实现了完整的微服务架构，采用了服务拆分、独立部署、共享组件的设计理念，具有高可用性、可扩展性和易于维护的特点。

### 微服务组件详解

| 组件名称 | 主要职责 | 文件位置 | 核心功能 |
|---------|---------|----------|----------|
| **用户服务(user)** | 用户认证与会话管理 | `./user/` | 用户登录、身份验证、JWT令牌发放 |
| **管理员服务(admin)** | 设备管理和数据查询 | `./admin/` | 设备列表查询、数据统计分析 |
| **共享模型(models)** | 数据模型与数据库交互 | `./models/` | 数据库模型定义、连接管理、自动迁移 |
| **辅助工具(helper)** | 通用功能与工具函数 | `./helper/` | JWT生成/验证、MD5加密、HTTP请求处理 |
| **常量定义(define)** | 系统常量与配置 | `./define/` | 定义系统级常量、配置项、错误码 |

### 微服务架构优势

1. **服务解耦**：各服务独立开发、部署和扩展，降低了系统复杂度
2. **高可用性**：单个服务故障不影响整体系统运行，支持独立伸缩
3. **技术多样性**：各服务可根据需求选择最适合的技术栈（本项目统一使用Go语言）
4. **独立扩展**：根据业务需求独立扩展高负载服务，提高资源利用率
5. **简化维护**：服务边界清晰，问题定位和修复更加高效

### go-zero框架在微服务中的应用

go-zero 框架为微服务提供了完整的解决方案，本项目中主要应用：

1. **API网关**：自动生成RESTful API路由和处理器
2. **服务发现与注册**：支持多种服务注册中心集成
3. **负载均衡**：内置客户端负载均衡机制
4. **熔断器**：防止服务雪崩，提高系统稳定性
5. **配置中心**：统一管理服务配置，支持热更新
6. **分布式追踪**：支持与主流追踪系统集成

### 服务间通信

- **HTTP API**：外部系统通过RESTful API与服务交互
- **共享数据库**：服务间通过共享数据库进行数据交换（可根据需求升级为消息队列）
- **配置文件**：各服务通过独立的YAML配置文件管理自身配置

### 微服务部署架构

各服务可独立部署在不同服务器或容器中，支持横向扩展。典型的部署架构：

```
客户端 → API网关 → 用户服务/管理员服务 → 共享数据库
```

在高并发场景下，可以通过水平扩展服务实例数量来提高系统处理能力。

## 目录结构

```
go-zero-iot/
├── _goctl/           # goctl生成文档和示例
├── admin/            # 管理员服务目录
│   ├── admin.api     # 管理员API定义
│   ├── admin.go      # 管理员服务入口
│   ├── etc/          # 配置文件目录
│   └── internal/     # 内部实现目录
├── define/           # 常量定义
├── helper/           # 辅助工具函数
├── main.go           # 项目主入口
├── models/           # 数据模型目录
│   ├── device_basic.go   # 设备基础信息模型
│   ├── init.go           # 数据库初始化
│   ├── product_basic.go  # 产品基础信息模型
│   └── user_basic.go     # 用户基础信息模型
├── test/             # 测试文件目录
└── user/             # 用户服务目录
    ├── etc/          # 配置文件目录
    ├── internal/     # 内部实现目录
    ├── user.api      # 用户API定义
    └── user.go       # 用户服务入口
```

## 数据模型

### 用户表 (user_basic)

| 字段名 | 类型 | 描述 |
|--------|------|------|
| `id` | 主键 | 自增ID |
| `identity` | VARCHAR(50) | 用户唯一标识 |
| `name` | VARCHAR(50) | 用户名 |
| `password` | VARCHAR(50) | 用户密码(MD5加密) |
| `created_at` | DATETIME | 创建时间 |
| `updated_at` | DATETIME | 更新时间 |
| `deleted_at` | DATETIME | 删除时间 |

### 设备表 (device_basic)

| 字段名 | 类型 | 描述 |
|--------|------|------|
| `id` | 主键 | 自增ID |
| `identity` | VARCHAR(50) | 设备唯一标识 |
| `product_identity` | VARCHAR(50) | 产品唯一标识(外键) |
| `name` | VARCHAR(50) | 设备名称 |
| `key` | VARCHAR(50) | 设备密钥 |
| `secret` | VARCHAR(50) | 设备密文 |
| `created_at` | DATETIME | 创建时间 |
| `updated_at` | DATETIME | 更新时间 |
| `deleted_at` | DATETIME | 删除时间 |

### 产品表 (product_basic)

| 字段名 | 类型 | 描述 |
|--------|------|------|
| `id` | 主键 | 自增ID |
| `identity` | VARCHAR(50) | 产品唯一标识 |
| `name` | VARCHAR(50) | 产品名称 |
| `key` | VARCHAR(50) | 产品密钥 |
| `created_at` | DATETIME | 创建时间 |
| `updated_at` | DATETIME | 更新时间 |
| `deleted_at` | DATETIME | 删除时间 |

## 快速开始

### 1. 环境要求

- Go 1.16+ 开发环境
- MySQL 5.7+

### 2. 安装依赖包

```bash
# 安装GORM及MySQL驱动
go get -u gorm.io/gorm
go get -u gorm.io/driver/mysql

# 安装go-zero框架和goctl工具
go get -u github.com/zeromicro/go-zero
go get -u github.com/zeromicro/go-zero/tools/goctl@latest
```

### 3. 配置数据库

在 `models/init.go` 文件中配置数据库连接信息：

```go
// 修改数据库连接字符串
dsn := "root:root@tcp(127.0.0.1:3306)/zero_iot?charset=utf8mb4&parseTime=True&loc=Local"
```

确保MySQL数据库已创建：

```sql
CREATE DATABASE zero_iot CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```

### 4. 服务构建与运行

#### 用户服务

```bash
# 进入用户服务目录
cd user

# 生成服务代码（如果需要重新生成）
goctl api go -api user.api -dir . --style go_zero

# 运行用户服务
go run user.go -f etc/user-api.yaml
```

#### 管理员服务

```bash
# 进入管理员服务目录
cd admin

# 生成服务代码（如果需要重新生成）
goctl api go -api admin.api -dir . --style go_zero

# 运行管理员服务
go run admin.go -f etc/admin-api.yaml
```

## API接口说明

### 用户服务接口

| 接口名称 | 路径 | 方法 | 功能描述 |
|---------|------|------|----------|
| 用户登录 | `/user/login` | `POST` | 用户身份认证，返回JWT令牌 |

**用户登录请求参数**：

```json
{
  "username": "用户名",
  "password": "密码"
}
```

**用户登录响应数据**：

```json
{
  "token": "JWT认证令牌"
}
```

### 管理员服务接口

| 接口名称 | 路径 | 方法 | 功能描述 |
|---------|------|------|----------|
| 获取设备列表 | `/device/list` | `GET` | 查询设备分页列表，支持按名称筛选 |

**获取设备列表查询参数**：

| 参数名 | 类型 | 是否必选 | 描述 |
|--------|------|---------|------|
| `page` | int | 可选 | 页码 |
| `size` | int | 可选 | 每页数量 |
| `name` | string | 可选 | 设备名称模糊查询 |

**获取设备列表响应数据**：

```json
{
  "list": [
    {
      "identity": "设备唯一标识",
      "name": "设备名称",
      "key": "设备密钥",
      "secret": "设备密文",
      "product_name": "产品名称"
    }
  ],
  "count": 总设备数
}```

## 开发指南

### 添加新API

1. 在对应服务的 `.api` 文件中定义新的接口
2. 使用 goctl 工具生成代码：
   ```bash
   goctl api go -api 服务名.api -dir . --style go_zero
   ```
3. 在生成的 handler 中实现业务逻辑

### 添加新模型

1. 在 `models` 目录下创建新的模型文件
2. 在 `models/init.go` 中注册新模型到自动迁移列表

## 测试

系统提供了单元测试文件，位于 `test` 目录下：

```bash
# 运行用户服务测试
cd test
go test -v user_test.go

# 运行管理员服务测试
go test -v admin_test.go
```

## 注意事项

| 注意事项 | 详细说明 |
|---------|----------|
| **数据库配置** | 请确保在开发和生产环境中正确配置数据库连接信息 |
| **JWT密钥** | 在生产环境中，请修改 `helper/helper.go` 中的JWT签名密钥 |
| **密码安全** | 用户密码使用MD5加密存储，生产环境建议使用更安全的加密方式 |
| **服务端口** | 默认服务端口配置在各服务的 `etc` 目录下的YAML配置文件中 |
| **API文档** | 可以使用 goctl 生成Swagger文档：`goctl api doc -dir .` |

## 贡献指南

1. Fork 本仓库
2. 创建功能分支 (`git checkout -b feature/amazing-feature`)
3. 提交更改 (`git commit -m 'Add some amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 打开 Pull Request

## 许可证

[MIT](https://choosealicense.com/licenses/mit/)