Touka(灯花)框架

Touka(灯花) 是一个基于 Go 语言构建的多层次、高性能 Web 框架。其设计目标是为开发者提供更直接的控制、有效的扩展能力，以及针对特定场景的行为优化

Touka 的设计特点

Touka 在一些特定方面进行了细致的设计与实现，旨在提供便利的工具与更清晰的控制：

• 统一且可定制的错误处理 Touka 提供了灵活的错误处理机制，允许开发者通过 Engine.SetErrorHandler 设置统一的错误响应逻辑。此机制不仅适用于框架内部产生的错误，更特别之处在于它能够捕获由 http.FileServer 等标准库处理器返回的 404 Not Found、403 Forbidden 等错误状态码。

  • 设计考量： 默认情况下，http.FileServer 在文件未找到或权限不足时会直接返回标准错误响应。Touka 的设计能够拦截这些由 http.FileServer 发出的错误信号，并将其转发给框架统一的 ErrorHandler。这使得开发者可以为文件服务中的异常情况提供与应用其他部分风格一致的自定义错误响应，从而提升整体的用户体验和错误管理效率。

• 客户端 IP 来源的透明解析 Touka 提供了可配置的客户端 IP 获取机制。开发者可以通过 Engine.SetRemoteIPHeaders 指定框架优先从哪些 HTTP 头部（如 X-Forwarded-For、X-Real-IP）解析客户端真实 IP，并通过 Engine.SetForwardByClientIP 控制此机制的启用。

  • 实现细节： Context.RequestIP() 方法会根据这些配置，从 http.Request.Header 中解析并返回第一个有效的 IP 地址。如果未配置或头部中未找到有效 IP，则回退到 http.Request.RemoteAddr，并对 IP 格式进行验证。这有助于在存在多层代理的环境中获取准确的源 IP。

• 内置日志与出站 HTTP 客户端的 Context 绑定 Touka 的核心 Context 对象直接包含了对 reco.Logger（一个异步、结构化日志库）和 httpc.Client（一个功能增强的 HTTP 客户端）的引用。开发者可以直接通过 c.GetLogger() 和 c.Client() 在请求处理函数中访问这些工具。

  • 设计考量： 这种集成方式旨在提供这些核心工具在特定请求生命周期内的统一访问点。所有日志记录和出站 HTTP 请求操作都与当前请求上下文绑定，并能利用框架层面的全局配置，有助于简化复杂请求处理场景下的代码组织。

• 强健的 Panic 恢复与连接状态感知 Touka 提供的 Recovery 中间件能够捕获处理链中的 panic。它会记录详细的堆栈信息和请求快照。此外，它能识别由客户端意外断开连接引起的网络错误（如 broken pipe 或 connection reset by peer），在这些情况下，框架会避免尝试向已失效的连接写入响应。

  • 设计考量： 这有助于防止因底层网络问题或客户端行为导致的二次 panic，避免在关闭的连接上进行无效写入，从而提升服务的稳定性。

• HTTP 协议版本与服务器行为的细致控制 Touka 允许开发者通过 Engine.SetProtocols 方法，精确定义服务器支持的 HTTP 协议版本（HTTP/1.1、HTTP/2、H2C）。框架也提供了对重定向行为、未匹配路由处理和文件服务行为的配置选项。

  • 设计考量： 这种协议和行为的细致化控制，为开发者提供了在特定部署环境（如 gRPC-Web 对 HTTP/2 的要求）中对服务器通信栈进行调整的能力。

• Context 对象的高效复用 Touka 对其核心 Context 对象进行了池化管理。每个请求处理结束后，Context 对象会被重置并返回到对象池中，以便后续请求复用。

  • 设计考量： 这种机制旨在减少每次请求的内存分配和垃圾回收（GC）压力，尤其在高并发场景下，有助于提供更平滑和可预测的性能表现。

快速上手

package main

import (
	"fmt"
	"io"
	"log"
	"net/http"
	"os"
	"time"

	"github.com/fenthope/reco"
	"github.com/infinite-iroha/touka"
)

func main() {
	r := touka.New()

	// 配置日志记录器 (可选，不设置则使用默认配置)
	logConfig := reco.Config{
		Level:      reco.LevelDebug,
		Mode:       reco.ModeText, // 或 reco.ModeJSON
		Output:     os.Stdout,
		Async:      true,
		BufferSize: 4096,
	}
	r.SetLogger(logConfig)

	// 配置统一错误处理器
	// Touka 允许您为 404, 500 等错误定义统一的响应。
	// 特别地，它能捕获 http.FileServer 产生的 404/403 错误并统一处理。
	r.SetErrorHandler(func(c *touka.Context, code int) {
		// 这里可以根据 code 返回 JSON, HTML, 或其他自定义错误页面
		c.JSON(code, touka.H{"error_code": code, "message": http.StatusText(code)})
		c.GetLogger().Errorf("发生HTTP错误: %d, 路径: %s", code, c.Request.URL.Path) // 记录错误
	})

	// 注册基本路由
	r.GET("/hello", func(c *touka.Context) {
		// 设置响应头部
		c.SetHeader("X-Framework", "Touka") // 设置一个头部
		c.AddHeader("X-Custom-Info", "Hello") // 添加一个头部 (如果已有则追加)
		c.AddHeader("X-Custom-Info", "World") // 再次添加，Content-Type: X-Custom-Info: Hello, World

		// 获取请求头部
		acceptEncoding := c.GetReqHeader("Accept-Encoding")
		userAgent := c.UserAgent() // 便捷获取 User-Agent

		c.String(http.StatusOK, "Hello from Touka! Your Accept-Encoding: %s, User-Agent: %s", acceptEncoding, userAgent)
		c.GetLogger().Infof("请求 /hello 来自 IP: %s", c.ClientIP())
	})

	r.GET("/json", func(c *touka.Context) {
		// 删除响应头部
		c.DelHeader("X-Powered-By") // 假设有这个头部，可以删除它
		c.JSON(http.StatusOK, touka.H{"message": "Welcome to Touka", "timestamp": time.Now()})
	})

	// 注册包含路径参数的路由
	r.GET("/user/:id", func(c *touka.Context) {
		userID := c.Param("id") // 获取路径参数
		c.String(http.StatusOK, "User ID: %s", userID)
	})

	// 注册使用查询参数的路由
	r.GET("/search", func(c *touka.Context) {
		query := c.DefaultQuery("q", "default_query") // 获取查询参数，提供默认值
		paramB := c.Query("paramB")                  // 获取另一个查询参数
		c.String(http.StatusOK, "Search query: %s, Param B: %s", query, paramB)
	})
    
    // 注册处理 POST 表单的路由
    r.POST("/submit-form", func(c *touka.Context) {
        name := c.PostForm("name") // 获取表单字段值
        email := c.DefaultPostForm("email", "no_email@example.com") // 获取表单字段，提供默认值
        c.String(http.StatusOK, "Form submitted: Name=%s, Email=%s", name, email)
    })

    // 演示 Set 和 Get 方法在中间件中传递数据
    // 在中间件中 Set 数据
    r.Use(func(c *touka.Context) {
        c.Set("requestID", "req-12345") // 设置一个数据
        c.Next()
    })
    // 在路由处理函数中 Get 数据
    r.GET("/context-data", func(c *touka.Context) {
        requestID, exists := c.Get("requestID") // 获取数据
        if !exists {
            requestID = "N/A"
        }
        c.String(http.StatusOK, "Request ID from Context: %s", requestID)
    })

	// 服务静态文件
	// 使用 r.Static 方法，其错误（如 404）将由上面设置的 ErrorHandler 统一处理
	// 假设您的静态文件在项目根目录的 'static' 文件夹
	r.Static("/static", "./static")

	// 演示出站 HTTP 请求 (使用 Context 中绑定的 httpc.Client)
	r.GET("/fetch-example", func(c *touka.Context) {
		resp, err := c.Client().Get("https://example.com", httpc.WithTimeout(5*time.Second))
		if err != nil {
			c.Errorf("出站请求失败: %v", err) // 记录错误
			c.String(http.StatusInternalServerError, "Failed to fetch external resource")
			return
		}
		defer resp.Body.Close()
		bodyBytes, _ := io.ReadAll(resp.Body)
		c.String(http.StatusOK, "Fetched from example.com (first 100 bytes): %s...", bodyBytes[:min(len(bodyBytes), 100)])
	})

	// 演示 HTTP 协议控制
	// 默认已启用 HTTP/1.1。如果需要 HTTP/2，通常需在 TLS 模式下启用。
	// r.SetProtocols(&touka.ProtocolsConfig{
	// 	Http1:           true,
	// 	Http2:           true, // 启用 HTTP/2 (需要 HTTPS)
	// 	Http2_Cleartext: false,
	// })

	// 启动服务器 (支持优雅关闭)
	log.Println("Touka Server starting on :8080...")
	err := r.RunShutdown(":8080", 10*time.Second) // 优雅关闭超时10秒
	if err != nil {
		log.Fatalf("Touka server failed to start: %v", err)
	}
}

func min(a, b int) int {
	if a < b {
		return a
	}
	return b
}

中间件支持

内置

Recovery r.Use(touka.Recovery())

fenthope

访问日志-record

Gzip

压缩-Compress(Deflate,Gzip,Zstd)

请求速率限制-ikumi

sessions

jwt

带宽限制

文档与贡献

• API 文档： 访问 pkg.go.dev/github.com/infinite-iroha/touka 查看完整的 API 参考

• 贡献： 我们欢迎任何形式的贡献，无论是错误报告、功能建议还是代码提交。请遵循项目的贡献指南

• 可供参考, AI生成存在幻觉, 不完全可靠, 请注意辨别

相关项目

gin 参考并引用了相关部分代码

reco 灯花框架的默认日志库

httpc 原touka-httpc, 一个现代化且易用的HTTP Client, 作为Touka框架Context携带的HTTPC

许可证

本项目使用MPL许可证

tree部分来自gin与httprouter

WJQSERVER/httproute是本项目的前身(一个httprouter的fork版本)