[AI 翻译] How I write HTTP services in Go after 13 years

推荐查看原文！！！

How I write HTTP services in Go after 13 years | Grafana Labs

Mat Ryer, principal engineer at Grafana Labs and host of the Go Time podcast, shares what he's learned from more than a dozen years of writing HTTP services in Go.

https://grafana.com/blog/2024/02/09/how-i-write-http-services-in-go-after-13-years/

NewServer 构造函数

• NewServer 是一个大型构造函数，它将所有依赖项作为参数传入。

• 一般它会返回一个 http.Handler，在更复杂的场景时，它可以是专用类型。

• 它通常会配置自己的多路复用器并调用 routes.go。

func NewServer(
	logger *Logger
	config *Config
	commentStore *commentStore
	anotherStore *anotherStore
) http.Handler {
	mux := http.NewServeMux()
	addRoutes(
		mux,
		Logger,
		Config,
		commentStore,
		anotherStore,
	)
	var handler http.Handler = mux
	handler = someMiddleware(handler)
	handler = someMiddleware2(handler)
	handler = someMiddleware3(handler)
	return handler
}

var handler http.Handler = mux
handler = logging.NewLoggingMiddleware(logger, handler)
handler = logging.NewGoogleTraceIDMiddleware(logger, handler)
handler = checkAuthHeaders(handler)
return handler

// 创建一个新的 Server 实例
srv := NewServer(  
	// 传递日志记录器
	logger,  
	// 传递配置信息
	config,  
	// 传递租户存储
	tenantsStore,  
	// 传递 Slack 链接存储
	slackLinkStore,  
	// 传递 Microsoft Teams 链接存储
	msteamsLinkStore,  
	// 传递代理
	proxy,  
)  
// 创建一个 HTTP 服务器
httpServer := &http.Server{  
	// 设置服务器地址
	Addr:    net.JoinHostPort(config.Host, config.Port),  
	// 设置服务器处理程序
	Handler: srv,  
}  
// 启动一个 goroutine 来监听和服务 HTTP 请求
go func() {  
	// 打印监听地址
	log.Printf("listening on %s\n", httpServer.Addr)  
	// 启动监听和服务
	if err := httpServer.ListenAndServe(); err != nil && err != http.ErrServerClosed {  
		// 如果发生错误，打印错误信息
		fmt.Fprintf(os.Stderr, "error listening and serving: %s\n", err)  
	}  
}()  
// 创建一个 WaitGroup 用于等待所有 goroutine 完成
var wg sync.WaitGroup  
// 添加一个 goroutine 到 WaitGroup
wg.Add(1)  
// 启动一个 goroutine 来处理关闭操作
go func() {  
	// 延迟执行 Done() 函数
	defer wg.Done()  
	// 等待上下文被取消
	<-ctx.Done()  
	// 创建一个新的上下文，设置 10 秒的超时时间
	shutdownCtx := context.Background()  
	shutdownCtx, cancel := context.WithTimeout(shutdownCtx, 10 * time.Second)  
	// 延迟执行 cancel() 函数
	defer cancel()  
	// 关闭 HTTP 服务器
	if err := httpServer.Shutdown(shutdownCtx); err != nil {  
		// 如果发生错误，打印错误信息
		fmt.Fprintf(os.Stderr, "error shutting down http server: %s\n", err)  
	}  
}()  
// 等待所有 goroutine 完成
wg.Wait()  
// 返回 nil
return nil

长参数列表

srv := NewServer(
	logger,
	config,
	tenantsStore,
	commentsStore,
	conversationService,
	chatGPTService,
)

在 routes.go 中映射全部接口（API）

func addRoutes(
	mux                 *http.ServeMux,
	logger              *logging.Logger,
	config              Config,
	tenantsStore        *TenantsStore,
	commentsStore       *CommentsStore,
	conversationService *ConversationService,
	chatGPTService      *ChatGPTService,
	authProxy           *authProxy
) {
	mux.Handle("/api/v1/", handleTenantsGet(logger, tenantsStore))
	mux.Handle("/oauth2/", handleOAuth2Proxy(logger, authProxy))
	mux.HandleFunc("/healthz", handleHealthzPlease(logger))
	mux.Handle("/", http.NotFoundHandler())
}

main() 函数中只调用 run() 函数

func run(ctx context.Context, w io.Writer, args []string) error {
	ctx, cancel := signal.NotifyContext(ctx, os.Interrupt)
	defer cancel()

	// ...
}

func main() {
	ctx := context.Background()
	if err := run(ctx, os.Stdout, os.Args); err != nil {
		fmt.Fprintf(os.Stderr, "%s\\n", err)
		os.Exit(1)
	}
}

EDIT：我曾经在 main 中执行 signal.NotifyContext 部分，但 Dave Henderson（以及其他几个人）指出 cancel 不会被调用，所以我已将其移至 run 函数中。

func run(
	ctx    context.Context,
	args   []string,
	getenv func(string) string,
	stdin  io.Reader,
	stdout, stderr io.Writer,
) error

优雅停止

控制环境变量

args := []string{
	"myapp",
	"--out", outFile,
	"--fmt", "markdown",
}
go run(ctx, args, etc.)

getenv := func(key string) string {
	switch key {
	case "MYAPP_FORMAT":
		return "markdown"
	case "MYAPP_TIMEOUT":
		return "5s"
	default:
		return ""
}
go run(ctx, args, getenv)

func main() {
	ctx := context.Background()
	if err := run(ctx, os.Getenv, os.Stderr); err != nil {
		fmt.Fprintf(os.Stderr, "%s\\n", err)
		os.Exit(1)
	}
}

Maker 函数返回处理程序

// handleSomething 处理你经常听到的那些 Web 请求之一。
func handleSomething(logger *Logger) http.Handler {
	thing := prepareThing()
	return http.HandlerFunc(
		func(w http.ResponseWriter, r *http.Request) {
			// 使用 thing 处理请求
			logger.Info(r.Context(), "msg", "handleSomething")
		}
	)
}

在同一处解码/编码

func encode[T any](w http.ResponseWriter, r *http.Request, status int, v T) error {
	w.Header().Set("Content-Type", "application/json")
	w.WriteHeader(status)
	if err := json.NewEncoder(w).Encode(v); err != nil {
		return fmt.Errorf("encode json: %w", err)
	}
	return nil
}

func decode[T any](r *http.Request) (T, error) {
	var v T
	if err := json.NewDecoder(r.Body).Decode(&v); err != nil {
		return v, fmt.Errorf("decode json: %w", err)
	}
	return v, nil
}

err := encode(w, r, http.StatusOK, obj)

decoded, err := decode[CreateSomethingRequest](r)

验证数据

// Validator 是一个可以验证的对象。
type Validator interface {
	// Valid 检查对象并返回任何问题。如果 len(problems) == 0 则对象有效。
	Valid(ctx context.Context) (problems map[string]string)
}

• 必填字段不为空

• 具有特定格式的字符串（如电子邮件）是正确的

• 数字在可接受的范围内

func decodeValid[T Validator](r *http.Request) (T, map[string]string, error) {
	var v T
	if err := json.NewDecoder(r.Body).Decode(&v); err != nil {
		return v, nil, fmt.Errorf("decode json: %w", err)
	}
	if problems := v.Valid(r.Context()); len(problems) > 0 {
		return v, problems, fmt.Errorf("invalid %T: %d problems", v, len(problems))
	}
	return v, nil, nil
}

中间件的适配器模式

func adminOnly(h http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		if !currentUser(r).IsAdmin {
			http.NotFound(w, r)
			return
		}
		h(w, r)
	})
}

package app

func addRoutes(mux *http.ServeMux) {
	mux.HandleFunc("/api/", handleAPI())
	mux.HandleFunc("/about", handleAbout())
	mux.HandleFunc("/", handleIndex())
	mux.HandleFunc("/admin", adminOnly(handleAdminIndex()))
}

有时我会返回中间件

mux.Handle("/route1", middleware(logger, db, slackClient, rroll []byte, handleSomething(handlerSpecificDeps))
mux.Handle("/route2", middleware(logger, db, slackClient, rroll []byte, handleSomething2(handlerSpecificDeps))
mux.Handle("/route3", middleware(logger, db, slackClient, rroll []byte, handleSomething3(handlerSpecificDeps))
mux.Handle("/route4", middleware(logger, db, slackClient, rroll []byte, handleSomething4(handlerSpecificDeps))

func newMiddleware(
	logger Logger,
	db *DB,
	slackClient *slack.Client,
	rroll []byte,
) func(h http.Handler) http.Handler

middleware := newMiddleware(logger, db, slackClient, rroll)
mux.Handle("/route1", middleware(handleSomething(handlerSpecificDeps))
mux.Handle("/route2", middleware(handleSomething2(handlerSpecificDeps))
mux.Handle("/route3", middleware(handleSomething3(handlerSpecificDeps))
mux.Handle("/route4", middleware(handleSomething4(handlerSpecificDeps))

// middleware 是一个包装 http.Handlers 的函数
// 提供在执行 h 处理程序之前或之后的执行功能。
type middleware func(h http.Handler) http.Handler

隐藏请求/响应类型

func handleSomething() http.HandlerFunc {
	type request struct {
		Name string
	}
	type response struct {
		Greeting string `json:"greeting"`
	}
	return func(w http.ResponseWriter, r *http.Request) {
		...
	}
}

使用内联请求/响应类型在测试中进行额外的故事讲述

func TestGreet(t *testing.T) {  
	// 创建一个新的测试辅助工具
	is := is.New(t)  
	// 定义一个测试用的 Person 结构体
	person := struct {  
		// 使用 `json:"name"` 标签指定 JSON 序列化时的字段名
		Name string `json:"name"`  
	}{  
		// 设置 Name 字段的值
		Name: "Mat Ryer",  
	}  
	// 创建一个新的 bytes.Buffer 用于存储 JSON 数据
	var buf bytes.Buffer  
	// 使用 json.NewEncoder 将 Person 结构体编码成 JSON 数据
	err := json.NewEncoder(&buf).Encode(person)  
	// 使用 is.NoErr() 断言编码操作没有错误
	is.NoErr(err) // json.NewEncoder  
	// 创建一个新的 HTTP 请求
	req, err := http.NewRequest(http.MethodPost, "/greet", &buf)  
	// 使用 is.NoErr() 断言创建请求没有错误
	is.NoErr(err)  
	//... more test code here
}

sync.Once defer 设置

func handleTemplate(files string...) http.HandlerFunc {  
	// 使用 sync.Once 保证模板只解析一次
	var (  
		init    sync.Once  
		tpl     *template.Template  
		tplerr  error  
	)  
	// 返回一个 http.HandlerFunc，用于处理请求
	return func(w http.ResponseWriter, r *http.Request) {  
		// 使用 sync.Once.Do() 保证模板解析只执行一次
		init.Do(func(){  
			// 解析模板文件
			tpl, tplerr = template.ParseFiles(files...)  
		})  
		// 如果模板解析发生错误，则返回错误信息
		if tplerr != nil {  
			http.Error(w, tplerr.Error(), http.StatusInternalServerError)  
			return  
		}  
		// 使用解析好的模板
		// ... 使用 tpl 
	}  
}

• 错误检查在 init 函数之外，因此如果出现问题，我们仍然会显示错误，并且不会在日志中丢失它

• 如果未调用 handler，则永远不会完成此任务——这可能会带来巨大的好处，取决于您的代码是如何部署的。

面向测试而设计

• 通过查看测试，了解你的程序的功能有多容易？

• 在不担心破坏程序的情况下修改代码有多容易？

• 如果你的所有测试都通过了，你可以将其发布到生产环境吗？还是需要覆盖更多测试内容？

单元测试中的单元是什么？

1. 调用该函数以获取 http.Handler——你必须传入所有必需的依赖项（这是一个特性）。

2. 在返回的 http.Handler 上调用 ServeHTTP 方法，使用真实的 http.Request 和来自 httptest 包的 ResponseRecorder（请参阅https://pkg.go.dev/net/http/httptest#ResponseRecorder）

3. 对响应进行断言（检查状态代码，解码正文并确保它是正确的，检查任何重要的标头等）

使用 run 函数进行测试

func Test(t *testing.T) {
	ctx := context.Background()
	ctx, cancel := context.WithCancel(ctx)
	t.Cleanup(cancel)
	go run(ctx)
	// 测试代码在这里
}

等待准备就绪

// waitForReady 函数会调用指定的接口，直到它收到 200 响应，或者上下文被取消，或者超时。
func waitForReady(  
	// 传入上下文，用于取消操作
	ctx context.Context,   
	// 传入超时时间
	timeout time.Duration,   
	// 传入待检测的端点
	endpoint string,  
) error {  
	// 创建一个新的 HTTP 客户端
	client := http.Client{}  
	// 记录开始时间
	startTime := time.Now()  
	// 循环调用端点，直到收到 200 响应
	for {  
		// 创建一个新的 HTTP 请求，并设置上下文
		req, err := http.NewRequestWithContext(  
			ctx,   
			http.MethodGet,   
			endpoint,   
			nil,  
		)  
		// 如果创建请求失败，返回错误
		if err != nil {  
			return fmt.Errorf("failed to create request: %w", err)  
		}  
  
		// 执行 HTTP 请求
		resp, err := client.Do(req)  
		// 如果执行请求失败，打印错误信息并继续循环
		if err != nil {  
			fmt.Printf("Error making request: %s\n", err.Error())  
			continue  
		}  
		// 如果响应状态码为 200，则表示端点已就绪
		if resp.StatusCode == http.StatusOK {  
			fmt.Println("Endpoint is ready!")  
			// 关闭响应体
			resp.Body.Close()  
			// 返回 nil，表示成功
			return nil  
		}  
		// 关闭响应体
		resp.Body.Close()  
  
		// 使用 select 语句判断是否应该继续等待
		select {  
		// 如果上下文被取消，则返回错误信息
		case <-ctx.Done():  
			return ctx.Err()  
		// 否则，检查是否已超时
		default:  
			// 如果已经超时，则返回超时错误信息
			if time.Since(startTime) >= timeout {  
				return fmt.Errorf("timeout reached while waiting for endpoint")  
			}  
			// 等待一段时间，然后再次尝试请求
			// wait a little while between checks  
			time.Sleep(250 * time.Millisecond)  
		}  
	}  
}

将所有这些付诸实践

How I write HTTP services in Go after 13 years | Grafana Labs

Mat Ryer, principal engineer at Grafana Labs and host of the Go Time podcast, shares what he's learned from more than a dozen years of writing HTTP services in Go.

https://grafana.com/blog/2024/02/09/how-i-write-http-services-in-go-after-13-years/