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

{{ .title }}

-//

Welcome, {{ .user }}!

-``` - -##### 文件和流式响应 - -```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 生态中大量现有的、遵循标准接口的第三方中间件和工具。