update about

README.md

@@ -1,34 +1,10 @@
 # Touka(灯花)框架
 
-Touka(灯花) 是一个基于 Go 语言构建的多层次、高性能 Web 框架。其设计目标是为开发者提供**更直接的控制、有效的扩展能力，以及针对特定场景的行为优化**
+Touka(灯花) 是一个基于 Go 语言构建的多层次、高性能 Web 框架。其设计目标是为开发者提供**更直接的控制、有效的扩展能力，以及针对特定场景的行为优化**。
 
-## Touka 的设计特点
+**想深入了解 Touka 吗？请阅读我们的 -> [深度指南 (about-touka.md)](about-touka.md)**
 
-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）压力，尤其在高并发场景下，有助于提供更平滑和可预测的性能表现。
 
 ### 快速上手
 
@@ -48,166 +24,68 @@ import (
 )
 
 func main() {
-	r := touka.New()
+	r := touka.Default() // 使用带 Recovery 中间件的默认引擎
 
-	// 配置日志记录器 (可选，不设置则使用默认配置)
+	// 配置日志记录器 (可选)
 	logConfig := reco.Config{
 		Level:      reco.LevelDebug,
-		Mode:       reco.ModeText, // 或 reco.ModeJSON
+		Mode:       reco.ModeText,
 		Output:     os.Stdout,
 		Async:      true,
-		BufferSize: 4096,
 	}
-	r.SetLogger(logConfig)
+	r.SetLoggerCfg(logConfig)
 
 	// 配置统一错误处理器
-	// Touka 允许您为 404, 500 等错误定义统一的响应。
+	r.SetErrorHandler(func(c *touka.Context, code int, err error) {
-	// 特别地，它能捕获 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) // 记录错误
+		c.GetLogger().Errorf("发生HTTP错误: %d, 路径: %s, 错误: %v", code, c.Request.URL.Path, err)
 	})
 
-	// 注册基本路由
+	// 注册路由
-	r.GET("/hello", func(c *touka.Context) {
+	r.GET("/hello/:name", func(c *touka.Context) {
-		// 设置响应头部
+		name := c.Param("name")
-		c.SetHeader("X-Framework", "Touka") // 设置一个头部
+		query := c.DefaultQuery("mood", "happy")
-		c.AddHeader("X-Custom-Info", "Hello") // 添加一个头部 (如果已有则追加)
+		c.String(http.StatusOK, "Hello, %s! You seem %s.", name, query)
-		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 := r.RunShutdown(":8080", 10*time.Second); err != nil {
-	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())`
+- **Recovery:** `r.Use(touka.Recovery())` (已包含在 `touka.Default()` 中)
 
-### fenthope
+### 第三方 (fenthope)
 
-[访问日志-record](https://github.com/fenthope/record) 
+- [访问日志-record](https://github.com/fenthope/record)
-
+- [Gzip](https://github.com/fenthope/gzip)
-[Gzip](https://github.com/fenthope/gzip)
+- [压缩-Compress(Deflate,Gzip,Zstd)](https://github.com/fenthope/compress)
-
+- [请求速率限制-ikumi](https://github.com/fenthope/ikumi)
-[压缩-Compress(Deflate,Gzip,Zstd)](https://github.com/fenthope/compress)
+- [sessions](https://github.com/fenthope/sessions)
-
+- [jwt](https://github.com/fenthope/jwt)
-[请求速率限制-ikumi](https://github.com/fenthope/ikumi)
+- [带宽限制](https://github.com/fenthope/toukautil/blob/main/bandwithlimiter.go)
-
-[sessions](https://github.com/fenthope/sessions)
-
-[jwt](https://github.com/fenthope/jwt)
-
-[带宽限制](https://github.com/fenthope/toukautil/blob/main/bandwithlimiter.go)
 
 ## 文档与贡献
 
-*   **API 文档：** 访问 [pkg.go.dev/github.com/infinite-iroha/touka](https://pkg.go.dev/github.com/infinite-iroha/touka) 查看完整的 API 参考
+*   **深度指南:** **[about-touka.md](about-touka.md)**
-*   **贡献：** 我们欢迎任何形式的贡献，无论是错误报告、功能建议还是代码提交。请遵循项目的贡献指南
+*   **API 文档：** 访问 [pkg.go.dev/github.com/infinite-iroha/touka](https://pkg.go.dev/github.com/infinite-iroha/touka) 查看完整的 API 参考。
-
+*   **贡献：** 我们欢迎任何形式的贡献，无论是错误报告、功能建议还是代码提交。请遵循项目的贡献指南。
-*   [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/infinite-iroha/touka) 可供参考, AI生成存在幻觉, 不完全可靠, 请注意辨别
 
 ## 相关项目
 
-[gin](https://github.com/gin-gonic/gin) 参考并引用了相关部分代码
+- [gin](https://github.com/gin-gonic/gin): Touka 在路由和 API 设计上参考了 Gin。
-
+- [reco](https://github.com/fenthope/reco): Touka 框架的默认日志库。
-[reco](https://github.com/fenthope/reco) 灯花框架的默认日志库
+- [httpc](https://github.com/WJQSERVER-STUDIO/httpc): 一个现代化且易用的 HTTP Client，作为 Touka 框架 Context 携带的 HTTPC。
-
-[httpc](https://github.com/WJQSERVER-STUDIO/httpc) 原[touka-httpc](https://github.com/satomitouka/touka-httpc), 一个现代化且易用的HTTP Client, 作为Touka框架Context携带的HTTPC
 
 ## 许可证
 
-本项目使用MPL许可证
+本项目基于 [Mozilla Public License, v. 2.0](https://mozilla.org/MPL/2.0/) 许可。
 
-tree部分来自[gin](https://github.com/gin-gonic/gin)与[httprouter](https://github.com/julienschmidt/httprouter)
+`tree.go` 部分代码源自 [gin](https://github.com/gin-gonic/gin) 与 [httprouter](https://github.com/julienschmidt/httprouter)，其原始许可为 BSD-style。
-
-[WJQSERVER/httproute](https://github.com/WJQSERVER/httprouter)是本项目的前身(一个[httprouter](https://github.com/julienschmidt/httprouter)的fork版本)

about-touka.md

@@ -0,0 +1,577 @@
+# 关于 Touka (灯花) 框架：一份深度指南
+
+Touka (灯花) 是一个基于 Go 语言构建的、功能丰富且高性能的 Web 框架。它的核心设计目标是为开发者提供一个既强大又灵活的工具集，允许对框架行为进行深度定制，同时通过精心设计的组件和机制，优化在真实业务场景中的开发体验和运行性能。
+
+本文档旨在提供一份全面而深入的指南，帮助您理解 Touka 的核心概念、设计哲学以及如何利用其特性来构建健壮、高效的 Web 应用。
+
+---
+
+## 核心设计哲学
+
+Touka 的设计哲学根植于以下几个核心原则：
+
+*   **控制力与可扩展性:** 框架在提供强大默认功能的同时，也赋予开发者充分的控制权。我们相信开发者最了解自己的业务需求。因此，无论是路由行为、错误处理逻辑，还是服务器协议，都可以根据具体需求进行精细调整和扩展。
+*   **明确性与可预测性:** API 设计力求直观和一致，使得框架的行为易于理解和预测，减少开发过程中的意外。我们避免使用过多的“魔法”，倾向于让代码的意图清晰可见。
+*   **性能意识:** 在核心组件的设计中，性能是一个至关重要的考量因素。通过采用如对象池、优化的路由算法等技术，Touka 致力于在高并发场景下保持低延迟和高吞吐。
+*   **开发者体验:** 框架内置了丰富的辅助工具和便捷的 API，例如与请求上下文绑定的日志记录器和 HTTP 客户端，旨在简化常见任务，提升开发效率。
+
+---
+
+## 核心功能深度剖析
+
+### 1. 引擎 (Engine)：框架的中央枢纽
+
+`Engine` 是 Touka 框架的实例，也是所有功能的入口和协调者。它实现了 `http.Handler` 接口，可以无缝集成到 Go 的标准 HTTP 生态中。
+
+#### 1.1. 初始化引擎
+
+```go
+// 创建一个“干净”的引擎，不包含任何默认中间件
+r := touka.New()
+
+// 创建一个带有默认中间件的引擎，目前仅包含 Recovery()
+// 推荐在生产环境中使用，以防止 panic 导致整个服务崩溃
+r := touka.Default()
+```
+
+#### 1.2. 引擎配置
+
+`Engine` 提供了丰富的配置选项，允许您定制其核心行为。
+
+```go
+func main() {
+    r := touka.New()
+
+    // === 路由行为配置 ===
+
+    // 自动重定向尾部带斜杠的路径，默认为 true
+    // e.g., /foo/ 会被重定向到 /foo
+    r.SetRedirectTrailingSlash(true)
+
+    // 自动修复路径的大小写，默认为 true
+    // e.g., /FOO 会被重定向到 /foo (如果 /foo 存在)
+    r.SetRedirectFixedPath(true)
+
+    // 当路由存在但方法不匹配时，自动处理 405 Method Not Allowed，默认为 true
+    r.SetHandleMethodNotAllowed(true)
+
+    // === IP 地址解析配置 ===
+
+    // 是否信任 X-Forwarded-For, X-Real-IP 等头部来获取客户端 IP，默认为 true
+    // 在反向代理环境下非常有用
+    r.SetForwardByClientIP(true)
+    // 自定义用于解析 IP 的头部列表，按顺序查找
+    r.SetRemoteIPHeaders([]string{"X-Forwarded-For", "X-App-Client-IP", "X-Real-IP"})
+
+    // === 请求体大小限制 ===
+
+    // 设置全局默认的请求体最大字节数，-1 表示不限制
+    // 这有助于防止 DoS 攻击
+    r.SetGlobalMaxRequestBodySize(10 * 1024 * 1024) // 10 MB
+
+    // ... 其他配置
+    r.Run(":8080")
+}
+```
+
+#### 1.3. 服务器生命周期管理
+
+Touka 提供了对底层 `*http.Server` 的完全控制，并内置了优雅关闭的逻辑。
+
+```go
+func main() {
+    r := touka.New()
+
+    // 通过 ServerConfigurator 对 http.Server 进行自定义配置
+    r.SetServerConfigurator(func(server *http.Server) {
+        // 设置自定义的读写超时时间
+        server.ReadTimeout = 15 * time.Second
+        server.WriteTimeout = 15 * time.Second
+        fmt.Println("自定义的 HTTP 服务器配置已应用")
+    })
+
+    // 启动服务器，并支持优雅关闭
+    // RunShutdown 会阻塞，直到收到 SIGINT 或 SIGTERM 信号
+    // 第二个参数是优雅关闭的超时时间
+    fmt.Println("服务器启动于 :8080")
+    if err := r.RunShutdown(":8080", 10*time.Second); err != nil {
+        log.Fatalf("服务器启动失败: %v", err)
+    }
+}
+```
+
+---
+
+### 2. 路由系统 (Routing)：强大、灵活、高效
+
+Touka 的路由系统基于一个经过优化的**基数树 (Radix Tree)**，它支持静态路径、路径参数和通配符，并能实现极高的查找性能。
+
+#### 2.1. 基本路由
+
+```go
+// 精确匹配的静态路由
+r.GET("/ping", func(c *touka.Context) {
+    c.String(http.StatusOK, "pong")
+})
+
+// 注册多个 HTTP 方法
+r.HandleFunc([]string{"GET", "POST"}, "/data", func(c *touka.Context) {
+    c.String(http.StatusOK, "Data received via %s", c.Request.Method)
+})
+
+// 注册所有常见 HTTP 方法
+r.ANY("/any", func(c *touka.Context) {
+    c.String(http.StatusOK, "Handled with ANY for method %s", c.Request.Method)
+})
+```
+
+#### 2.2. 参数化路由
+
+使用冒号 `:` 来定义路径参数。
+
+```go
+r.GET("/users/:id", func(c *touka.Context) {
+    // 通过 c.Param() 获取路径参数
+    userID := c.Param("id")
+    c.String(http.StatusOK, "获取用户 ID: %s", userID)
+})
+
+r.GET("/articles/:category/:article_id", func(c *touka.Context) {
+    category := c.Param("category")
+    articleID := c.Param("article_id")
+    c.JSON(http.StatusOK, touka.H{
+        "category": category,
+        "id":       articleID,
+    })
+})
+```
+
+#### 2.3. 通配符路由 (Catch-all)
+
+使用星号 `*` 来定义通配符路由，它会捕获该点之后的所有路径段。**通配符路由必须位于路径的末尾**。
+
+```go
+// 匹配如 /static/js/main.js, /static/css/style.css 等
+r.GET("/static/*filepath", func(c *touka.Context) {
+    // 捕获的路径可以通过参数名 "filepath" 获取
+    filePath := c.Param("filepath")
+    c.String(http.StatusOK, "请求的文件路径是: %s", filePath)
+})
+```
+
+#### 2.4. 路由组 (RouterGroup)
+
+路由组是组织和管理路由的强大工具，特别适用于构建结构化的 API。
+
+```go
+func main() {
+    r := touka.New()
+
+    // 所有 /api/v1 下的路由都需要经过 AuthMiddleware
+    v1 := r.Group("/api/v1")
+    v1.Use(AuthMiddleware()) // 应用组级别的中间件
+    {
+        // 匹配 /api/v1/products
+        v1.GET("/products", getProducts)
+        // 匹配 /api/v1/products/:id
+        v1.GET("/products/:id", getProductByID)
+
+        // 可以在组内再嵌套组
+        ordersGroup := v1.Group("/orders")
+        ordersGroup.Use(OrderPermissionsMiddleware()) // 更具体的中间件
+        {
+            // 匹配 /api/v1/orders
+            ordersGroup.GET("", getOrders)
+            // 匹配 /api/v1/orders/:id
+            ordersGroup.GET("/:id", getOrderByID)
+        }
+    }
+
+    r.Run(":8080")
+}
+
+func AuthMiddleware() touka.HandlerFunc {
+    return func(c *touka.Context) {
+        // 模拟认证逻辑
+        fmt.Println("V1 Auth Middleware: Checking credentials...")
+        c.Next()
+    }
+}
+// ... 其他处理器
+```
+
+---
+
+### 3. 上下文 (Context)：请求的灵魂
+
+`touka.Context` 是框架中最为核心的结构，它作为每个 HTTP 请求的上下文，在中间件和最终处理器之间流转。它提供了海量的便捷 API 来简化开发。
+
+#### 3.1. 请求数据解析
+
+##### 获取查询参数
+
+```go
+// 请求 URL: /search?q=touka&lang=go&page=1
+r.GET("/search", func(c *touka.Context) {
+    // c.Query() 获取指定参数，不存在则返回空字符串
+    query := c.Query("q") // "touka"
+
+    // c.DefaultQuery() 获取参数，不存在则返回指定的默认值
+    lang := c.DefaultQuery("lang", "en") // "go"
+    category := c.DefaultQuery("cat", "all") // "all"
+
+    c.JSON(http.StatusOK, touka.H{
+        "query":    query,
+        "language": lang,
+        "category": category,
+    })
+})
+```
+
+##### 获取 POST 表单数据
+
+```go
+// 使用 curl 测试:
+// curl -X POST http://localhost:8080/register -d "username=test&email=test@example.com"
+r.POST("/register", func(c *touka.Context) {
+    username := c.PostForm("username")
+    email := c.DefaultPostForm("email", "anonymous@example.com")
+    // 也可以获取所有表单数据
+    // form, _ := c.Request.MultipartForm()
+
+    c.String(http.StatusOK, "注册成功: 用户名=%s, 邮箱=%s", username, email)
+})
+```
+
+##### JSON 数据绑定
+
+Touka 可以轻松地将请求体中的 JSON 数据绑定到 Go 结构体。
+
+```go
+type UserProfile struct {
+    Name    string   `json:"name" binding:"required"`
+    Age     int      `json:"age" binding:"gte=18"`
+    Tags    []string `json:"tags"`
+    Address string   `json:"address,omitempty"`
+}
+
+// 使用 curl 测试:
+// curl -X POST http://localhost:8080/profile -H "Content-Type: application/json" -d '''
+// {
+//   "name": "Alice",
+//   "age": 25,
+//   "tags": ["go", "web"]
+// }
+// '''
+r.POST("/profile", func(c *touka.Context) {
+    var profile UserProfile
+    
+    // c.ShouldBindJSON() 会解析 JSON 并填充到结构体中
+    if err := c.ShouldBindJSON(&profile); err != nil {
+        // 如果 JSON 格式错误或不满足绑定标签，会返回错误
+        c.JSON(http.StatusBadRequest, touka.H{"error": err.Error()})
+        return
+    }
+
+    c.JSON(http.StatusOK, touka.H{
+        "status":  "success",
+        "profile": profile,
+    })
+})
+```
+
+#### 3.2. 响应构建
+
+##### 发送 JSON, String, Text
+
+```go
+r.GET("/responses", func(c *touka.Context) {
+    // c.JSON(http.StatusOK, touka.H{"framework": "Touka"})
+    // c.String(http.StatusOK, "Hello, %s", "World")
+    c.Text(http.StatusOK, "This is plain text.")
+})
+```
+
+##### 渲染 HTML 模板
+
+首先，需要为引擎配置一个模板渲染器。
+
+```go
+// main.go
+import "html/template"
+
+func main() {
+    r := touka.New()
+    // 加载模板文件
+    r.HTMLRender = template.Must(template.ParseGlob("templates/*.html"))
+
+    r.GET("/index", func(c *touka.Context) {
+        // 渲染 index.html 模板，并传入数据
+        c.HTML(http.StatusOK, "index.html", touka.H{
+            "title": "Touka 模板渲染",
+            "user":  "Guest",
+        })
+    })
+
+    r.Run(":8080")
+}
+
+// templates/index.html
+// <h1>{{ .title }}</h1>
+// <p>Welcome, {{ .user }}!</p>
+```
+
+##### 文件和流式响应
+
+```go
+// 直接发送一个文件
+r.GET("/download/report", func(c *touka.Context) {
+    // 浏览器会提示下载
+    c.File("./reports/latest.pdf")
+})
+
+// 将文件内容作为响应体
+r.GET("/show/config", func(c *touka.Context) {
+    // 浏览器会直接显示文件内容（如果支持）
+    c.SetRespBodyFile(http.StatusOK, "./config.yaml")
+})
+
+// 流式响应，适用于大文件或实时数据
+r.GET("/stream", func(c *touka.Context) {
+    // 假设 getRealTimeDataStream() 返回一个 io.Reader
+    // dataStream := getRealTimeDataStream()
+    // c.WriteStream(dataStream)
+})
+```
+
+#### 3.3. Cookie 操作
+
+Touka 提供了简单的 API 来管理 Cookie。
+
+```go
+r.GET("/login", func(c *touka.Context) {
+    // 设置一个有效期为 1 小时的 cookie
+    c.SetCookie("session_id", "user-12345", 3600, "/", "localhost", false, true)
+    c.String(http.StatusOK, "登录成功！")
+})
+
+r.GET("/me", func(c *touka.Context) {
+    sessionID, err := c.GetCookie("session_id")
+    if err != nil {
+        c.String(http.StatusUnauthorized, "请先登录")
+        return
+    }
+    c.String(http.StatusOK, "您的会话 ID 是: %s", sessionID)
+})
+
+r.GET("/logout", func(c *touka.Context) {
+    // 通过将 MaxAge 设置为 -1 来删除 cookie
+    c.DeleteCookie("session_id")
+    c.String(http.StatusOK, "已退出登录")
+})
+```
+
+#### 3.4. 中间件数据传递
+
+使用 `c.Set()` 和 `c.Get()` 可以在处理链中传递数据。
+
+```go
+// 中间件：生成并设置请求 ID
+func RequestIDMiddleware() touka.HandlerFunc {
+    return func(c *touka.Context) {
+        requestID := fmt.Sprintf("req-%d", time.Now().UnixNano())
+        c.Set("RequestID", requestID)
+        c.Next()
+    }
+}
+
+func main() {
+    r := touka.New()
+    r.Use(RequestIDMiddleware())
+
+    r.GET("/status", func(c *touka.Context) {
+        // 在处理器中获取由中间件设置的数据
+        // c.MustGet() 在 key 不存在时会 panic，适用于确定存在的场景
+        requestID := c.MustGet("RequestID").(string)
+        
+        // 或者使用安全的 Get
+        // requestID, exists := c.GetString("RequestID")
+
+        c.JSON(http.StatusOK, touka.H{"status": "ok", "request_id": requestID})
+    })
+
+    r.Run(":8080")
+}
+```
+
+#### 3.5. 集成的工具
+
+##### 日志记录
+
+Touka 集成了 `reco` 日志库，可以直接在 `Context` 中使用。
+
+```go
+r.GET("/log-test", func(c *touka.Context) {
+    userID := "user-abc"
+    c.Infof("用户 %s 访问了 /log-test", userID)
+    
+    err := errors.New("一个模拟的错误")
+    if err != nil {
+        c.Errorf("处理请求时发生错误: %v, 用户: %s", err, userID)
+    }
+
+    c.String(http.StatusOK, "日志已记录")
+})
+```
+
+##### HTTP 客户端
+
+Touka 集成了 `httpc` 客户端，方便发起出站请求。
+
+```go
+r.GET("/fetch-data", func(c *touka.Context) {
+    // 使用 Context 携带的 httpc 客户端
+    resp, err := c.GetHTTPC().Get("https://api.github.com/users/WJQSERVER-STUDIO", httpc.WithTimeout(5*time.Second))
+    if err != nil {
+        c.ErrorUseHandle(http.StatusInternalServerError, err)
+        return
+    }
+    defer resp.Body.Close()
+
+    // 将外部响应直接流式传输给客户端
+    c.SetHeader("Content-Type", resp.Header.Get("Content-Type"))
+    c.WriteStream(resp.Body)
+})
+```
+
+---
+
+### 4. 错误处理：统一且强大
+
+Touka 的一个标志性特性是其统一的错误处理机制。
+
+#### 4.1. 自定义全局错误处理器
+
+```go
+func main() {
+    r := touka.New()
+
+    // 设置一个自定义的全局错误处理器
+    r.SetErrorHandler(func(c *touka.Context, code int, err error) {
+        // 检查是否是客户端断开连接
+        if errors.Is(err, context.Canceled) {
+            return // 不做任何事
+        }
+
+        // 记录详细错误
+        c.GetLogger().Errorf("捕获到错误: code=%d, err=%v, path=%s", code, err, c.Request.URL.Path)
+
+        // 根据错误码返回不同的响应
+        switch code {
+        case http.StatusNotFound:
+            c.JSON(code, touka.H{"error": "您要找的页面去火星了"})
+        case http.StatusMethodNotAllowed:
+            c.JSON(code, touka.H{"error": "不支持的请求方法"})
+        default:
+            c.JSON(code, touka.H{"error": "服务器内部错误"})
+        }
+    })
+
+    // 这个路由不存在，会触发 404
+    // r.GET("/this-route-does-not-exist", ...)
+
+    // 静态文件服务，如果文件不存在，也会被上面的 ErrorHandler 捕获
+    r.StaticDir("/files", "./non-existent-dir")
+
+    r.Run(":8080")
+}
+```
+
+#### 4.2. `errorCapturingResponseWriter` 的魔力
+
+Touka 如何捕获 `http.FileServer` 的错误？答案是 `errorCapturingResponseWriter`。
+
+当您使用 `r.StaticDir` 或类似方法时，Touka 不会直接将 `http.FileServer` 作为处理器。相反，它会用一个自定义的 `ResponseWriter` 实现（即 `ecw`）来包装原始的 `ResponseWriter`，然后才调用 `http.FileServer.ServeHTTP`。
+
+这个包装器会：
+1.  **拦截 `WriteHeader(statusCode)` 调用：** 当 `http.FileServer` 内部决定要写入一个例如 `404 Not Found` 的状态码时，`ecw` 会捕获这个 `statusCode`。
+2.  **判断是否为错误：** 如果 `statusCode >= 400`，`ecw` 会将此视为一个错误信号。
+3.  **阻止原始响应：** `ecw` 会阻止 `http.FileServer` 继续向客户端写入任何内容（包括响应体）。
+4.  **调用全局 `ErrorHandler`：** 最后，`ecw` 会调用您通过 `r.SetErrorHandler` 设置的全局错误处理器，并将捕获到的 `statusCode` 和一个通用错误传递给它。
+
+这个机制确保了无论是动态 API 的错误还是静态文件服务的错误，都能被统一、优雅地处理，从而提供一致的用户体验。
+
+---
+
+### 5. 静态文件服务与嵌入式资源
+
+#### 5.1. 服务本地文件
+
+```go
+// 将 URL /assets/ 映射到本地的 ./static 目录
+r.StaticDir("/assets", "./static")
+
+// 将 URL /favicon.ico 映射到本地的 ./static/img/favicon.ico 文件
+r.StaticFile("/favicon.ico", "./static/img/favicon.ico")
+```
+
+#### 5.2. 服务嵌入式资源 (Go 1.16+)
+
+使用 `go:embed` 可以将静态资源直接编译到二进制文件中，实现真正的单体应用部署。
+
+```go
+// main.go
+package main
+
+import (
+    "embed"
+    "io/fs"
+    "net/http"
+    "github.com/infinite-iroha/touka"
+)
+
+//go:embed frontend/dist
+var embeddedFS embed.FS
+
+func main() {
+    r := touka.New()
+
+    // 创建一个子文件系统，根目录为 embeddedFS 中的 frontend/dist
+    subFS, err := fs.Sub(embeddedFS, "frontend/dist")
+    if err != nil {
+        panic(err)
+    }
+
+    // 使用 StaticFS 来服务这个嵌入式文件系统
+    // 所有对 / 的访问都会映射到嵌入的 frontend/dist 目录
+    r.StaticFS("/", http.FS(subFS))
+
+    r.Run(":8080")
+}
+```
+
+---
+
+### 6. 与标准库的无缝集成
+
+Touka 提供了适配器，可以轻松使用任何实现了标准 `http.Handler` 或 `http.HandlerFunc` 接口的组件。
+
+```go
+import "net/http/pprof"
+
+// 适配一个标准的 http.HandlerFunc
+r.GET("/legacy-handler", touka.AdapterStdFunc(func(w http.ResponseWriter, r *http.Request) {
+    w.Write([]byte("这是一个标准的 http.HandlerFunc"))
+}))
+
+// 适配一个标准的 http.Handler，例如 pprof
+debugGroup := r.Group("/debug/pprof")
+{
+    debugGroup.GET("/", touka.AdapterStdFunc(pprof.Index))
+    debugGroup.GET("/cmdline", touka.AdapterStdFunc(pprof.Cmdline))
+    debugGroup.GET("/profile", touka.AdapterStdFunc(pprof.Profile))
+    // ... 其他 pprof 路由
+}
+```
+
+这使得您可以方便地利用 Go 生态中大量现有的、遵循标准接口的第三方中间件和工具。