{"id":36560733,"url":"https://github.com/seakee/go-api","last_synced_at":"2026-04-01T18:38:43.126Z","repository":{"id":194264856,"uuid":"690438385","full_name":"seakee/go-api","owner":"seakee","description":"Go-API is a simple, powerful, and high-performance Go framework for building web APIs.","archived":false,"fork":false,"pushed_at":"2026-03-19T12:39:28.000Z","size":581,"stargazers_count":6,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-03-20T03:34:06.762Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/seakee.png","metadata":{"files":{"readme":"README-zh.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-09-12T07:41:45.000Z","updated_at":"2026-03-19T12:33:18.000Z","dependencies_parsed_at":"2026-01-30T04:03:14.157Z","dependency_job_id":null,"html_url":"https://github.com/seakee/go-api","commit_stats":null,"previous_names":["seakee/go-api"],"tags_count":17,"template":false,"template_full_name":null,"purl":"pkg:github/seakee/go-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seakee%2Fgo-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seakee%2Fgo-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seakee%2Fgo-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seakee%2Fgo-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/seakee","download_url":"https://codeload.github.com/seakee/go-api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seakee%2Fgo-api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31290928,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T13:12:26.723Z","status":"ssl_error","status_checked_at":"2026-04-01T13:12:25.102Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-12T06:49:50.829Z","updated_at":"2026-04-01T18:38:43.107Z","avatar_url":"https://github.com/seakee.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Go-API 框架\n\n**语言版本**: [English](README.md) | [中文](README-zh.md)\n\n---\n\n### 项目概述\n\n`go-api` 是一个功能强大、高性能的 Go 语言框架，专为构建企业级 Web API 而设计。它提供了完整的解决方案，包括分层架构、依赖注入、全面的中间件支持和自动代码生成功能。\n\n### 主要特性\n\n- 🚀 **高性能**: 基于 Gin 框架，优化了日志和数据库连接\n- 🏗️ **分层架构**: 严格遵循 Model → Repository → Service → Controller 模式\n- 🔧 **依赖注入**: 清晰的架构和适当的关注点分离\n- ⚙️ **配置管理**: 多环境支持，基于 JSON 的配置\n- 📝 **高级日志**: 使用 Zap 的结构化日志，高性能\n- 🗄️ **多数据库支持**: MySQL、PostgreSQL、SQLite、SQL Server、ClickHouse (通过 xdb/GORM) 和 MongoDB (qmgo)\n- 🔐 **JWT 认证**: 内置应用认证和 JWT token\n- 🌐 **国际化**: 多语言支持（中文、英文）\n- 📊 **中间件系统**: CORS、认证、请求日志和自定义中间件\n- ⚡ **代码生成**: 从 SQL 文件自动生成模型和仓库\n- 🔄 **任务调度**: 内置作业调度系统\n- 📨 **消息队列**: Kafka 生产者/消费者支持\n- 🚨 **监控**: 异常恢复和通知集成\n- 🐳 **Docker 支持**: 完整的 Docker 支持和优化镜像\n\n### 快速开始\n\n#### 方法一：使用项目生成脚本\n\n```bash\n# 下载项目生成器\ncurl -O https://raw.githubusercontent.com/seakee/go-api/main/scripts/generate.sh\nchmod +x generate.sh\n\n# 生成新项目\n./generate.sh my-api-project v1.0.0\ncd my-api-project\n\n# 安装依赖并运行\ngo mod tidy\nmake run\n```\n\n#### 方法二：克隆并自定义\n\n```bash\n# 克隆仓库\ngit clone https://github.com/seakee/go-api.git\ncd go-api\n\n# 安装依赖\ngo mod download\n\n# 复制和配置本地设置\ncp bin/configs/local.json.default bin/configs/local.json\n# 编辑 bin/configs/local.json 设置数据库配置\n\n# 运行应用\nmake run\n```\n\n### 项目结构\n\n```\ngo-api/\n├── app/                             # 应用层\n│   ├── config/                     # 配置管理\n│   │   └── config.go              # 配置加载器和结构\n│   ├── http/                       # HTTP层\n│   │   ├── controller/             # HTTP控制器\n│   │   │   ├── auth/               # 认证控制器\n│   │   │   │   ├── app.go          # 应用CRUD操作\n│   │   │   │   ├── handler.go      # 认证处理器接口\n│   │   │   │   └── jwt.go          # JWT令牌操作\n│   │   │   └── base.go             # 基础控制器\n│   │   ├── middleware/             # HTTP中间件\n│   │   │   ├── check_app_auth.go   # JWT认证\n│   │   │   ├── cors.go             # CORS处理\n│   │   │   ├── handler.go          # 中间件接口\n│   │   │   ├── request_logger.go   # 请求日志\n│   │   │   └── set_trace_id.go     # 跟踪ID注入\n│   │   ├── router/                 # 路由定义\n│   │   │   ├── external/           # 外部API路由\n│   │   │   │   └── service/        # 外部服务路由\n│   │   │   │       └── auth/       # 认证端点\n│   │   │   ├── internal/           # 内部API路由\n│   │   │   │   └── service/        # 内部服务路由\n│   │   │   │       └── auth/       # 认证端点\n│   │   │   └── handler.go          # 主路由器\n│   │   └── context.go              # HTTP上下文包装器\n│   ├── model/                      # 数据模型\n│   │   └── auth/                   # 认证模型\n│   │       ├── app.go              # 应用模型 (MySQL)\n│   │       └── app_mgo.go          # 应用模型 (MongoDB)\n│   ├── pkg/                        # 工具包\n│   │   ├── e/                      # 错误代码\n│   │   │   └── code.go             # 错误代码定义\n│   │   ├── jwt/                    # JWT工具\n│   │   │   └── jwt.go              # JWT生成/解析\n│   │   ├── schedule/               # 任务调度\n│   │   │   └── schedule.go         # 作业调度器\n│   │   └── trace/                  # 分布式跟踪\n│   │       └── trace.go            # 跟踪ID生成\n│   ├── repository/                 # 数据访问层\n│   │   └── auth/                   # 认证仓库\n│   │       └── app.go              # 应用仓库\n│   ├── service/                    # 业务逻辑层\n│   │   └── auth/                   # 认证服务\n│   │       └── app.go              # 应用服务\n│   └── worker/                     # 后台工作者\n│       └── handler.go              # 工作者处理器\n├── bin/                            # 运行时资源\n│   ├── configs/                    # 配置文件\n│   │   ├── dev.json                # 开发环境配置\n│   │   ├── local.json              # 本地配置\n│   │   └── prod.json               # 生产环境配置\n│   ├── data/                       # 数据文件\n│   │   └── sql/                    # SQL脚本\n│   │       └── auth_app.sql        # 应用表结构\n│   └── lang/                       # 语言文件\n│       ├── en-US.json              # 英文消息\n│       └── zh-CN.json              # 中文消息\n├── bootstrap/                      # 应用启动\n│   ├── app.go                      # 主应用初始化\n│   ├── database.go                 # 数据库设置\n│   ├── http.go                     # HTTP服务器设置\n│   ├── kafka.go                    # Kafka设置\n│   └── schedule.go                 # 调度器设置\n├── command/                        # CLI命令\n│   └── codegen/                    # 代码生成器\n│       ├── codegen/                # 生成器逻辑\n│       ├── handler.go              # CLI处理器\n│       └── README.md               # 生成器文档\n├── scripts/                        # 实用脚本\n│   └── generate.sh                 # 项目生成器\n├── docs/                           # 项目文档\n│   ├── Home.md                     # Wiki首页（英文）\n│   ├── Home-zh.md                  # Wiki首页（中文）\n│   ├── Architecture-Design.md      # 架构设计文档\n│   ├── Development-Guide.md        # 开发指南\n│   ├── API-Documentation.md        # 完整API参考\n│   ├── Code-Generator-Guide.md     # 代码生成工具指南\n│   └── Deployment-Guide.md         # 生产部署指南\n├── Dockerfile                      # Docker配置\n├── Makefile                        # 构建自动化\n├── docker-compose.yml              # Docker Compose\n├── go.mod                          # Go模块\n├── go.sum                          # 依赖项\n├── main.go                         # 应用入口点\n└── CONTRIBUTING.md                 # 贡献指南\n```\n\n### 核心组件\n\n#### 1. 分层架构\n\n框架遵循严格的4层架构：\n\n- **模型层**: 数据结构和数据库操作\n- **仓库层**: 数据访问抽象和接口\n- **服务层**: 业务逻辑实现\n- **控制器层**: HTTP请求处理和响应格式化\n\n#### 2. 配置管理\n\n支持多环境的JSON配置：\n\n```json\n{\n  \"system\": {\n    \"name\": \"go-api\",\n    \"run_mode\": \"debug\",\n    \"http_port\": \":8080\",\n    \"jwt_secret\": \"你的密钥\"\n  },\n  \"databases\": [\n    {\n      \"enable\": true,\n      \"db_type\": \"mysql\",\n      \"db_name\": \"go-api\",\n      \"db_host\": \"localhost\",\n      \"db_port\": 3306,\n      \"charset\": \"utf8mb4\",\n      \"conn_max_lifetime\": 3\n    }\n  ]\n}\n```\n\n#### 3. 中间件系统\n\n内置常用功能的中间件：\n\n- **认证**: 基于JWT的应用认证\n- **CORS**: 跨域资源共享\n- **日志**: 结构化请求/响应日志\n- **跟踪ID**: 分布式跟踪支持\n- **异常恢复**: 自动异常恢复和通知\n\n#### 4. 认证系统\n\n完整的JWT认证：\n\n```bash\n# 获取JWT令牌\ncurl -X POST http://localhost:8080/go-api/external/service/auth/token \\\n  -d \"app_id=your_app_id\u0026app_secret=your_app_secret\"\n\n# 在请求中使用令牌\ncurl -H \"Authorization: your_jwt_token\" \\\n  http://localhost:8080/go-api/external/service/auth/app\n```\n\n### 开发指南\n\n#### 添加新控制器\n\n1. 创建控制器结构：\n\n```go\n// app/http/controller/user/handler.go\npackage user\n\nimport (\n    \"github.com/gin-gonic/gin\"\n    \"github.com/seakee/go-api/app/http\"\n)\n\ntype Handler interface {\n    Create() gin.HandlerFunc\n    GetByID() gin.HandlerFunc\n}\n\ntype handler struct {\n    controller.BaseController\n    service userService.UserService\n}\n\nfunc NewHandler(appCtx *http.Context) Handler {\n    return \u0026handler{\n        BaseController: controller.BaseController{\n            AppCtx: appCtx,\n            Logger: appCtx.Logger,\n            Redis:  appCtx.Redis[\"go-api\"],\n            I18n:   appCtx.I18n,\n        },\n        service: userService.NewUserService(appCtx.SqlDB[\"go-api\"], appCtx.Redis[\"go-api\"]),\n    }\n}\n```\n\n2. 注册路由：\n\n```go\n// app/http/router/external/service/user/user.go\nfunc RegisterRoutes(api *gin.RouterGroup, ctx *http.Context) {\n    userHandler := user.NewHandler(ctx)\n    {\n        api.POST(\"user\", ctx.Middleware.CheckAppAuth(), userHandler.Create())\n        api.GET(\"user/:id\", userHandler.GetByID())\n    }\n}\n```\n\n#### 添加中间件\n\n```go\n// app/http/middleware/handler.go\ntype Middleware interface {\n    CheckAppAuth() gin.HandlerFunc\n    YourNewMiddleware() gin.HandlerFunc  // 添加这个\n}\n\n// app/http/middleware/your_middleware.go\nfunc (m middleware) YourNewMiddleware() gin.HandlerFunc {\n    return func(c *gin.Context) {\n        // 中间件逻辑\n        c.Next()\n    }\n}\n```\n\n#### 代码生成\n\n从SQL文件生成模型和仓库：\n\n```bash\n# 从SQL文件生成\ngo run ./command/codegen/handler.go -name user_table\n\n# 生成所有SQL文件\ngo run ./command/codegen/handler.go\n\n# 自定义路径\ngo run ./command/codegen/handler.go -sql custom/sql -model custom/model\n```\n\n### API端点\n\n#### 外部API（公开）\n\n| 方法 | 端点 | 描述 | 需要认证 |\n|------|------|------|----------|\n| POST | `/go-api/external/service/auth/token` | 获取JWT令牌 | 否 |\n| POST | `/go-api/external/service/auth/app` | 创建应用 | 是 |\n| GET | `/go-api/external/service/ping` | 健康检查 | 否 |\n\n#### 内部API（私有）\n\n| 方法 | 端点 | 描述 | 需要认证 |\n|------|------|------|----------|\n| POST | `/go-api/internal/service/auth/token` | 获取JWT令牌 | 否 |\n| POST | `/go-api/internal/service/auth/app` | 创建应用 | 是 |\n| GET | `/go-api/internal/service/ping` | 健康检查 | 否 |\n\n### Docker部署\n\n#### 使用Docker Compose\n\n```yaml\n# docker-compose.yml\nversion: '3.8'\nservices:\n  go-api:\n    build: .\n    ports:\n      - \"8080:8080\"\n    volumes:\n      - ./bin/configs:/bin/configs\n      - ./bin/logs:/bin/logs\n    environment:\n      - RUN_ENV=prod\n      - APP_NAME=go-api\n    depends_on:\n      - mysql\n      - redis\n\n  mysql:\n    image: mysql:8.0\n    environment:\n      MYSQL_ROOT_PASSWORD: password\n      MYSQL_DATABASE: go-api\n    ports:\n      - \"3306:3306\"\n\n  redis:\n    image: redis:7-alpine\n    ports:\n      - \"6379:6379\"\n```\n\n#### 构建和运行\n\n```bash\n# 构建Docker镜像\nmake docker-build\n\n# 使用Docker Compose运行\ndocker-compose up -d\n\n# 运行单个容器\nmake docker-run\n```\n\n### 构建命令\n\n```bash\n# 开发\nmake run          # 运行应用\nmake test         # 运行测试\nmake fmt          # 格式化代码\nmake all          # fmt + test + build\n\n# 生产\nmake build        # 构建二进制文件\nmake docker-build # 构建Docker镜像\nmake docker-run   # 运行Docker容器\n```\n\n### 环境变量\n\n| 变量 | 描述 | 默认值 |\n|------|------|--------|\n| `RUN_ENV` | 运行环境 | `local` |\n| `APP_NAME` | 应用名称 | `go-api` |\n| `CONFIG_DIR` | 配置目录 | `./bin/configs` |\n\n### 文档\n\n完整的项目文档位于 `docs/` 目录：\n\n- **[📚 GitHub Wiki](https://github.com/seakee/go-api/wiki)** - 完整的Wiki文档\n- **[Wiki首页](docs/Home.md)** - 文档索引和快速导航\n- **[架构设计](docs/Architecture-Design.md)** - 系统架构和设计模式\n- **[开发指南](docs/Development-Guide.md)** - 详细的开发工作流程\n- **[API文档](docs/API-Documentation.md)** - 完整的API参考\n- **[代码生成器](docs/Code-Generator-Guide.md)** - 代码生成工具使用指南\n- **[部署指南](docs/Deployment-Guide.md)** - 生产环境部署\n- **[Makefile使用指南](docs/Makefile-Usage.md)** - 构建自动化和开发工具\n- **[go-api.sh使用指南](docs/go-api.sh-Usage.md)** - Shell脚本替代方案\n\n### 贡献\n\n我们欢迎贡献！请查看 [贡献指南](CONTRIBUTING.md) 了解：\n\n- 代码标准和风格指南\n- 拉取请求流程\n- 问题报告\n- 开发环境设置\n\n### 许可证\n\n本项目采用MIT许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fseakee%2Fgo-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fseakee%2Fgo-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fseakee%2Fgo-api/lists"}