{"id":29182647,"url":"https://github.com/hedeqiang/go-skeleton","last_synced_at":"2025-10-14T22:17:28.065Z","repository":{"id":301339484,"uuid":"1008896504","full_name":"hedeqiang/go-skeleton","owner":"hedeqiang","description":"A simple Golang web service skeleton","archived":false,"fork":false,"pushed_at":"2025-08-03T10:35:11.000Z","size":61697,"stargazers_count":4,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-03T12:16:01.930Z","etag":null,"topics":["golang","skeleton","template","web"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hedeqiang.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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}},"created_at":"2025-06-26T09:01:34.000Z","updated_at":"2025-08-03T10:35:14.000Z","dependencies_parsed_at":"2025-06-26T11:32:46.894Z","dependency_job_id":"3972cb5e-8cf2-48a0-9c1c-8c1bc39dd565","html_url":"https://github.com/hedeqiang/go-skeleton","commit_stats":null,"previous_names":["hedeqiang/skeleton"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/hedeqiang/go-skeleton","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hedeqiang%2Fgo-skeleton","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hedeqiang%2Fgo-skeleton/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hedeqiang%2Fgo-skeleton/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hedeqiang%2Fgo-skeleton/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hedeqiang","download_url":"https://codeload.github.com/hedeqiang/go-skeleton/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hedeqiang%2Fgo-skeleton/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279021761,"owners_count":26087053,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-14T02:00:06.444Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["golang","skeleton","template","web"],"created_at":"2025-07-01T20:07:03.064Z","updated_at":"2025-10-14T22:17:28.050Z","avatar_url":"https://github.com/hedeqiang.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Skeleton - Go Web 应用模板\n\n这是一个功能完整的 Go Web 应用模板，集成了现代 Go 开发的最佳实践和常用中间件。项目采用分层架构设计，具有良好的可扩展性和可维护性。\n\n\u003e **注意：** 开发中，非稳定版本\n\n## 🚀 项目特性\n\n### 核心技术栈\n- **Web 框架**: Gin\n- **数据库**: GORM (支持 MySQL、PostgreSQL)\n- **缓存**: Redis\n- **消息队列**: RabbitMQ\n- **配置管理**: Viper\n- **日志**: Zap\n- **参数验证**: Validator\n- **依赖注入**: Wire\n\n### 架构特点\n- **依赖注入**: 完全的 DI 模式，使用 Wire 进行代码生成\n- **分层架构**: Handler -\u003e Service -\u003e Repository 清晰分层\n- **中间件栈**: Recovery、CORS、RequestID、Logger 等完整支持\n- **优雅启停**: 完整的生命周期管理\n- **统一响应**: 标准化的 API 返回格式\n- **配置化管理**: 多环境配置支持\n- **消息队列**: 生产者和消费者分离架构\n\n## 📁 项目结构\n\n```\nskeleton/\n├── cmd/                          # 应用程序入口\n│   ├── api/                     # API 服务\n│   └── consumer/                # 消息消费者服务\n├── configs/                     # 配置文件\n│   └── config.dev.yaml         # 开发环境配置\n├── internal/                    # 内部代码\n│   ├── app/                    # 应用容器\n│   ├── config/                 # 配置管理\n│   ├── handler/v1/             # HTTP 处理器\n│   ├── messaging/              # 消息处理\n│   │   ├── consumer/           # 消息消费者\n│   │   └── processors/         # 消息处理器\n│   ├── middleware/             # 中间件\n│   ├── model/                  # 数据模型\n│   ├── repository/             # 数据访问层\n│   ├── router/                 # 路由配置\n│   ├── service/                # 业务逻辑层\n│   └── wire/                   # 依赖注入\n├── pkg/                        # 公共包\n│   ├── database/              # 数据库连接\n│   ├── logger/                # 日志工具\n│   ├── mq/                    # 消息队列\n│   ├── redis/                 # Redis 客户端\n│   └── response/              # 响应工具\n├── docs/                       # 文档\n├── scripts/                    # 脚本文件\n│   ├── migrate/               # 数据库迁移\n│   └── seed/                  # 种子数据\n├── Makefile                    # 构建工具\n└── README.md                   # 项目文档\n```\n\n## 🛠️ 快速开始\n\n### 1. 环境要求\n- Go 1.21+\n- MySQL 8.0+ 或 PostgreSQL 13+\n- Redis 6.0+\n- RabbitMQ 3.8+\n\n### 2. 安装依赖\n```bash\ngit clone https://github.com/hedeqiang/skeleton.git\ncd skeleton\ngo mod tidy\n```\n\n### 3. 配置文件\n项目使用 `configs/config.dev.yaml` 配置文件，根据需要修改：\n\n```yaml\n# 数据库配置\ndatabases:\n  default:\n    type: \"mysql\"\n    dsn: \"user:password@tcp(localhost:3306)/dbname?charset=utf8mb4\u0026parseTime=True\u0026loc=Local\"\n\n# Redis 配置\nredis:\n  addr: \"localhost:6379\"\n  password: \"\"\n  db: 0\n\n# RabbitMQ 配置\nrabbitmq:\n  url: \"amqp://guest:guest@127.0.0.1:5672/\"\n```\n\n### 4. 数据库迁移\n```bash\nmake db-migrate\n```\n\n### 5. 启动服务\n```bash\n# 启动 API 服务\nmake run-api\n\n# 启动消费者服务 (可选)\nmake run-consumer\n```\n\n### 6. 访问服务\n- API 服务: http://localhost:8080\n- 健康检查: http://localhost:8080/ping\n\n## 📊 核心功能模块\n\n### 🌐 Web API\n- RESTful API 设计\n- 统一的错误处理和响应格式\n- 参数验证和数据绑定\n- 中间件支持 (CORS、日志、恢复等)\n\n### 🗄️ 数据库\n- GORM ORM 支持\n- 多数据源配置\n- 自动迁移和种子数据\n- 连接池管理\n\n### 📨 消息队列\n- RabbitMQ 集成\n- 生产者和消费者分离\n- 配置化队列管理\n- 消息处理器模式\n\n\u003e 详细使用说明请参考: [消息队列文档](docs/MESSAGE_QUEUE.md)\n\n### 🔧 Redis 缓存\n- Redis 客户端封装\n- 连接管理\n- 支持各种数据类型操作\n\n### 📝 日志系统\n- 结构化日志记录 (Zap)\n- 请求追踪 (Request ID)\n- 多级别日志输出\n- JSON 格式支持\n\n### ⚙️ 配置管理\n- 多环境配置支持\n- 环境变量覆盖\n- 实时配置重载\n- 类型安全的配置绑定\n\n## 🔌 API 接口\n\n### 用户管理\n- `POST /api/v1/users` - 创建用户\n- `GET /api/v1/users/:id` - 获取用户信息\n- `PUT /api/v1/users/:id` - 更新用户信息\n- `DELETE /api/v1/users/:id` - 删除用户\n- `GET /api/v1/users` - 获取用户列表\n\n### 消息队列\n- `POST /api/v1/hello/publish` - 发布消息到队列\n\n### 系统\n- `GET /ping` - 服务健康检查\n\n## 💡 使用示例\n\n### 创建用户\n```bash\ncurl -X POST http://localhost:8080/api/v1/users \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"username\": \"testuser\",\n    \"email\": \"test@example.com\",\n    \"password\": \"password123\"\n  }'\n```\n\n### 发布消息\n```bash\ncurl -X POST http://localhost:8080/api/v1/hello/publish \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"content\": \"Hello, World!\",\n    \"sender\": \"user123\"\n  }'\n```\n\n### 获取用户列表\n```bash\ncurl \"http://localhost:8080/api/v1/users?page=1\u0026page_size=10\"\n```\n\n## 🔧 开发工具\n\n### Makefile 命令\n```bash\n# 构建相关\nmake build           # 构建所有二进制文件\nmake build-api       # 构建 API 服务\nmake build-consumer  # 构建消费者服务\nmake clean           # 清理构建产物\n\n# 运行相关\nmake run-api         # 运行 API 服务\nmake run-consumer    # 运行消费者服务\nmake mq-api          # 运行消息队列 API 服务\nmake mq-consumer     # 运行消息队列消费者\n\n# 代码质量\nmake test            # 运行测试\nmake test-coverage   # 运行测试并生成覆盖率报告\nmake fmt             # 格式化代码\nmake lint            # 代码检查\nmake vet             # 代码静态分析\n\n# 数据库操作\nmake db-migrate      # 数据库迁移\nmake db-seed         # 创建种子数据\n\n# 依赖管理\nmake wire            # 生成依赖注入代码\nmake deps            # 更新依赖\nmake install-tools   # 安装开发工具\n\n# Docker\nmake up       # 启动 Docker 服务\nmake down     # 停止 Docker 服务\n\n# 帮助信息\nmake help            # 显示所有可用命令\n```\n\n## 🏗️ 架构设计\n\n### 依赖注入\n使用 Wire 自动生成依赖注入代码，保证组件解耦：\n```go\n// 典型的依赖链\nDatabase -\u003e Repository -\u003e Service -\u003e Handler\n```\n\n### 中间件链\n```go\nr.Use(middleware.RequestID())      // 请求 ID\nr.Use(middleware.NewLogger(logger)) // 日志记录\nr.Use(middleware.NewRecovery(logger)) // 错误恢复\nr.Use(middleware.CORS())           // 跨域处理\n```\n\n### 统一响应格式\n```json\n{\n  \"code\": 200,\n  \"message\": \"success\",\n  \"data\": {...},\n  \"request_id\": \"uuid\"\n}\n```\n\n### 错误处理\n- 统一的错误处理机制\n- 结构化错误信息\n- HTTP 状态码映射\n- 错误日志记录\n\n## 📚 详细文档\n\n- [消息队列使用指南](docs/MESSAGE_QUEUE.md) - RabbitMQ 完整使用指南\n- [Wire 架构文档](docs/WIRE_ARCHITECTURE.md) - 依赖注入架构\n\n## 🧪 测试\n\n```bash\n# 运行所有测试\nmake test\n\n# 运行测试并生成覆盖率报告\nmake test-coverage\n\n# 测试特定功能\nmake test-mq-api    # 测试消息队列 API\n```\n\n## 📦 部署\n\n### 本地开发\n```bash\nmake run-api         # 启动 API 服务\nmake run-consumer    # 启动消费者服务 (可选)\n```\n\n### Docker 部署\n```bash\nmake docker-up       # 使用 Docker Compose 启动所有服务\n```\n\n### 生产构建\n```bash\nmake build           # 构建生产版本二进制文件\n```\n\n## 🔍 监控和调试\n\n### 健康检查\n- API 服务: `GET /ping`\n- 数据库连接状态检查\n- Redis 连接状态检查\n- RabbitMQ 连接状态检查\n\n### 日志监控\n- 结构化 JSON 日志\n- 请求 ID 追踪\n- 错误栈跟踪\n- 性能指标记录\n\n### 调试工具\n- RabbitMQ 管理界面: http://localhost:15672\n- 详细的错误信息和堆栈跟踪\n- 开发模式下的详细日志\n\n## 🛠️ 扩展指南\n\n### 添加新的 API 端点\n1. 在 `internal/model/` 中定义数据模型\n2. 在 `internal/repository/` 中实现数据访问层\n3. 在 `internal/service/` 中实现业务逻辑\n4. 在 `internal/handler/` 中实现 HTTP 处理器\n5. 在 `internal/router/` 中注册路由\n6. 在 `internal/wire/` 中配置依赖注入\n\n### 添加新的中间件\n1. 在 `internal/middleware/` 中创建中间件文件\n2. 在路由中注册中间件\n\n### 添加新的消息处理器\n1. 在 `internal/messaging/processors/` 中创建处理器\n2. 在配置文件中添加队列配置\n3. 注册到消息消费服务\n\n## 📄 许可证\n\n本项目基于 MIT 许可证开源。\n\n## 🤝 贡献指南\n\n1. Fork 项目\n2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)\n3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)\n4. 推送到分支 (`git push origin feature/AmazingFeature`)\n5. 打开 Pull Request\n\n---\n\n**快速开始**: `make run-api` → 访问 http://localhost:8080/ping \n\n## 🐳 Docker 部署\n\n### 快速开始\n\n1. **克隆项目**\n   ```bash\n   git clone \u003crepository-url\u003e\n   cd skeleton\n   ```\n\n2. **配置环境变量**\n   ```bash\n   cp .env.example .env\n   # 根据需要修改 .env 文件中的配置\n   ```\n\n3. **启动开发环境**\n   ```bash\n   # 使用 Make 命令\n   make docker-up\n   \n   # 或使用脚本\n   ./scripts/docker-dev.sh up\n   ```\n\n4. **访问服务**\n   - API 服务: http://localhost:8080\n   - API 文档: http://localhost:8080/api/v1/docs\n   - 数据库管理: http://localhost:8081\n   - RabbitMQ 管理: http://localhost:15672 (admin/admin123)\n\n### Docker 命令\n\n#### 开发环境管理\n```bash\n# 启动开发环境\nmake docker-up\n\n# 停止开发环境\nmake docker-down\n\n# 重启开发环境\nmake docker-restart\n\n# 查看服务日志\nmake docker-logs\n\n# 查看容器状态\nmake docker-ps\n\n# 进入 API 容器\nmake docker-shell\n\n# 清理环境\nmake docker-clean\n```\n\n#### 数据库操作\n```bash\n# 运行数据库迁移\nmake docker-migrate\n\n# 运行数据库种子\nmake docker-seed\n\n# 重置数据库\n./scripts/docker-dev.sh db reset\n```\n\n#### 镜像构建\n```bash\n# 构建所有服务镜像\nmake docker-build\n\n# 构建特定服务\ndocker build --build-arg SERVICE=api -t skeleton/api:latest .\ndocker build --build-arg SERVICE=scheduler -t skeleton/scheduler:latest .\n```\n\n### 部署模式\n\n#### 开发环境\n```bash\n# 启动开发环境（包含热重载）\ndocker compose -f docker compose.yaml -f docker compose.override.yaml up -d\n```\n\n#### 生产环境\n```bash\n# 构建生产镜像\nmake docker-build\n\n# 启动生产环境\nmake docker-prod\n\n# 或手动启动\ndocker compose -f docker compose.yaml -f docker compose.prod.yaml up -d\n```\n\n### 服务配置\n\n#### 端口映射\n- API 服务: 8080\n- PostgreSQL: 5432\n- Redis: 6379\n- RabbitMQ: 5672 (AMQP), 15672 (管理界面)\n- Adminer: 8081\n\n#### 环境变量\n主要环境变量配置（详见 `.env.example`）：\n```bash\n# 应用配置\nAPP_ENV=development\nAPI_PORT=8080\n\n# 数据库配置\nPOSTGRES_PASSWORD=123456\n\n# Redis 配置\nREDIS_PASSWORD=redis123\n\n# RabbitMQ 配置\nRABBITMQ_USER=admin\nRABBITMQ_PASSWORD=admin123\n```\n\n### 健康检查\n\n所有服务都配置了健康检查：\n- API: `curl http://localhost:8080/health`\n- PostgreSQL: `pg_isready`\n- Redis: `redis-cli ping`\n- RabbitMQ: `rabbitmq-diagnostics ping`\n\n### 监控和日志\n\n#### 日志管理\n```bash\n# 查看所有服务日志\ndocker compose logs -f\n\n# 查看特定服务日志\ndocker compose logs -f api\ndocker compose logs -f scheduler\n```\n\n#### 生产环境监控\n生产环境包含 Prometheus 和 Grafana：\n- Prometheus: http://localhost:9090\n- Grafana: http://localhost:3000 (admin/admin)\n\n### 故障排查\n\n#### 常见问题\n1. **端口占用**\n   ```bash\n   # 检查端口占用\n   lsof -i :8080\n   \n   # 修改端口映射\n   # 编辑 .env 文件中的端口配置\n   ```\n\n2. **容器启动失败**\n   ```bash\n   # 查看容器日志\n   docker compose logs \u003cservice_name\u003e\n   \n   # 重新构建镜像\n   docker compose build --no-cache \u003cservice_name\u003e\n   ```\n\n3. **数据库连接失败**\n   ```bash\n   # 检查数据库状态\n   docker compose ps postgres\n   \n   # 重启数据库\n   docker compose restart postgres\n   ```\n\n#### 调试模式\n```bash\n# 以调试模式启动 API 服务（包含 Delve 调试器）\ndocker compose -f docker compose.yaml -f docker compose.override.yaml up api\n\n# 连接调试器\ndlv connect localhost:2345\n```\n\n### 安全考虑\n\n1. **生产环境配置**\n   - 修改默认密码\n   - 配置防火墙规则\n   - 限制网络访问\n\n2. **敏感信息管理**\n   - 使用环境变量注入敏感配置\n   - 不要将 `.env` 文件提交到版本控制\n\n3. **容器安全**\n   - 使用非 root 用户运行应用\n   - 定期更新基础镜像\n   - 扫描镜像漏洞","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhedeqiang%2Fgo-skeleton","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhedeqiang%2Fgo-skeleton","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhedeqiang%2Fgo-skeleton/lists"}