本文手把手教你使用 Go 语言（基于 go-restful 框架）快速搭建一个符合 REST 规范、能接收并解析 JSON 请求体、返回结构化 JSON 响应的 Web API，适用于第三方系统集成场景。
本文手把手教你使用 go 语言（基于 `go-restful` 框架）快速搭建一个符合 rest 规范、能接收并解析 json 请求体、返回结构化 json 响应的 web api，适用于第三方系统集成场景。
Go 语言原生 net/http 包功能强大但偏底层，直接处理 JSON 请求/响应需手动调用 json.Decoder 和 json.Encoder，易出错且代码冗长。对于面向第三方开放的 Web API，推荐使用成熟、轻量、符合 REST 最佳实践的框架——如 go-restful。它内置内容协商（Content Negotiation）、自动 JSON 序列化/反序列化、路径路由、参数校验等能力，大幅提升开发效率与接口健壮性。
以下是一个完整可运行的示例，实现 /users 端点接收 POST 请求中的 JSON 用户数据，并记录日志（实际项目中可替换为数据库保存逻辑）：
package main
import (
"github.com/emicklei/go-restful/v3"
"log"
"net/http"
)
// User 是请求体对应的结构体，字段首字母必须大写（导出）才能被 JSON 包访问
type User struct {
Name string `json:"name"` // 显式指定 JSON 字段名，增强兼容性
Email string `json:"email,omitempty"` // 可选字段，空值不序列化
}
func postUser(req *restful.Request, resp *restful.Response) {
newUser := new(User)
// 自动从请求 Body 解析 JSON 到 newUser，无需手动读取和解码
if err := req.ReadEntity(newUser); err != nil {
log.Printf("JSON decode error: %v", err)
resp.WriteErrorString(http.StatusBadRequest, "Invalid JSON payload")
return
}
// ✅ 此处已成功获取结构化 User 实例
log.Printf("Received user: %+v", *newUser)
// 示例：返回成功响应（含 JSON）
resp.WriteHeader(http.StatusCreated)
if err := resp.WriteEntity(map[string]string{
"status": "success",
"message": "user saved",
"id": "12345", // 实际中可返回数据库生成的 ID
}); err != nil {
log.Printf("Failed to write response: %v", err)
resp.WriteErrorString(http.StatusInternalServerError, "Internal error")
}
}
func main() {
// 创建 RESTful WebService
ws := new(restful.WebService)
ws.Path("/users").
Consumes(restful.MIME_JSON). // 声明只接受 application/json
Produces(restful.MIME_JSON) // 声明响应为 application/json
// 定义 POST 路由，绑定处理器
ws.Route(ws.POST("").To(postUser).
Doc("Create a new user").
Param(ws.BodyParameter("user", "User object in JSON format").DataType("main.User")))
restful.Add(ws)
log.Println("API server starting on :8080...")
log.Fatal(http.ListenAndServe(":8080", nil))
}✅ 测试方式（终端执行）：
curl -v -H "Content-Type: application/json" \
-X POST http://localhost:8080/users \
-d '{"name": "Alice", "email": "alice@example.com"}'预期响应状态码为 201 Created，响应体为 JSON 格式成功消息。
⚠️ 关键注意事项：
-
结构体字段导出性：Go 中只有首字母大写的字段（如
Name）才会被json包序列化/反序列化，小写字段（如name）将被忽略； -
依赖安装：运行前请执行
go mod init your-module-name && go get github.com/emicklei/go-restful/v3； -
错误处理：示例中已包含基础错误捕获，生产环境建议统一封装错误响应格式（如添加
code、timestamp字段）； -
安全性补充：真实项目需增加 CORS 配置、请求限流、JWT 认证、输入校验（如使用
go-playground/validator）等； -
替代方案：若偏好更流行或更轻量的框架，
Gin（高性能）或Chi（极简中间件）也是优秀选择，原理类似，仅 API 写法略有差异。
通过本教程，你已掌握用 Go 构建专业级第三方 Web API 的核心范式：定义结构体 → 绑定路由 → 自动 JSON 编解码 → 返回标准化响应。下一步，可结合数据库（如 gorm）与中间件，构建完整的微服务接口层。
