Go 语言是当今开发后端 Web 接口的主力语言之一。平时我们在手机 App 或网页上刷新列表、提交表单时,背后通常就是由 HTTP 服务器负责接收请求并返回数据的。
在 Go 语言中,标准库 net/http 包直接内置了高性能的 HTTP 服务端功能。我们不需要安装配置复杂的外部服务器软件,只写十几行代码就能在本地启动一个 Web 服务。
启动第一个 HTTP 服务器
在 Go 语言中搭建一个最基本的 HTTP 服务器,按顺序主要分为以下 3 步:
- 编写处理函数:我们定义当客户端访问某个路径时,服务器具体要执行什么代码、返回什么内容。
- 注册路由:我们调用
http.HandleFunc()把网址路径(如"/hello")和对应的处理函数绑定起来。 - 监听端口并启动服务:我们调用
http.ListenAndServe()指定本机监听端口(如":8080"),开始等待客户端发来请求。
语法:
func 处理函数名(w http.ResponseWriter, r *http.Request) {
// 处理请求并向 w 写入响应内容
}
http.HandleFunc("/路径", 处理函数名)
http.ListenAndServe(":端口号", nil)说明:
在处理函数的参数列表中,w 和 r 的类型是固定不变的。其中,http.ResponseWriter 本身是一个接口,因此前面不需要加星号(*)。而 http.Request 是一个结构体,为了避免每次请求都复制整个对象,这里固定使用结构体指针 *http.Request。
初学的小伙伴可以把这两个参数想象成餐厅服务员手里的两样东西:
- r *http.Request(客户端请求):就像顾客递过来的 “点菜单”,里面记录了客户端发来的所有信息,例如访问的网址
r.URL、请求方法r.Method以及提交的参数。 - w http.ResponseWriter(响应写入器):就像服务员端给顾客的 “餐盘”。我们在函数里调用
fmt.Fprintln(w, ...)或w.Write(...)往w里面写什么内容,客户端就会收到什么内容。
客户端与处理函数之间的数据流向如下图所示。

示例 1:搭建第一个 HTTP 服务器
package main
import (
"fmt"
"net/http"
)
func helloHandler(w http.ResponseWriter, r *http.Request) {
fmt.Fprintln(w, "欢迎来到绿叶网!")
}
func main() {
http.HandleFunc("/hello", helloHandler)
fmt.Println("服务已启动,请访问 http://localhost:8080/hello")
err := http.ListenAndServe(":8080", nil)
if err != nil {
fmt.Println("启动失败:", err)
}
}服务器启动后会一直处于等待请求的状态,不会像普通脚本那样自动退出。我们需要在本地终端执行 go run main.go 启动程序,首次启动时如果系统弹出防火墙提示,点击允许访问即可。
保持终端窗口不关闭,打开浏览器访问 http://localhost:8080/hello,运行结果如下。
欢迎来到绿叶网!分析:
http.HandleFunc("/hello", helloHandler) 表示告诉服务器:只要有客户端访问 "/hello" 这个路径,就自动调用 helloHandler 函数来处理。
随后的 http.ListenAndServe(":8080", nil) 会在本机的 8080 端口启动监听,第 2 个参数传 nil 表示使用标准库内置的默认路由器。想要停止当前服务时,回到终端按下快捷键(Ctrl + C)即可。
注意:
- 端口号前必须加冒号:在
http.ListenAndServe(":8080", nil)中,端口号前面必须加上英文冒号写成":8080"。如果漏掉冒号写成"8080",启动时会直接报错missing port in address(地址缺少端口号)。 - 避免端口重复占用:同一个端口在同一时刻只能被一个程序监听。我们在运行后面的示例前,记得先按快捷键(Ctrl + C)关掉正在运行的服务,否则新程序会因为端口被占用而启动失败。
获取查询参数与返回 JSON
在实际的后端接口开发中,客户端经常会在网址末尾通过问号(?)附带查询参数,比如 /api/user?name=Tony。同时,客户端通常希望服务器返回标准的 JSON 格式数据,而不是普通纯文本。
语法:
val := r.URL.Query().Get("参数名")
w.Header().Set("Content-Type", "application/json; charset=utf-8")
json.NewEncoder(w).Encode(数据对象)说明:
调用 r.URL.Query().Get("name") 可以直接提取出网址 ?name=Tony 中 "name" 对应的值。如果网址里没有传入该参数,则会返回空字符串 ""。
在返回数据时,我们先通过 w.Header().Set() 将响应头 Content-Type 设为 "application/json; charset=utf-8",再调用 encoding/json 包的 json.NewEncoder() 对结构体或 Map 做 JSON 编码并直接写入响应流 w 中。
示例 2:读取查询参数并返回 JSON
package main
import (
"encoding/json"
"fmt"
"net/http"
)
type UserResp struct {
Name string `json:"name"`
Message string `json:"message"`
}
func userHandler(w http.ResponseWriter, r *http.Request) {
// 1. 获取 URL 中的 name 查询参数
name := r.URL.Query().Get("name")
if name == "" {
name = "游客"
}
// 2. 设置响应头为 JSON 格式
w.Header().Set("Content-Type", "application/json; charset=utf-8")
// 3. 组装结构体并编码写入响应流 w
resp := UserResp{
Name: name,
Message: "你好," + name,
}
json.NewEncoder(w).Encode(resp)
}
func main() {
http.HandleFunc("/api/user", userHandler)
fmt.Println("服务已启动,请访问 http://localhost:8080/api/user?name=Tony")
if err := http.ListenAndServe(":8080", nil); err != nil {
fmt.Println("启动失败:", err)
}
}在本地启动服务后,打开浏览器访问 http://localhost:8080/api/user?name=Tony,运行结果如下。
{"name":"Tony","message":"你好,Tony"}分析:
当我们在浏览器中访问该地址时,r.URL.Query().Get("name") 会提取出查询参数 "Tony"。随后程序组装好 UserResp 结构体变量 resp,并通过 json.NewEncoder(w).Encode(resp) 将其编码为 JSON 文本发回浏览器。
如果我们直接访问不带参数的 http://localhost:8080/api/user,Get("name") 会返回空字符串,name 就会自动采用默认值 "游客"。小伙伴们可以在浏览器里删掉问号后面的参数试一下。
注意: 设置响应头 w.Header().Set() 或状态码 w.WriteHeader() 时,必须写在向 w 写入正文数据的代码之前。一旦调用 fmt.Fprintln()、w.Write() 或 Encode() 开始写入正文,响应头和默认状态码 200 就会立即发出,后续再修改将不再生效。
限定请求方法与提取路径参数
在早期的 Go 版本中,http.HandleFunc("/users", ...) 既不能直接限制只接收 GET 还是 POST 请求,也没法直接提取类似 /users/1001 这种嵌在路径里的参数。从 Go 1.22 版本开始,标准库原生支持在路由字符串里直接写出请求方法和 {参数名} 占位符。
语法:
http.HandleFunc("请求方法 /路径/{参数名}", 处理函数)
val := r.PathValue("参数名")说明:
在路由规则 "GET /users/{id}" 中,开头的 "GET "(末尾带空格)表示该接口只接收 GET 请求。路径中的 {id} 是动态路径参数占位符,在处理函数内部调用 r.PathValue("id") 就能直接取出对应的字符串值。
小伙伴们在本地练习这一写法时,记得确保安装的 Go 版本以及 go.mod 中声明的版本不低于 1.22。
示例 3:提取动态路径参数
package main
import (
"fmt"
"net/http"
)
func getUserHandler(w http.ResponseWriter, r *http.Request) {
id := r.PathValue("id") // 提取路径中 {id} 对应的值
fmt.Fprintf(w, "正在查询用户 ID:%s\n", id)
}
func main() {
http.HandleFunc("GET /users/{id}", getUserHandler)
fmt.Println("服务已启动,请访问 http://localhost:8080/users/1001")
if err := http.ListenAndServe(":8080", nil); err != nil {
fmt.Println("启动失败:", err)
}
}启动服务后,打开浏览器访问 http://localhost:8080/users/1001,运行结果如下。
正在查询用户 ID:1001分析:
http.HandleFunc("GET /users/{id}", getUserHandler) 注册了一条带方法限制的动态路由。当客户端以 GET 方式访问 /users/1001 时,占位符 {id} 就会匹配到 "1001",调用 r.PathValue("id") 即可将其取出。
如果客户端改用 POST 方式访问该地址,服务器会自动拒绝请求并返回 405 Method Not Allowed(方法不允许)状态码。
解析 POST 请求的 JSON 数据
在开发创建用户、提交订单等后端接口时,客户端通常会通过 POST 请求在请求体(Body)中发来一段 JSON 数据。在服务器端,请求体数据保存在 r.Body 中,我们调用 json.NewDecoder(r.Body).Decode() 就能直接将其解析到结构体里。
语法:
var req 结构体类型
err := json.NewDecoder(r.Body).Decode(&req)说明:
json.NewDecoder(r.Body) 会创建一个从请求体流读取数据的解码器,紧接着调用 .Decode(&req) 即可将 JSON 字段按名称填充到结构体变量 req 中。注意 Decode() 必须传入结构体变量的地址 &req,否则无法写入数据。
创建资源成功后,后端接口通常会通过 w.WriteHeader(http.StatusCreated) 返回 201 状态码,再把结果写回给客户端。下面我们来看完整示例。
示例 4:解析 POST 提交的 JSON
package main
import (
"encoding/json"
"fmt"
"net/http"
)
type UserReq struct {
Name string `json:"name"`
Age int `json:"age"`
}
func createUserHandler(w http.ResponseWriter, r *http.Request) {
var req UserReq
if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
http.Error(w, "JSON 格式错误", http.StatusBadRequest)
return
}
w.Header().Set("Content-Type", "application/json; charset=utf-8")
w.WriteHeader(http.StatusCreated) // 返回 201 Created 状态码
json.NewEncoder(w).Encode(map[string]any{
"status": "ok",
"name": req.Name,
"age": req.Age,
})
}
func main() {
http.HandleFunc("POST /api/users", createUserHandler)
fmt.Println("服务已启动,监听 POST http://localhost:8080/api/users")
if err := http.ListenAndServe(":8080", nil); err != nil {
fmt.Println("启动失败:", err)
}
}需要注意的是,平时我们在浏览器地址栏直接输入网址回车,发送的全都是 GET 请求,无法直接触发上面的 POST 接口。保持当前服务运行后,我们可以新开第 2 个终端窗口,根据当前系统执行下面的命令发送测试请求:
# macOS / Linux 终端
curl -X POST http://localhost:8080/api/users -d '{"name":"Rose","age":22}'
# Windows 终端(CMD / PowerShell)
curl.exe -X POST http://localhost:8080/api/users -d "{\"name\":\"Rose\",\"age\":22}"运行结果如下。
{"age":22,"name":"Rose","status":"ok"}分析:
在这个例子中,路由 "POST /api/users" 限制只接收 POST 请求。客户端提交 JSON 数据后,json.NewDecoder(r.Body).Decode(&req) 会读取请求体并填入 req 结构体中。如果发来的数据格式有误,程序就会通过 http.Error() 向客户端返回 400 错误状态码。
数据解析成功后,我们先调用 w.Header().Set() 声明 JSON 响应头,再调用 w.WriteHeader(http.StatusCreated) 设置 201 状态码,最后把结果编码写入 w。这样正好遵循了前面强调的 “先设响应头和状态码,再写正文” 的顺序。
此外,大家也可以直接使用前一节 “Go 发送 HTTP 请求” 中编写的 POST 客户端代码,将目标网址改为 http://localhost:8080/api/users 来完成本地客户端与服务端的收发联调。
自定义路由器与超时配置
前面 4 个示例为了简洁,都直接使用了 http.HandleFunc() 和 http.ListenAndServe(":8080", nil)。平时写小工具或本地练习这样写很省事,但在正式上线部署时,这种快捷写法存在 2 个隐患:
- 全局路由器容易互相干扰:
http.HandleFunc()会把路由注册到全局默认的路由器中,如果项目引入的某个第三方包也往里面注册了路径,就可能暴露出意料之外的接口。 - 默认没有超时限制:
http.ListenAndServe()启动的服务默认不会限制客户端的读写耗时,一旦遇到网络异常或慢速恶意连接,连接就会一直挂起并耗尽服务器资源。
在实际项目中,我们更推荐使用 http.NewServeMux() 创建独立的路由器,再配合 &http.Server{} 显式配置超时时间。
语法:
mux := http.NewServeMux()
mux.HandleFunc("GET /路径", 处理函数)
srv := &http.Server{
Addr: ":8080",
Handler: mux,
ReadTimeout: 5 * time.Second,
WriteTimeout: 10 * time.Second,
}
err := srv.ListenAndServe()说明:
http.NewServeMux() 会返回一个全新的路由器对象 mux,之后我们通过 mux.HandleFunc() 把接口全部注册在它上面,做到与全局默认路由器完全隔离。
在 http.Server 结构体中,ReadTimeout 用于限制读取客户端完整请求的最长时间,WriteTimeout 用于限制服务器写出响应的最长时间。配置好之后调用 srv.ListenAndServe() 即可启动服务。
示例 5:使用独立路由器与超时配置
package main
import (
"fmt"
"net/http"
"time"
)
func healthHandler(w http.ResponseWriter, r *http.Request) {
fmt.Fprintln(w, "ok")
}
func main() {
// 1. 创建独立的路由器并注册接口
mux := http.NewServeMux()
mux.HandleFunc("GET /health", healthHandler)
// 2. 配置带超时限制的 HTTP 服务器
srv := &http.Server{
Addr: ":8080",
Handler: mux,
ReadTimeout: 5 * time.Second,
WriteTimeout: 10 * time.Second,
}
fmt.Println("服务已启动,请访问 http://localhost:8080/health")
if err := srv.ListenAndServe(); err != nil {
fmt.Println("启动失败:", err)
}
}启动服务后,在浏览器访问 http://localhost:8080/health,运行结果如下。
ok分析:
在这个例子中,我们把 /health 健康检查接口注册到了独立的 mux 上,并通过 http.Server 给服务加上了 5 秒读超时和 10 秒写超时。这和我们给 HTTP 客户端设置 Timeout 是一个道理:客户端和服务端两边都设好超时保护,线上服务才不容易被异常连接拖垮。
常见问题
1. 多个浏览器同时访问这个 HTTP 服务器,会排队卡住吗?
不会。Go 的 net/http 服务器在底层已经帮我们做好了并发处理:每当有一个新请求进来,框架都会自动开启一个独立的协程(Goroutine)去调用对应的处理函数,不需要我们自己写 go 关键字。
不过也正因为处理函数是并发执行的,如果我们在函数里需要修改某个全局共享变量(比如统计总访问次数),记得使用前面学过的互斥锁做好并发保护。
2. 发送 HTTP 请求时必须手动写 defer resp.Body.Close(),搭建服务器时需要手动关闭 r.Body 吗?
不需要。在 HTTP 服务器端,当我们的处理函数执行返回后,net/http 框架会自动负责关闭并清理请求体 r.Body。小伙伴们不用像编写客户端代码那样每次都手写 defer r.Body.Close()。
