# WattGoAPI

**Repository Path**: leady-study/watt-go-api

## Basic Information

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

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-12-11
- **Last Updated**: 2026-01-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Watt Go API

基于 Go 语言和 Gin 框架构建的企业级后端 API 框架，提供了完整模块化功能支持，适用于快速搭建高性能、可扩展的后端应用服务。

## 🌟 特性

- **高性能架构**：基于 Go 1.24.1 和 Gin 框架，提供卓越的并发性能和响应速度
- **模块化设计**：清晰的模块划分，便于功能扩展和维护
- **完善的认证系统**：基于 JWT 的用户认证，支持令牌过期控制和单点登录
- **数据库支持**：基于 GORM 的 ORM 操作，支持 MySQL 数据库和自动化迁移
- **缓存集成**：内置 Redis 支持，提供高效的缓存解决方案
- **并发任务管理**：支持 goroutine 的注册、执行和管理，提升系统并发处理能力
- **云存储集成**：支持阿里云 OSS 对象存储，提供文件上传、下载和管理功能
- **短信服务**：集成阿里云短信服务，支持验证码和通知短信发送
- **API 中间件支持**：提供 JWT 认证、CORS、请求验证、语言国际化等中间件
- **完善的日志系统**：结构化日志记录，支持多级别日志输出
- **错误处理机制**：统一的错误处理接口，支持自定义错误处理器
- **验证码支持**：内置图形验证码生成和验证功能
- **微信集成**：预留微信公众号接口，便于扩展微信生态功能

## 📋 系统要求

- Go 1.24.1 或更高版本
- MySQL 5.7+ 或 8.0+
- Redis 6.0+（可选，用于缓存）

## 🚀 快速开始

### 作为包安装使用

确保你已经安装了 Go 环境（推荐 1.24.1+），然后执行以下命令安装：

```bash
go get gitee.com/leady-study/watt-go-api
```

在项目中导入并使用：

```go
package main

import (
	"ResidentService/other"
	"ResidentService/router"

	wattgoapi "gitee.com/leady-study/watt-go-api"
)

func main() {
	// 创建 API 实例
	api := wattgoapi.CreateApi()
	
	// 初始化你的路由
	router.Init()
	
	// 初始化其他服务
	other.NewMiniWechat()
	
	// 启动服务器
	api.StartServer()
}
```

### 自定义路由设置

如果你想自定义路由，可以按照以下方式：

```go
package main

import (
	"github.com/gin-gonic/gin"
	wattgoapi "gitee.com/leady-study/watt-go-api"
	"gitee.com/leady-study/watt-go-api/watt_config"
	"gitee.com/leady-study/watt-go-api/watt_routers"
	"gitee.com/leady-study/watt-go-api/watt_response"
)

func main() {
	// 创建 API 实例
	api := wattgoapi.CreateApi()
	
	// 创建 Gin 路由器
	r := gin.Default()
	
	// 添加你的自定义路由
	apiGroup := r.Group(watt_config.GetConfig().Api.Prefix)
	{
		apiGroup.GET("/custom", func(c *gin.Context) {
			watt_response.Success(c, "This is a custom route")
		})
	}
	
	// 设置默认路由
	watt_routers.SetupRoutes(r)
	
	// 使用自定义路由启动服务器
	if err := r.Run(":8080"); err != nil {
		panic(err)
	}
}
```

### 配置文件位置

默认情况下，watt-go-api 会在项目根目录下查找 `config.yaml` 文件。如果配置文件位于其他位置，你可以通过环境变量指定：

```bash
export CONFIG_PATH=/path/to/your/config.yaml
```

或者在代码中设置：

```go
package main

import (
	"os"
	wattgoapi "gitee.com/leady-study/watt-go-api"
	"gitee.com/leady-study/watt-go-api/watt_config"
)

func main() {
	// 设置配置文件路径
	os.Setenv("CONFIG_PATH", "/path/to/your/config.yaml")
	
	// 创建 API 实例
	api := wattgoapi.CreateApi()
	
	// 启动服务器
	api.StartServer()
}
```

### 源码安装

如果你想获取完整源码并进行修改，可以使用以下方式：

```bash
git clone https://gitee.com/leady-study/watt-go-api
cd watt-go-api
go mod tidy
```

### 配置

1. 复制并修改配置文件 `config.yaml`：
```yaml
api:
  prefix: "/api"

server:
  host: "0.0.0.0"
  port: "8080"
  mode: "debug"
  domain: "localhost"
  ssl_enabled: false

database:
  host: "localhost"
  port: "3306"
  user: "root"
  password: "your_password"
  dbname: "watt_api"
  charset: "utf8mb4"

jwt:
  secret: "your_jwt_secret_key"
  expire_time: 168  # 单位：小时
  single_sign_on: false
```

2. 根据需要配置 Redis、阿里云服务（OSS、短信）等选项。

### 启动服务

```bash
go run api.go
```

服务启动后，默认监听 `http://localhost:8080`，API 路径为 `http://localhost:8080/api`

## 📁 目录结构

- `api.go`：应用程序入口文件
- `config.yaml`：主配置文件
- `watt_config/`：配置加载与管理模块
- `watt_database/`：数据库连接、迁移与模型同步相关功能
- `watt_enums/`：项目枚举定义
- `watt_helper/`：通用辅助函数，如 JWT 生成、日志、端口检查等
- `watt_jobs/`：并发任务调度与管理模块
- `watt_middleware/`：Gin 框架中间件，如 JWT、CORS、请求验证等
- `watt_models/`：数据库模型定义与操作
- `watt_request/`：请求结构体与校验
- `watt_response/`：响应封装与格式化
- `watt_routers/`：API 路由注册

## 📖 主要功能模块

### 1. 认证与授权
- JWT Token 认证机制
- 支持自定义 Token 过期时间
- 可选的单点登录功能

### 2. 数据库操作
- 基于 GORM 的 ORM 操作
- 支持数据库自动迁移
- 事务处理支持

### 3. 文件存储
- 阿里云 OSS 对象存储集成
- 文件上传、下载与管理
- 支持多种文件格式处理

### 4. 短信服务
- 阿里云短信服务集成
- 验证码发送与验证
- 支持模板短信发送

### 5. 并发任务管理
- Goroutine 池管理
- 任务注册与执行
- 错误处理与恢复

### 6. 中间件
- CORS 跨域处理
- 请求参数验证
- 多语言支持
- 访问日志记录

## 🔧 依赖包

本项目使用了以下主要依赖包：

- `github.com/gin-gonic/gin` - HTTP Web 框架
- `gorm.io/gorm` - Go ORM 库
- `gorm.io/driver/mysql` - GORM MySQL 驱动
- `github.com/go-sql-driver/mysql` - MySQL 驱动
- `github.com/golang-jwt/jwt/v5` - JWT 认证库
- `github.com/spf13/viper` - 配置管理库
- `github.com/aliyun/alibaba-cloud-sdk-go` - 阿里云 SDK
- `github.com/aliyun/aliyun-oss-go-sdk` - 阿里云 OSS SDK
- `github.com/go-playground/validator/v10` - 数据验证库
- `github.com/gofrs/uuid/v5` - UUID 生成库

## 📝 API 示例

### 认证接口
```bash
# 用户登录
POST /api/login
Content-Type: application/json
{
  "username": "admin",
  "password": "password"
}

# 获取用户信息
GET /api/user/info
Authorization: Bearer {jwt_token}
```

### 文件上传接口
```bash
# 上传文件
POST /api/file/upload
Authorization: Bearer {jwt_token}
Content-Type: multipart/form-data
```

## 📚 代码示例

### 创建新的 API 接口
```go
// 在 watt_routers 中注册路由
func SetupRoutes(r *gin.Engine) {
    api := r.Group(config.ApiPrefix)
    {
        // 新的 API 接口
        api.GET("/example", exampleHandler)
    }
}

// 处理函数
func exampleHandler(c *gin.Context) {
    // 业务逻辑处理
    watt_response.Success(c, "Hello World")
}
```

### 使用数据库模型
```go
// 定义模型
type Example struct {
    watt_models.BaseModel
    Name string `gorm:"size:100;not null" json:"name"`
}

// 数据库操作
func CreateExample(name string) error {
    example := Example{Name: name}
    return watt_database.GetDB().Create(&example).Error
}
```

## 🐛 故障排除

1. **端口占用问题**：检查 `config.yaml` 中的端口配置是否被其他程序占用
2. **数据库连接失败**：确保数据库服务正常运行，检查连接参数是否正确
3. **JWT 认证失败**：检查密钥配置是否正确，Token 是否过期
4. **文件上传失败**：检查阿里云 OSS 配置是否正确

## 🤝 贡献

欢迎提交 PR 和 Issue。贡献前请确保遵循项目编码规范，并通过测试。

## 📄 许可证

本项目采用 MIT License。详情请查看 `LICENSE` 文件。

## 🔗 相关链接

- [Gin 框架文档](https://gin-gonic.com/docs/)
- [GORM 文档](https://gorm.io/docs/)
- [Go 官方文档](https://golang.org/doc/)