unkey 的 kitchensink：一个纯 Go 标准库实现的平台功能探针 HTTP 服务

unkey 的 kitchensink：一个纯 Go 标准库实现的平台功能探针 HTTP 服务

【免费下载链接】unkeyThe Developer Platform for Modern APIs项目地址: https://gitcode.com/GitHub_Trending/un/unkey

kitchensink是 unkey 仓库中一个刻意保持“最小化”的 Go 服务：它只依赖 Go 标准库，把平台各项能力（网关策略、部署路由、环境变量注入、请求头透传、日志采集等）各自封装成独立子包，每个子包就是一个端到端的“探针（probe）”。本文将以 svc/kitchensink/README.md 为主线，结合 main.go 及全部探针子包的源码实现，完整讲解它的设计约束、路由清单、配置方式、扩展方法、运行方式，以及每个探针背后真正验证的平台能力。读完本文，你将掌握如何运行、探测和扩展这个服务，也能理解它如何被当作 unkey 平台各类网关与部署特性的“活文档”。

kitchensink 是什么：探针即示例

Stdlib-only HTTP server. Each probe lives in its own subpackage and demonstrates one platform feature end-to-end — gateway policies, deployment routing, env injection, header propagation, and so on.

kitchensink 是一个仅使用 Go 标准库的 HTTP 服务器。它的核心理念是：每个探针（probe）独立成包，端到端演示一项平台能力——网关策略（gateway policies）、部署路由（deployment routing）、环境变量注入（env injection）、请求头透传（header propagation）等。

这些探针同时承担“可运行的工作示例（worked example）”角色：工程师阅读任意一个子包，就能获得一份完整、可直接复制粘贴的集成示例，了解如何接入对应能力，而无需在仓库里追着 import 到处跑。换句话说，kitchensink 的代码本身就是写给平台用户的教程。

这个定位在入口文件的注释里同样明确——main.go 开头写道：Command kitchensink runs a stdlib-only HTTP server that exposes every probe subpackage as a real HTTP endpoint.（kitchensink 命令运行一个纯标准库 HTTP 服务器，把每个探针子包暴露为真实 HTTP 端点）。

三条硬性约束：标准库、无状态、小而精

README 为 kitchensink 定义了三条不可逾越的约束，这也决定了它的代码风格与架构边界：

1. 仅用 Go 标准库（Go standard library only）。不允许任何第三方依赖。唯一被允许的本地 import 是internal/httpx，用于平凡的响应拼装（例如httpx.JSON），它被放在internal/目录下，从而保持在“工作示例”的展示面之外。同时探针之间不允许互相 import（No cross-probe imports）。
2. 无状态（Stateless）。不使用数据库、不使用缓存、不存活过单个请求的 goroutine。每个 handler 都是“请求的纯函数”。
3. 小（Small）。如果一个探针膨胀到约 50 行以上，它大概率应该被拆成独立服务，而不是继续塞在 kitchensink 的某个角落。

这三条约束在代码中体现得相当彻底。以internal/httpx为例，httpx.go 的包注释明确解释了它存在的意义：让每个探针的 handler 专注于自己演示的能力——一次辅助调用胜过四行响应头拼装；同时放在internal/下，让读者看到的探针代码是“标准库调用 + 一个很小的本地 import”，而不是一层庞大的工具库。

httpx目前只提供唯一一个函数：

// JSON writes v as indented JSON with the given status code and the // application/json Content-Type. func JSON(w http.ResponseWriter, status int, v any) { w.Header().Set("Content-Type", "application/json") w.WriteHeader(status) enc := json.NewEncoder(w) enc.SetIndent("", " ") _ = enc.Encode(v) }

它负责“以指定状态码写出带缩进的 JSON，并设置application/json的 Content-Type”——这是绝大多数探针的公共响应方式。

配置：只有环境变量，没有 CLI 标志

kitchensink只通过环境变量配置，不提供任何 CLI 标志。README 对此的解释是：部署（Deployments）负责注入环境变量，而这正是 kitchensink 存在要验证的契约（contract）——如果环境变量注入链路出了问题，这个服务第一时间就能暴露出来。

目前唯一的配置项是：

这一点在 main.go 中体现为很直接的三行逻辑：

port := os.Getenv("PORT") if port == "" { port = "8080" } addr := ":" + port

目录布局与完整路由清单

README 给出的目录布局与探针清单如下：

svc/kitchensink/ ├── main.go — wires method+path → handler ├── hello/ — GET /hello, smoke test ├── env/ — GET /env, process environment ├── buildinfo/ — GET /buildinfo, value injected via -ldflags -X ├── principal/ — GET /principal, decodes X-Unkey-Principal ├── headers/ — GET /headers, echoes request headers ├── echo/ — POST /echo, echoes body verbatim ├── logs/ — POST /log, logs body at INFO ├── status/ — GET /status/{code}, returns arbitrary status └── sleep/ — GET /sleep?d=<duration>, blocks before responding

结合源码，实际目录中还存在两个 README 布局里未展开的成员：index/（GET /路由清单页）和internal/httpx/（公共响应辅助）。真实目录结构以 svc/kitchensink 下的文件为准。

所有路由在 main.go 的routes切片中集中注册，注册表本身就是一份“端点 → 用途”的对照表：

启动装配与优雅退出

main.go 展示了完整的启动流程，其中值得注意的工程细节包括：

• JSON 结构化日志：slog.New(slog.NewJSONHandler(os.Stdout, nil))并slog.SetDefault，所有探针（如logs）通过全局slog记录日志，统一输出为 JSON 到 stdout，便于平台日志采集器（log aggregator）拾取。
• 路由注册即索引：mux.HandleFunc(rt.Pattern, rt.Fn)的同时调用index.Register(rt.Pattern, rt.Description)，把每个路由登记到GET /的自述页上。
• 超时保护：http.Server设置了ReadHeaderTimeout: 10 * time.Second，防止慢速请求头攻击或僵尸连接拖垮服务。
• 优雅退出：监听os.Interrupt与syscall.SIGTERM，收到信号后以 5 秒超时的srv.Shutdown(ctx)完成优雅下线，配合容器的停止流程。

自述页的实现：index 探针

index是唯一需要知道“有哪些路由”的探针，因此它与其他探针不同：main.go在启动时为每个路由调用一次Register，再把Handler挂载到根路径。其实现见 index/handler.go：Register用strings.Cut(pattern, " ")把形如"GET /hello"的 ServeMux 模式拆成方法与路径，Handler则按路径排序后以纯文本渲染出带分隔线的清单页。

逐个探针深入：每个端点验证什么

下面结合每个子包的源码，说明各探针的具体行为，以及它在平台中对应的验证场景。

GET /hello —— 最小可用形态与冒烟测试

hello/handler.go 是整个仓库最简单的探针，也是“新增探针的参考形状”：一个常量200 OK响应，Content-Type 为text/plain; charset=utf-8，正文是hello, world\n。

// Handler writes "hello, world" as text/plain. Registered by main.go. func Handler(w http.ResponseWriter, r *http.Request) { w.Header().Set("Content-Type", "text/plain; charset=utf-8") _, _ = w.Write([]byte("hello, world\n")) }

它的定位是管道本身的冒烟测试（smoke test for the pipeline itself）：如果请求能打到这个端点并拿到预期响应，说明从客户端、网关、路由到容器的整条链路是通的。

GET /env —— 验证部署环境变量注入

env/handler.go 把进程环境变量以 JSON 返回，并支持?prefix=按键前缀过滤：

func Handler(w http.ResponseWriter, r *http.Request) { prefix := r.URL.Query().Get("prefix") out := map[string]string{} for _, kv := range os.Environ() { k, v, _ := strings.Cut(kv, "=") if prefix != "" && !strings.HasPrefix(k, prefix) { continue } out[k] = v } httpx.JSON(w, http.StatusOK, out) }

它的用途是端到端验证部署环境变量注入（verifying deployment env injection works end-to-end）：把服务部署上去后，curl localhost:8080/env?prefix=MYAPP_，就能确认平台注入的变量是否真的进入了进程环境。

GET /buildinfo —— 验证-ldflags -X构建期注入

buildinfo/handler.go 演示的是链接期变量注入这条管线契约：build-time variable → ldflags -X → package var，与env探针的“运行时环境 → os.Getenv”形成鲜明对照。其核心是一个包级变量：

var Version = "unset"

"unset"是兜底哨兵值：本地go run没有注入时，探针依然能正常响应。覆盖它的命令是：

go build -ldflags "-X 'github.com/unkeyed/unkey/svc/kitchensink/buildinfo.Version=<value>'"

handler 则把该值以 JSON 返回：{"version": ...}。

在 Dockerfile 中可以看到这条管线在真实构建中的落地：构建阶段通过 Docker BuildKit 的 secret mount 把平台变量挂载到/run/secrets/.env，if [ -f /run/secrets/.env ]; then set -a && . /run/secrets/.env && set +a; fi加载后，以-ldflags "-X 'github.com/unkeyed/unkey/svc/kitchensink/buildinfo.Version=${VERSION:-unset}'"注入版本号——-f守卫保证本地无 secret 挂载时构建依然可用，${VERSION:-unset}与源码中的哨兵值保持一致。

GET /principal —— 解码网关注入的鉴权主体

principal/handler.go 验证的是frontline 网关在鉴权策略通过后设置的X-Unkey-Principal头。该头的常量与svc/frontline/internal/policies.PrincipalHeader保持一致（注释说明为保持 kitchensink 纯标准库、避免跨服务 import 而在此复制一份）。

行为分三种情况：

• 头不存在（即绕过 frontline 直连本端点）：返回401 Unauthorized，提示“需要带鉴权策略经由 frontline 访问本端点”；
• 头存在但 JSON 解析失败（frontline 传来了垃圾数据）：返回502 Bad Gateway——这是“网关的错，不是调用方的错”；
• 头合法：解析为 JSON 后原样返回。

raw := r.Header.Get(header) if raw == "" { http.Error(w, header+" header not set; reach this endpoint through frontline with an auth policy", http.StatusUnauthorized) return } var p map[string]any if err := json.Unmarshal([]byte(raw), &p); err != nil { http.Error(w, "invalid principal JSON from frontline: "+err.Error(), http.StatusBadGateway) return } httpx.JSON(w, http.StatusOK, p)

GET /headers —— 回显请求头，验证头透传

headers/handler.go 把收到的请求头整体以 JSON 返回：

func Handler(w http.ResponseWriter, r *http.Request) { httpx.JSON(w, http.StatusOK, r.Header) }

它的价值在于调试请求头经过 frontline、负载均衡器或任何中间代理后的透传情况（debugging header propagation）：端到端请求后检查响应里的头集合，即可确认自定义头、认证头是否被正确保留或改写。

POST /echo —— 验证请求体不被改写

echo/handler.go 原样返回请求体，并尽量保留Content-Type：

func Handler(w http.ResponseWriter, r *http.Request) { if ct := r.Header.Get("Content-Type"); ct != "" { w.Header().Set("Content-Type", ct) } _, _ = io.Copy(w, r.Body) }

实现直接用io.Copy把r.Body流式拷贝到w，不需要在内存里读完整请求体。它用于验证请求体透传与代理未静默改写 payload（proxies aren't silently rewriting payloads）。

POST /log —— 验证平台日志采集

logs/handler.go 读取请求体、以 INFO 级别记录到 stdout，并回显已记录的内容：

body, err := io.ReadAll(r.Body) if err != nil { http.Error(w, "failed to read body: "+err.Error(), http.StatusBadRequest) return } msg := string(body) slog.Info("kitchensink/log", "body", msg) httpx.JSON(w, http.StatusOK, map[string]string{"logged": msg})

其用途是验证平台日志采集器（log aggregator）能拾取应用日志：发送一条请求后，到平台日志侧确认kitchensink/log这条 INFO 日志是否如期出现。值得注意的是包名取logs而非log，正是为了避免遮蔽调用方可能用到的标准库log包（见该文件包注释）。

GET /status/{code} —— 任意状态码，演练上游错误处理

status/handler.go 从路径参数解析状态码并原样返回：

code, err := strconv.Atoi(r.PathValue("code")) if err != nil || code < 100 || code > 599 { http.Error(w, "code must be a valid HTTP status (100-599)", http.StatusBadRequest) return } http.Error(w, http.StatusText(code), code)

实现依赖 Go 1.22+ 的http.ServeMux路径通配符{code}与r.PathValue。它的用途是演练 frontline 对上游错误（502、429 等）的处理，而不需要一个真的会失败的 upstream——比如curl localhost:8080/status/503即可随时制造一个 503 上游。

GET /sleep —— 阻塞响应，演练超时与慢上游

sleep/handler.go 按?d=<duration>阻塞指定时长后返回 200：

dStr := r.URL.Query().Get("d") if dStr == "" { http.Error(w, "d query param required, e.g. /sleep?d=500ms", http.StatusBadRequest) return } d, err := time.ParseDuration(dStr) if err != nil || d < 0 { http.Error(w, "d must be a valid duration (e.g. 500ms, 2s, 1m): "+dStr, http.StatusBadRequest) return } select { case <-time.After(d): w.WriteHeader(http.StatusOK) _, _ = w.Write([]byte("slept " + d.String() + "\n")) case <-r.Context().Done(): }

时长用time.ParseDuration解析（"500ms"、"2s"、"1m30s"等）。实现通过select同时监听定时器与r.Context().Done()，尊重客户端取消，避免测试场景下泄漏 goroutine。它用于测试 frontline 的超时与慢上游行为（Frontline timeouts and slow-upstream behavior）。

新增一个探针：三步走

README 给出了新增探针的标准流程，结合源码可以展开为：

第 1 步：创建子包与 handler。在svc/kitchensink/<name>/handler.go中实现行为。

第 2 步：导出标准签名。写出func Handler(w http.ResponseWriter, r *http.Request)。hello/handler.go是最小可用形态的模板——只依赖net/http，不引入任何框架。

第 3 步：注册路由。在 main.go 的routes切片中追加一行：

"GET /<name>": <name>.Handler,

注册键使用Go 1.22+ 的http.ServeMux模式语法：GET /foo、POST /bar/{id}等，且方法 + 路径与 handler 一一对应。注册时main.go会自动完成三件事：挂载 handler、写入index自述页、打印一条registeredINFO 日志。

值得注意的是，README 中的注册示例（"GET /<name>": <name>.Handler）是简化写法，实际代码中routes是包含Pattern、Description、Fn三个字段的结构体切片，因此真实新增时需要同时提供路径模式、人类可读描述与 handler 三者，例如：

{"GET /hello", "Smoke test — returns 'hello, world'.", hello.Handler},

运行方式：本机、自定义端口与 Docker

README 给出了三种运行方式，均可直接套用。

方式一：直接以 Go 运行（默认端口 8080）：

go run ./svc/kitchensink

方式二：自定义端口（通过PORT环境变量覆盖）：

PORT=9090 go run ./svc/kitchensink

方式三：Docker 构建运行。注意构建上下文是仓库根目录，而不是 kitchensink 所在目录——因为二进制属于主 Go module（需要根目录的go.mod参与构建）：

docker build -f svc/kitchensink/Dockerfile -t kitchensink . docker run --rm -p 8080:8080 kitchensink

Dockerfile 的实现细节也值得注意：多阶段构建，builder 阶段基于golang:1.25-alpine，先单独拷贝go.mod/go.sum并go mod download以利用层缓存；运行阶段基于gcr.io/distroless/static-debian13:nonroot以非 root 用户运行；镜像内ENV PORT=8080并EXPOSE 8080，ENTRYPOINT直接执行二进制。构建时还通过 BuildKit secret 挂载.env来注入VERSION（见上文 buildinfo 探针）。

方式四：本地构建二进制（如需注入版本号）：

go build -ldflags "-X 'github.com/unkeyed/unkey/svc/kitchensink/buildinfo.Version=v1.0.0'" -o kitchensink ./svc/kitchensink

启动后，可以直接用 README 给出的三连探测验证服务健康：

curl localhost:8080/hello curl localhost:8080/env curl localhost:8080/status/503

另外还可以：

• curl localhost:8080/查看全部已注册路由的自述清单；
• curl -X POST localhost:8080/echo -d '{"foo":"bar"}' -H 'Content-Type: application/json'验证请求体回显；
• curl 'localhost:8080/sleep?d=2s'制造一次 2 秒的慢响应；
• curl -X POST localhost:8080/log -d 'hello logs'触发一条 INFO 日志；
• curl -H 'X-Unkey-Principal: {"sub":"user_123"}' localhost:8080/principal模拟网关注入的鉴权主体（无该头则返回 401）。

小结：kitchensink 在 unkey 中的角色

从仓库结构看，unkey 的svc/下并列着 api、ctrl、frontline、heimdall、krane、logdrain、vault 等生产服务，而 kitchensink 刻意保持了极简：它是验证平台特性的“测试插头”，同时也是面向集成者的“活文档”。每一个探针都用标准库写成一个最小可用的端到端示例，让工程师不必在大量业务代码中摸索，就能确认网关策略、部署路由、环境变量注入、请求头透传、日志采集、超时处理等能力是否按预期工作。

如果你想深入某个能力背后的实现，可以从这些路径继续阅读：网关侧的X-Unkey-Principal注入逻辑见 svc/frontline 下的 policies 相关代码，平台日志采集链路见 svc/logdrain，而 kitchensink 自身的全部探针源码则集中在 svc/kitchensink 目录下，可作为新增探针或集成对接的第一手参考。

【免费下载链接】unkeyThe Developer Platform for Modern APIs项目地址: https://gitcode.com/GitHub_Trending/un/unkey