Go 搭建 HTTP 服务器

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 里面写什么内容,客户端就会收到什么内容。

客户端与处理函数之间的数据流向如下图所示。

HTTP 处理函数中请求 r 与响应 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()。

上一篇:

下一篇:

给站长反馈

绿叶网正在不断完善中,小伙伴们如果发现任何问题,还望多多给站长反馈,谢谢!

邮箱:lvyenet@vip.qq.com

「绿叶网」服务号
绿叶网服务号放大
关注服务号,微信也能看教程。
绿叶网服务号