从模板创建项目
Gone框架为开发者提供了丰富的项目模板，让您能够快速搭建各种类型的应用程序。本教程将手把手教您如何使用gonectl工具，从模板创建一个完整的Web项目。
我们将创建一个集成了以下技术栈的项目：
- Viper：配置文件管理
- XORM：数据库ORM操作
- Gin：高性能Web框架
整个过程只需几分钟，让我们开始吧！
第一步：安装gonectl工具
gonectl是Gone框架的命令行工具，它就像是您的项目管家，负责项目创建、代码生成等核心功能。
安装命令
go install github.com/gone-io/gonectl@latest
验证安装
安装完成后，在终端输入以下命令验证是否成功：
gonectl
如果看到命令帮助信息，说明安装成功！
💡 提示：如果遇到安装问题，请参考gonectl详细安装指南。
第二步：探索可用模板
Gone框架内置了多种实用模板，让我们先看看都有哪些选择：
gonectl create -l
您将看到丰富的模板列表，包括：
Available templates:
- config_center/apollo Apollo配置中心示例
- config_center/consul Consul配置中心示例
- config_center/etcd Etcd配置中心示例
- config_center/nacos Nacos配置中心示例
- es Elasticsearch示例项目
- gin+gorm+viper 使用Gin、GORM、Viper的简单Web演示
- gin+xorm+viper 使用Gin、XORM、Viper的Web演示
- grpc Gone gRPC示例项目
- grpc_use_discovery 带服务发现的gRPC示例
- http_use_discovery 使用Gin的HTTP服务发现示例
- openai OpenAI模型客户端集成
- simple 简单示例，使用Viper读取配置
- urllib 使用goner/urllib的HTTP客户端示例
- zap 在Gone框架中使用Zap日志
... 还有更多模板
第三步：创建您的第一个项目
我们选择gin+xorm+viper模板，它是一个功能完整的Web应用骨架，非常适合学习和实际开发。
创建项目
gonectl create -t gin+xorm+viper my-project
命令执行后，gonectl会自动：
- 下载模板文件
- 创建项目目录结构
- 初始化必要的配置文件
📝 说明：您可以将
my-project替换为任何您喜欢的项目名称。
第四步：了解项目结构
项目创建完成后，让我们看看都生成了什么：
cd my-project
tree
项目结构清晰明了，每个目录都有其特定用途：
my-project/
├── cmd/ # 🚀 程序入口
│ └── server/
│ ├── import.gone.go # 自动生成的导入文件
│ └── main.go # 主程序入口
├── config/ # ⚙️ 配置文件
│ └── default.properties # 默认配置
├── internal/ # 🏗️ 核心业务代码
│ ├── controller/ # 控制器层 - 处理HTTP请求
│ ├── interface/ # 接口定义层
│ │ ├── entity/ # 数据实体
│ │ └── service/ # 服务接口
│ ├── module/ # 业务模块层
│ │ ├── user/ # 用户相关功能
│ │ └── dependent/ # 依赖管理示例
│ ├── router/ # 路由配置
│ └── pkg/ # 工具包
├── scripts/ # 📜 脚本文件
│ └── mysql/
│ └── initdb.d/
│ └── user.sql # 数据库初始化脚本
├── tests/ # 🧪 测试文件
│ └── api/
├── docker-compose.yaml # Docker编排文件
├── Dockerfile # Docker镜像构建文件
└── README.md # 项目说明文档
这种结构遵循了Go项目的最佳实践，代码组织清晰，便于维护和扩展。
第五步：启动项目
现在让我们把项目跑起来！由于项目使用MySQL数据库，我们需要按顺序执行以下步骤：
5.1 启动数据库服务
# 使用Docker启动MySQL（后台运行）
docker compose up -d mysql
5.2 安装项目依赖
# 下载并安装Go模块依赖
go mod tidy
5.3 启动Web服务
# 使用gonectl运行项目
gonectl run ./cmd/server
如果一切顺利，您将看到类似以下的启动日志：
🎉 服务启动成功！
🌐 服务地址：http://localhost:8080
📊 健康检查：http://localhost:8080/health
第六步：测试API功能
项目启动后，让我们测试一下提供的API功能。这个模板项目提供了完整的用户管理功能：
6.1 用户注册
curl -X POST \
-H "Content-Type: application/json" \
-d '{"username":"admin","password":"admin"}' \
http://localhost:8080/api/users/register
6.2 用户登录
curl -X POST \
-H "Content-Type: application/json" \
-d '{"username":"admin","password":"admin"}' \
http://localhost:8080/api/users/login
6.3 获取用户信息
# 先获取登录Token
token=$(curl -s -X POST \
-H "Content-Type: application/json" \
-d '{"username":"admin","password":"admin"}' \
http://localhost:8080/api/users/login | jq -r '.data.token')
# 使用Token获取用户信息
curl -X GET \
-H "Authorization: Bearer $token" \
http://localhost:8080/api/users/me
💡 小贴士：您也可以使用项目中的
tests/api/user.http文件，配合VS Code的REST Client插件来测试API，更加直观方便。
第七步：Docker部署（可选）
如果您想要将项目容器化部署，Gone框架已经为您准备好了完整的Docker配置。
7.1 配置环境变量
echo "ENVIRONMENT=dev" > .env
7.2 构建Docker镜像
docker compose build
7.3 启动完整服务栈
# 启动Web服务和数据库
docker compose up -d
第八步：停止服务
当您完成开发工作后，可以优雅地停止所有服务：
# 停止并清理Docker容器
docker compose down
🎯 总结
通过本教程，您已经成功：
✅ 安装了Gone框架的命令行工具
✅ 了解了丰富的项目模板选择
✅ 创建了一个功能完整的Web项目
✅ 掌握了项目的目录结构和组织方式
✅ 成功启动并测试了项目功能
✅ 学会了Docker容器化部署
📄️ 项目详解
本文档详细介绍了使用Gone框架构建的Web项目结构与核心功能。Gone是一个轻量级的Go语言依赖注入框架，结合Gin提供了强大的Web开发能力。文档首先展示了项目的标准目录结构，包括应用入口、配置目录、内部代码组织等。随后详细说明了配置系统的实现，包括多环境配置文件层级与覆盖机制，以及常用配置项的功能说明。在路由系统部分，文档区分了需要鉴权和不需要鉴权的两种路由分组实现方式，并通过代码示例展示了如何创建和使用这些路由组。控制器实现部分则展示了如何注入路由组和服务接口，以及如何在控制器中注册路由处理函数。HTTP参数注入机制是Gone框架的一大特色，文档详细解释了通过 gone:"http,..." 标签将HTTP请求参数自动绑定到处理函数参数的方法，包括请求体、请求头、URL参数等多种注入类型的支持。最后，文档介绍了Gone框架的代码生成机制，包括 module.load.go 、 init.gone.go 和 import.gone.go 三种自动生成文件的作用，以及 gonectl 工具的使用技巧，这些功能大大减少了重复工作，提高了开发效率。本文档适合想要快速上手Gone框架进行Go语言Web开发的开发者阅读，通过学习本文档可以掌握Gone框架的基本用法、项目结构和组件化开发方法。