Go-API 框架

语言版本: English | 中文

项目概述

go-api 是一个功能强大、高性能的 Go 语言框架，专为构建企业级 Web API 而设计。它提供了完整的解决方案，包括分层架构、依赖注入、全面的中间件支持和自动代码生成功能。

主要特性

🚀 高性能: 基于 Gin 框架，优化了日志和数据库连接
🏗️ 分层架构: 严格遵循 Model → Repository → Service → Controller 模式
🔧 依赖注入: 清晰的架构和适当的关注点分离
⚙️ 配置管理: 多环境支持，基于 JSON 的配置
📝 高级日志: 使用 Zap 的结构化日志，高性能
🗄️ 多数据库支持: MySQL、PostgreSQL、SQLite、SQL Server、ClickHouse (通过 xdb/GORM) 和 MongoDB (qmgo)
🔐 JWT 认证: 内置应用认证和 JWT token
🌐 国际化: 多语言支持（中文、英文）
📊 中间件系统: CORS、认证、请求日志和自定义中间件
⚡ 代码生成: 从 SQL 文件自动生成模型和仓库
🔄 任务调度: 内置作业调度系统
📨 消息队列: Kafka 生产者/消费者支持
🚨 监控: 异常恢复和通知集成
🐳 Docker 支持: 完整的 Docker 支持和优化镜像

快速开始

方法一：使用项目生成脚本

# 下载项目生成器
curl -O https://raw.githubusercontent.com/seakee/go-api/main/scripts/generate.sh
chmod +x generate.sh

# 生成新项目
./generate.sh my-api-project v1.0.0
cd my-api-project

# 安装依赖并运行
go mod tidy
make run

方法二：克隆并自定义

# 克隆仓库
git clone https://github.com/seakee/go-api.git
cd go-api

# 安装依赖
go mod download

# 复制和配置本地设置
cp bin/configs/local.json.default bin/configs/local.json
# 编辑 bin/configs/local.json 设置数据库配置

# 运行应用
make run

项目结构

go-api/
├── app/                             # 应用层
│   ├── config/                     # 配置管理
│   │   └── config.go              # 配置加载器和结构
│   ├── http/                       # HTTP层
│   │   ├── controller/             # HTTP控制器
│   │   │   ├── auth/               # 认证控制器
│   │   │   │   ├── app.go          # 应用CRUD操作
│   │   │   │   ├── handler.go      # 认证处理器接口
│   │   │   │   └── jwt.go          # JWT令牌操作
│   │   │   └── base.go             # 基础控制器
│   │   ├── middleware/             # HTTP中间件
│   │   │   ├── check_app_auth.go   # JWT认证
│   │   │   ├── cors.go             # CORS处理
│   │   │   ├── handler.go          # 中间件接口
│   │   │   ├── request_logger.go   # 请求日志
│   │   │   └── set_trace_id.go     # 跟踪ID注入
│   │   ├── router/                 # 路由定义
│   │   │   ├── external/           # 外部API路由
│   │   │   │   └── service/        # 外部服务路由
│   │   │   │       └── auth/       # 认证端点
│   │   │   ├── internal/           # 内部API路由
│   │   │   │   └── service/        # 内部服务路由
│   │   │   │       └── auth/       # 认证端点
│   │   │   └── handler.go          # 主路由器
│   │   └── context.go              # HTTP上下文包装器
│   ├── model/                      # 数据模型
│   │   └── auth/                   # 认证模型
│   │       ├── app.go              # 应用模型 (MySQL)
│   │       └── app_mgo.go          # 应用模型 (MongoDB)
│   ├── pkg/                        # 工具包
│   │   ├── e/                      # 错误代码
│   │   │   └── code.go             # 错误代码定义
│   │   ├── jwt/                    # JWT工具
│   │   │   └── jwt.go              # JWT生成/解析
│   │   ├── schedule/               # 任务调度
│   │   │   └── schedule.go         # 作业调度器
│   │   └── trace/                  # 分布式跟踪
│   │       └── trace.go            # 跟踪ID生成
│   ├── repository/                 # 数据访问层
│   │   └── auth/                   # 认证仓库
│   │       └── app.go              # 应用仓库
│   ├── service/                    # 业务逻辑层
│   │   └── auth/                   # 认证服务
│   │       └── app.go              # 应用服务
│   └── worker/                     # 后台工作者
│       └── handler.go              # 工作者处理器
├── bin/                            # 运行时资源
│   ├── configs/                    # 配置文件
│   │   ├── dev.json                # 开发环境配置
│   │   ├── local.json              # 本地配置
│   │   └── prod.json               # 生产环境配置
│   ├── data/                       # 数据文件
│   │   └── sql/                    # SQL脚本
│   │       └── auth_app.sql        # 应用表结构
│   └── lang/                       # 语言文件
│       ├── en-US.json              # 英文消息
│       └── zh-CN.json              # 中文消息
├── bootstrap/                      # 应用启动
│   ├── app.go                      # 主应用初始化
│   ├── database.go                 # 数据库设置
│   ├── http.go                     # HTTP服务器设置
│   ├── kafka.go                    # Kafka设置
│   └── schedule.go                 # 调度器设置
├── command/                        # CLI命令
│   └── codegen/                    # 代码生成器
│       ├── codegen/                # 生成器逻辑
│       ├── handler.go              # CLI处理器
│       └── README.md               # 生成器文档
├── scripts/                        # 实用脚本
│   └── generate.sh                 # 项目生成器
├── docs/                           # 项目文档
│   ├── Home.md                     # Wiki首页（英文）
│   ├── Home-zh.md                  # Wiki首页（中文）
│   ├── Architecture-Design.md      # 架构设计文档
│   ├── Development-Guide.md        # 开发指南
│   ├── API-Documentation.md        # 完整API参考
│   ├── Code-Generator-Guide.md     # 代码生成工具指南
│   └── Deployment-Guide.md         # 生产部署指南
├── Dockerfile                      # Docker配置
├── Makefile                        # 构建自动化
├── docker-compose.yml              # Docker Compose
├── go.mod                          # Go模块
├── go.sum                          # 依赖项
├── main.go                         # 应用入口点
└── CONTRIBUTING.md                 # 贡献指南

核心组件

1. 分层架构

框架遵循严格的4层架构：

模型层: 数据结构和数据库操作
仓库层: 数据访问抽象和接口
服务层: 业务逻辑实现
控制器层: HTTP请求处理和响应格式化

2. 配置管理

支持多环境的JSON配置：

{
  "system": {
    "name": "go-api",
    "run_mode": "debug",
    "http_port": ":8080",
    "jwt_secret": "你的密钥"
  },
  "databases": [
    {
      "enable": true,
      "db_type": "mysql",
      "db_name": "go-api",
      "db_host": "localhost",
      "db_port": 3306,
      "charset": "utf8mb4",
      "conn_max_lifetime": 3
    }
  ]
}

3. 中间件系统

内置常用功能的中间件：

认证: 基于JWT的应用认证
CORS: 跨域资源共享
日志: 结构化请求/响应日志
跟踪ID: 分布式跟踪支持
异常恢复: 自动异常恢复和通知

4. 认证系统

完整的JWT认证：

# 获取JWT令牌
curl -X POST http://localhost:8080/go-api/external/service/auth/token \
  -d "app_id=your_app_id&app_secret=your_app_secret"

# 在请求中使用令牌
curl -H "Authorization: your_jwt_token" \
  http://localhost:8080/go-api/external/service/auth/app

开发指南

添加新控制器

创建控制器结构：

// app/http/controller/user/handler.go
package user

import (
    "github.com/gin-gonic/gin"
    "github.com/seakee/go-api/app/http"
)

type Handler interface {
    Create() gin.HandlerFunc
    GetByID() gin.HandlerFunc
}

type handler struct {
    controller.BaseController
    service userService.UserService
}

func NewHandler(appCtx *http.Context) Handler {
    return &handler{
        BaseController: controller.BaseController{
            AppCtx: appCtx,
            Logger: appCtx.Logger,
            Redis:  appCtx.Redis["go-api"],
            I18n:   appCtx.I18n,
        },
        service: userService.NewUserService(appCtx.SqlDB["go-api"], appCtx.Redis["go-api"]),
    }
}

注册路由：

// app/http/router/external/service/user/user.go
func RegisterRoutes(api *gin.RouterGroup, ctx *http.Context) {
    userHandler := user.NewHandler(ctx)
    {
        api.POST("user", ctx.Middleware.CheckAppAuth(), userHandler.Create())
        api.GET("user/:id", userHandler.GetByID())
    }
}

添加中间件

// app/http/middleware/handler.go
type Middleware interface {
    CheckAppAuth() gin.HandlerFunc
    YourNewMiddleware() gin.HandlerFunc  // 添加这个
}

// app/http/middleware/your_middleware.go
func (m middleware) YourNewMiddleware() gin.HandlerFunc {
    return func(c *gin.Context) {
        // 中间件逻辑
        c.Next()
    }
}

代码生成

从SQL文件生成模型和仓库：

# 从SQL文件生成
go run ./command/codegen/handler.go -name user_table

# 生成所有SQL文件
go run ./command/codegen/handler.go

# 自定义路径
go run ./command/codegen/handler.go -sql custom/sql -model custom/model

API端点

外部API（公开）

方法	端点	描述	需要认证
POST	`/go-api/external/service/auth/token`	获取JWT令牌	否
POST	`/go-api/external/service/auth/app`	创建应用	是
GET	`/go-api/external/service/ping`	健康检查	否

内部API（私有）

方法	端点	描述	需要认证
POST	`/go-api/internal/service/auth/token`	获取JWT令牌	否
POST	`/go-api/internal/service/auth/app`	创建应用	是
GET	`/go-api/internal/service/ping`	健康检查	否

Docker部署

使用Docker Compose

# docker-compose.yml
version: '3.8'
services:
  go-api:
    build: .
    ports:
      - "8080:8080"
    volumes:
      - ./bin/configs:/bin/configs
      - ./bin/logs:/bin/logs
    environment:
      - RUN_ENV=prod
      - APP_NAME=go-api
    depends_on:
      - mysql
      - redis

  mysql:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: password
      MYSQL_DATABASE: go-api
    ports:
      - "3306:3306"

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"

构建和运行

# 构建Docker镜像
make docker-build

# 使用Docker Compose运行
docker-compose up -d

# 运行单个容器
make docker-run

构建命令

# 开发
make run          # 运行应用
make test         # 运行测试
make fmt          # 格式化代码
make all          # fmt + test + build

# 生产
make build        # 构建二进制文件
make docker-build # 构建Docker镜像
make docker-run   # 运行Docker容器

环境变量

变量	描述	默认值
`RUN_ENV`	运行环境	`local`
`APP_NAME`	应用名称	`go-api`
`CONFIG_DIR`	配置目录	`./bin/configs`

文档

完整的项目文档位于 docs/ 目录：

📚 GitHub Wiki - 完整的Wiki文档
Wiki首页 - 文档索引和快速导航
架构设计 - 系统架构和设计模式
开发指南 - 详细的开发工作流程
API文档 - 完整的API参考
代码生成器 - 代码生成工具使用指南
部署指南 - 生产环境部署
Makefile使用指南 - 构建自动化和开发工具
go-api.sh使用指南 - Shell脚本替代方案

贡献

我们欢迎贡献！请查看贡献指南了解：

代码标准和风格指南
拉取请求流程
问题报告
开发环境设置

许可证

本项目采用MIT许可证 - 查看 LICENSE 文件了解详情。

FilesExpand file tree

README-zh.md

Latest commit

History