👷 实践是最好的学习方式！这一篇我们将用 Go + Gin 框架从零开始开发一个用户管理 API 服务。你将学到：
- 如何初始化项目并引入依赖
- 如何组织目录结构
- 如何用 Gin 实现 RESTful 接口
- 如何通过 curl 测试 API
- 进阶功能拓展建议
🧰 一、项目初始化与依赖安装
第一步，先创建项目目录并初始化 Go Modules：
mkdir go-user-api && cd go-user-api
go mod init github.com/yourname/go-user-api
然后安装我们将使用的 Web 框架 —— Gin：
go get -u github.com/gin-gonic/gin
✅ 你现在已经具备开发 Go Web 服务的基本环境。
📁 二、推荐的项目目录结构
保持简单，便于理解，也方便未来扩展：
go-user-api/
├── main.go # 应用入口
├── go.mod # 模块定义
├── go.sum # 依赖锁定文件
├── handlers/ # 路由处理逻辑
│ └── user.go
└── models/ # 数据模型结构体（可选）
📌 提醒：随着项目变复杂，可拆分出
service/,middleware/,config/,router/,utils/等目录。
🧪 三、实现用户 API 接口
目标是实现两个基础接口：
GET /users：返回所有用户数据POST /users：添加一个新用户
📄 main.go
package main
import (
"github.com/gin-gonic/gin"
"go-user-api/handlers"
)
func main() {
r := gin.Default()
// 注册路由
r.GET("/users", handlers.GetUsers)
r.POST("/users", handlers.CreateUser)
// 启动服务
r.Run(":8080")
}
📄 handlers/user.go
package handlers
import (
"net/http"
"github.com/gin-gonic/gin"
)
// 模拟用户结构体和数据
type User struct {
ID int `json:"id"`
Name string `json:"name"`
}
var users = []User{
{ID: 1, Name: "Alice"},
{ID: 2, Name: "Bob"},
}
// GET /users
func GetUsers(c *gin.Context) {
c.JSON(http.StatusOK, users)
}
// POST /users
func CreateUser(c *gin.Context) {
var newUser User
if err := c.ShouldBindJSON(&newUser); err != nil {
c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
return
}
newUser.ID = len(users) + 1
users = append(users, newUser)
c.JSON(http.StatusCreated, newUser)
}
🧪 四、启动服务并测试接口
启动服务：
go run main.go
服务默认监听 http://localhost:8080
使用 curl 测试接口
📥 获取用户列表：
curl http://localhost:8080/users
📤 添加新用户：
curl -X POST http://localhost:8080/users -H "Content-Type: application/json" -d '{"name":"Charlie"}'
返回示例：
{
"id": 3,
"name": "Charlie"
}
🔧 五、接口设计补充说明
推荐的 RESTful 风格规范：
| 请求方法 | 路径 | 含义 |
|---|---|---|
| GET | /users | 查询所有用户 |
| GET | /users/:id | 查询单个用户 |
| POST | /users | 创建新用户 |
| PUT | /users/:id | 更新用户信息 |
| DELETE | /users/:id | 删除用户 |
这些是 RESTful 接口的基本设计规范，在大型项目中非常常见。
📦 六、进阶拓展建议
✅ 想继续提升？你可以尝试：
- 🗄 接入 GORM 实现真实数据库（SQLite / MySQL）
- ✏️ 添加表单校验：使用 Gin 的
binding+validator - 🔐 增加登录、注册与 JWT 身份认证
- 🧪 编写单元测试（使用
httptest.NewRecorder()） - 🛡️ 使用中间件做访问日志、限流、错误恢复等处理
- 📂 添加日志框架如
zap，记录结构化日志 - 📚 提取配置文件（使用
viper管理 YAML/JSON）
🧠 七、小结与回顾
本篇我们完成了一个完整的 Go + Gin 实战项目的搭建和基本功能实现。你已经学到了：
- 如何初始化 Go 项目并安装依赖
- 如何用 Gin 实现基础的 API 路由与处理
- 如何通过 curl 工具测试接口
- 如何组织项目目录结构以支持未来拓展
📌 实战才是学习的核心，加油！后续我们会继续介绍部署与上线技巧 🚀
🪧 下一篇预告
🚀 Go语言-初学者日记（八）：部署与构建——Go 项目上线指南
包括go build编译、Docker 打包、环境变量配置、部署上线等内容，敬请期待！
