mccutchen/go-httpbin

go-httpbin

go-httpbin 是 Kenneth Reitz 的 httpbin 服务的一个完整且经过充分测试的 Go 语言实现，除 Go 标准库外无任何依赖。

https://pkg.go.dev/badge/github.com/mccutchen/go-httpbin/v2](https://pkg.go.dev/github.com/mccutchen/go-httpbin/v2) https://github.com/mccutchen/go-httpbin/actions/workflows/test.yaml/badge.svg](https://github.com/mccutchen/go-httpbin/actions/workflows/test.yaml) ![Coverage]([***]

镜像概述和主要用途

go-httpbin 是经典 HTTP 测试服务 httpbin 的 Go 语言移植版本，旨在提供一个轻量、可靠的 HTTP 请求/响应测试工具。它可作为独立服务运行，也可嵌入到 Go 应用中作为测试库，用于验证 HTTP 客户端行为、模拟各种 HTTP 响应场景（如状态码、延迟、请求头/体解析等）。

核心功能和特性

• 完整实现：覆盖 httpbin 核心端点（如 /get、/post、/status、/delay 等）
• 零外部依赖：仅使用 Go 标准库，部署简单，无额外依赖管理
• 多模式运行：支持作为独立服务（HTTP/HTTPS）或 Go 测试库使用
• 高度可配置：通过命令行参数或环境变量调整服务行为（端口、主机、最大请求体大小等）
• 轻量高效：Go 语言特性带来的低资源占用和快速响应

使用场景和适用范围

• API 客户端测试：验证 HTTP 客户端对不同请求方法、状态码、头信息的处理
• HTTP 协议调试：模拟延迟响应、大响应体、异常状态码等边缘场景
• 开发环境模拟：在本地开发中替代第三方 HTTP 服务，避免外部依赖
• 单元测试辅助：作为测试库嵌入 Go 应用，模拟 HTTP 服务交互逻辑

详细使用方法和配置说明

配置参数

go-httpbin 支持通过命令行参数或环境变量配置（命令行参数优先级高于环境变量）：

独立二进制文件

需先安装 Go 运行时环境，然后通过以下命令安装并运行：

bash
# 安装 go-httpbin 二进制
go install github.com/mccutchen/go-httpbin/v2/cmd/go-httpbin@latest

# 运行 HTTP 服务器
go-httpbin -host 127.0.0.1 -port 8081

# 运行 HTTPS 服务器（需先生成证书）
openssl genrsa -out server.key 2048
openssl req -new -x509 -sha256 -key server.key -out server.crt -days 3650
go-httpbin -host 127.0.0.1 -port 8081 -https-cert-file ./server.crt -https-key-file ./server.key

Docker 部署

Docker 镜像已发布至 https://hub.docker.com/r/mccutchen/go-httpbin/，支持直接运行：

基础 HTTP 服务

bash
# 随机映射端口运行
docker run -P mccutchen/go-httpbin

# 指定端口映射（主机8080端口映射到容器8080端口）
docker run -p 8080:8080 mccutchen/go-httpbin

HTTPS 服务（需挂载证书文件）

bash
# 生成证书（主机上执行）
openssl genrsa -out server.key 2048
openssl req -new -x509 -sha256 -key server.key -out server.crt -days 3650

# 挂载证书并运行 HTTPS 服务
docker run -d \
  -e HTTPS_CERT_FILE='/certs/server.crt' \
  -e HTTPS_KEY_FILE='/certs/server.key' \
  -v $(pwd):/certs \
  -p 8443:8080 \
  mccutchen/go-httpbin

Docker Compose 示例（docker-compose.yml）

yaml
version: '3'
services:
  go-httpbin:
    image: mccutchen/go-httpbin
    ports:
      - "8080:8080"
    environment:
      - HOST=0.0.0.0
      - PORT=8080
      - MAX_BODY_SIZE=2097152  # 2MB
    restart: always

单元测试辅助库

可将 httpbin 包作为测试库嵌入 Go 应用，模拟 HTTP 服务：

go
package httpbin_test

import (
	"net/http"
	"net/http/httptest"
	"os"
	"testing"
	"time"

	"github.com/mccutchen/go-httpbin/v2/httpbin"
)

func TestSlowResponse(t *testing.T) {
	// 创建 httpbin 实例
	app := httpbin.New()
	// 启动测试服务器
	testServer := httptest.NewServer(app.Handler())
	defer testServer.Close()

	// 配置 HTTP 客户端（设置超时 1 秒）
	client := http.Client{
		Timeout: time.Duration(1 * time.Second),
	}

	// 请求 /delay/10 端点（模拟 10 秒延迟响应）
	_, err := client.Get(testServer.URL + "/delay/10")
	// 验证客户端是否正确处理超时
	if !os.IsTimeout(err) {
		t.Fatalf("期望超时错误，实际错误: %s", err)
	}
}

自定义工具化

若需在生产环境中添加自定义观测性工具（如 metrics、结构化日志、分布式追踪等），可通过 Observer 机制包装服务。示例可参考 https://github.com/mccutchen/go-httpbin/tree/main/examples/custom-instrumentation（基于 DataDog 的请求观测示例）。

安装

作为 Go 项目依赖

bash
go get -u github.com/mccutchen/go-httpbin/v2

安装独立二进制

bash
go install github.com/mccutchen/go-httpbin/v2/cmd/go-httpbin@latest

与其他版本的差异

与原 httpbin（Python）比较

• 不支持 /brotli 端点（Go 标准库无内置 Brotli 支持）
• 忽略 ?show_env=1 查询参数（不特殊处理运行时环境头信息）
• 响应中字符串/字符串列表类型字段统一为列表类型（如请求头、查询参数、表单值）

与 ahmetb/go-httpbin 比较

• 零第三方依赖（仅依赖 Go 标准库）
• 更完整的端点实现

开发指南

bash
# 本地开发
make              # 构建项目
make test         # 运行测试
make testcover    # 运行测试并生成覆盖率报告
make run          # 本地运行服务

# 构建和推送 Docker 镜像
make image        # 构建 Docker 镜像
make imagepush    # 推送镜像到 Docker Hub