HTTP 服务链路#

假设我们的客户端构造一个 8080 端口的 GET /healthz 请求，而服务端需要返回 HTTP 200 OK，这其中基本的链路如下：

1
客户端连接 8080 端口
2
→ Go HTTP Server 读取并解析 HTTP 请求
3
→ 路由器根据请求路径寻找 Handler
4
→ /healthz 匹配到 healthz 函数
5
→ healthz 读取请求 r
6
→ 通过 w 写回响应

想要完成上面的链路，需要涉及如下的方法：

• net/http.ListenAndServe
• net/http.HandleFunc
• net/http.HandlerFunc
• net/http.ResponseWriter
• net/http.Request

我们接下来逐一讲解这些基本方法。

1
func http.HandleFunc(pattern string, handler func(http.ResponseWriter, *http.Request))

1
http.HandleFunc("/healthz", healthz)

1
func http.ListenAndServe(addr string, handler http.Handler) error

1
type HandlerFunc func(ResponseWriter, *Request)

1
r.Method      // GET、POST 等请求方法
2
r.URL         // 路径和查询参数
3
r.Header      // 请求头
4
r.Body        // 请求体
5
r.Context()   // 请求上下文和取消信号

1
HTTP/1.1 200 OK                   → 状态行
2
Content-Type: application/json    → 响应头
3

4
{"status":"ok"}                   → 响应体

1
w.Header().Set(...) // 设置响应头
2
w.WriteHeader(...)  // 设置响应状态码
3
w.Write(...)        // 写入响应体

第一个完整的例子#

所以对于实现一个简单的 GET /healthz 监听响应程序，我们可以这样书写代码：

1
package main
2

3
import (
4
  "log"
5
  "net/http"
6
)
7

8
func healthz(w http.ResponseWriter, r *http.Request) {
9
  if r.Method != http.MethodGet {
10
    w.WriteHeader(http.StatusMethodNotAllowed)
11
    return
12
  }
13
  w.Header().Set("Content-Type", "application/json")
14
  w.WriteHeader(http.StatusOK)
15
  w.Write([]byte(`{"status":"ok"}`))
16
}
17

18
func main() {
19
  http.HandleFunc("/healthz", healthz)
20
  log.Println("Server start ok")
21
  err := http.ListenAndServe(":8080", nil)
22
  if err != nil {
23
    log.Fatal(err)
24
    return
25
  }
26
}

Method 是什么#

先建立最基础的模型。从语义层面看，一个 HTTP Request 可以先关注：

1
Method + Path + Header + Body

其中 Method 可以先理解为客户端希望对目标资源执行的动作。例如 GET /targets/1 表示请求读取 /targets/1 所标识的资源。

HTTP Method 和 CRUD 有常见对应关系，但两者并非严格等价。例如 POST 也可以表示提交任务或触发处理，并不一定创建资源。

1
GET        → Read
2
POST       → Create（常见用法之一）
3
PUT/PATCH  → Update
4
DELETE     → Delete

GET#

GET 表示获取资源的当前表示。例如 GET /targets 通常读取 Target 集合，而 GET /targets/1 读取 ID 为 1 的单个 Target。

假设服务器中存在：

1
Target: 1
2
name = "google"
3
address = "https://google.com"
4

5
Target: 2
6
name = "github"
7
address = "https://github.com"

请求 GET /targets 时，服务器可以返回 JSON 数组：

1
HTTP/1.1 200 OK
2
Content-Type: application/json
3

4
[
5
  {
6
    "id": 1,
7
    "name": "google",
8
    "address": "https://google.com"
9
  },
10
  {
11
    "id": 2,
12
    "name": "github",
13
    "address": "https://github.com"
14
  }
15
]

如果请求 GET /targets/1，则只返回 ID 为 1 的资源；资源不存在时通常返回 404 Not Found。

GET 是安全且幂等的方法：“安全”表示客户端请求的目标不是修改服务器状态；“幂等”表示多次相同请求的预期效果与一次相同。

POST#

POST 表示客户端向目标资源提交数据，请服务器按照该资源的语义进行处理。在本项目中，它用于向集合创建一个新 Target：

1
POST /targets
2
Content-Type: application/json
3

4
{
5
  "name": "google",
6
  "address": "https://google.com"
7
}

创建成功后通常返回 201 Created 和创建后的资源，也可以通过 Location 响应头告诉客户端新资源的 URI。

设计资源风格的 API 时，一般使用 POST /targets，而不是 POST /createTarget，因为 Method 已经表达了操作语义。不过这是一种常见 API 设计方式，不是 HTTP 协议强制规定。

POST 通常不是幂等方法：重复发送同一个创建请求，可能创建多个不同资源。

PUT#

PUT 通常表示：

用客户端提供的完整表示替换目标资源的当前表示。

例如客户端发送：

1
PUT /targets/1
2
Content-Type: application/json
3

4
{
5
  "name": "google",
6
  "address": "https://google.com"
7
}

则服务器中的资源会被完整替换为：

1
{
2
  "id": 1,
3
  "name": "google",
4
  "address": "https://google.com"
5
}

PUT 是幂等方法：多次发送相同 PUT 请求，其预期服务器状态与发送一次相同。在 sentinel-go 当前约定中，更新不存在的 ID 返回 404 Not Found；HTTP 标准也允许某些 API 使用 PUT 创建指定 URI 的资源，因此具体行为需要在接口契约中写清楚。

PATCH#

PATCH 也表示更新。与 PUT 的完整替换不同，PATCH 请求体描述要应用到资源的一组局部修改，因此通常只提供需要变化的字段。

例如客户端发送：

1
PATCH /targets/1
2
Content-Type: application/json
3

4
{
5
  "name": "bing"
6
}

更新后的资源可能是：

1
{
2
  "id": 1,
3
  "name": "bing",
4
  "address": "https://google.com"
5
}

PUT 和 PATCH 成功后可以返回更新后的资源和 200 OK，也可以在不返回正文时使用 204 No Content；具体选择应保持一致并写入接口契约。PATCH 不保证天然幂等，其幂等性取决于补丁格式和操作语义。

DELETE#

DELETE 用于删除目标资源。当客户端发送 DELETE /targets/{id} 时，就是请求删除该 ID 对应的 Target；成功且不返回正文时通常使用 204 No Content，资源不存在时通常返回 404 Not Found。

DELETE 是幂等方法。这里的”幂等”指多次相同请求的预期服务器状态与执行一次相同，而不是要求每次响应状态码完全相同；第一次删除可能返回 204，再次删除可能返回 404。

安全性与幂等性速查#

自定义路由器#

最简单的例子使用了 http.ListenAndServe(":8080", nil)。其中第二个参数为 nil 时，服务器会使用全局的 http.DefaultServeMux。我们也可以显式创建并传入自己的路由器：

1
mux := http.NewServeMux()
2
mux.HandleFunc("/healthz", healthz)
3
http.ListenAndServe(":8080", mux)

这样，请求链会更加清晰：

1
客户端
2
  │
3
  │ GET /healthz
4
  ↓
5
HTTP Server（读取并解析请求）
6
  │
7
  ↓
8
mux（根据 Method + Path 匹配 Handler）
9
  │
10
  ↓
11
healthz
12
  │
13
  ↓
14
ResponseWriter
15
  │
16
  ↓
17
客户端

这里需要注意：如果路由通过 http.HandleFunc 注册，它会进入 DefaultServeMux；如果服务器最终使用的是新建的 mux，请求就匹配不到这些路由。因此，注册路由和启动服务器必须使用同一个 ServeMux。

Go 1.22 之后的方法路由#

在一些旧教程中，我们会看到下面的写法：

1
mux.HandleFunc("/targets", targetsHandler)
2

3
func targetsHandler(w http.ResponseWriter, r *http.Request) {
4
  switch r.Method {
5
  case http.MethodGet:
6
    // 查询
7
  case http.MethodPost:
8
    // 创建
9
  default:
10
    // 405
11
  }
12
}

从 Go 1.22 开始，标准库 ServeMux 的 pattern 支持 Method 和路径通配符，因此可以写成：

1
mux.HandleFunc("GET /targets", listTarget)
2
mux.HandleFunc("POST /targets", addTarget)
3

4
mux.HandleFunc("GET /targets/{id}", getTarget)
5
mux.HandleFunc("PUT /targets/{id}", updateTarget)
6
mux.HandleFunc("DELETE /targets/{id}", deleteTarget)

本文示例统一使用复数资源路径 /targets，而当前 sentinel-go 代码仍使用 /target。两种路径都能被路由器处理，但同一个项目应统一代码、README、测试和笔记中的接口契约，避免调用时混用。

HTTP Server 负责读取并解析原始请求，ServeMux 接收解析后的 *http.Request，再根据 Method、Host 和 Path 选择 Handler。换句话说，ServeMux 是请求多路复用器，而不是 HTTP 报文解析器。

{id} 只匹配一个路径段，可以通过 r.PathValue("id") 读取，返回值类型是 string。另外，"GET /targets/{id}" 也会匹配 HEAD 请求；当 Path 能匹配、Method 不能匹配时，ServeMux 会返回 405 Method Not Allowed。

处理路径参数：ID 问题#

r.PathValue() 返回字符串。如果资源 ID 使用整数表示，就需要进行转换，并将转换失败视为客户端请求错误：

1
id, err := strconv.Atoi(r.PathValue("id"))
2
if err != nil {
3
  http.Error(w, "invalid id", http.StatusBadRequest)
4
  return
5
}

PathValue 读取的是 ServeMux 已匹配路径通配符的值。例如路由 pattern 为 "GET /targets/{id}" 时，请求 /targets/12 得到的 id 是字符串 "12"。如果请求没有经过包含该通配符的路由匹配，结果会是空字符串。

生成 ID 时不能简单使用 len(targets) + 1，因为删除中间元素后，新 ID 可能与仍然存在的 ID 冲突。当前练习可以维护独立的递增计数器；并发处理请求时，计数器和 map 必须放在同一套同步策略下保护。

如何返回 JSON#

可以使用标准库中的 json.NewEncoder(w).Encode(value) 构造 JSON 响应，并通过结构体标签控制字段名称：

1
type Target struct {
2
  ID   int    `json:"id"`
3
  Name string `json:"name"`
4
  Addr string `json:"address"`
5
}

写入正文前需要设置响应头和状态码：

1
w.Header().Set("Content-Type", "application/json")
2
w.WriteHeader(http.StatusOK)
3
if err := json.NewEncoder(w).Encode(value); err != nil {
4
  // 记录错误；响应提交后不能再修改状态码。
5
}

第一次调用 WriteHeader，或者第一次写入响应体时，HTTP 状态码就会提交。状态码提交后再调用 http.Error，不能把已经发送的 200 改成 500。如果必须保证”编码失败时返回 500”，可以先用 json.Marshal 在内存中完成编码，成功后再写响应头和正文。

当需要返回多个资源时，可以先构造切片，再编码成 JSON 数组：

1
list := make([]Target, 0, len(targets))
2
for _, target := range targets {
3
  list = append(list, target)
4
}
5

6
if err := json.NewEncoder(w).Encode(list); err != nil {
7
  // 记录错误
8
}

如何解析 JSON#

请求体可以通过 Decoder 解析到结构体中：

1
var req TargetRequest
2

3
if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
4
  http.Error(w, "invalid json", http.StatusBadRequest)
5
  return
6
}

这里需要传入 &req，因为 Decoder 必须修改调用方持有的变量，才能把解析结果写入结构体字段。解析和校验通过后，再构造资源并写入服务器的存储：

1
target := Target{
2
  ID:   nextID,
3
  Name: req.Name,
4
  Addr: req.Addr,
5
}
6

7
targets[nextID] = target

拒绝未知字段与业务校验#

如果希望拒绝目标结构体中不存在的 JSON 字段，可以使用：

1
var req TargetRequest
2
decoder := json.NewDecoder(r.Body)
3
decoder.DisallowUnknownFields()
4

5
if err := decoder.Decode(&req); err != nil {
6
  http.Error(w, "invalid json", http.StatusBadRequest)
7
  return
8
}

DisallowUnknownFields 只负责拒绝未知字段，不会判断缺失字段、空字符串或地址是否合法；这些业务规则仍需单独校验。Decode 本身会报告 JSON 语法错误和类型不匹配。

1
if req.Name == "" || req.Addr == "" {
2
  http.Error(w, "name and address are required", http.StatusBadRequest)
3
  return
4
}

只调用一次 Decode 还可能接受正文末尾的第二个 JSON 值。需要严格限制请求正文时，可以在第一次解析成功后再次解析并确认得到 io.EOF，同时根据服务边界考虑限制请求体大小。

map 中的结构体是值副本#

当 targets 的类型是 map[int]Target 时，下面读取出的 target 是结构体副本：

1
target, ok := targets[id]

修改副本后必须显式写回：

1
target.Name = req.Name
2
target.Addr = req.Addr
3
targets[id] = target

否则 PUT 响应可能返回新值，但后续 GET 仍然读到旧值。

Handler 中不要调用 log.Fatal#

非法 ID、非法 JSON 和资源不存在都只是一次请求的失败，不应终止整个服务器。log.Fatal 记录日志后会调用 os.Exit(1)，因此 Handler 应返回合适的 4xx；服务器内部错误一般记录日志并返回 500。

当前实现边界#

当前 sentinel-go 使用内存 map 保存 Target，因此服务重启后数据会丢失。net/http 会并发处理请求，而普通 map 与自增 ID 计数器不能安全地被多个请求同时读写；后续需要引入互斥保护并使用 go test -race 验证。自动化测试、服务超时和优雅退出也尚未完成。