diff --git a/README.md b/README.md index 83a6ee4..0608eb9 100644 --- a/README.md +++ b/README.md @@ -1,173 +1,6 @@ -# Touka(灯花)框架 +# 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）压力，尤其在高并发场景下，有助于提供更平滑和可预测的性能表现。 - -### 快速上手 - -```go -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 -} -``` - -## 中间件支持 +## 中间件 ### 内置 @@ -191,19 +24,6 @@ Touka Gzip `r.Use(Gzip(-1))` [带宽限制](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 参考 -* **贡献：** 我们欢迎任何形式的贡献，无论是错误报告、功能建议还是代码提交。请遵循项目的贡献指南 - -## 相关项目 - -[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 - ## 许可证 本项目在v0阶段使用WJQSERVER STUDIO LICENSE许可证, 后续进行调整 diff --git a/go.mod b/go.mod index dbeb743..58e1acc 100644 --- a/go.mod +++ b/go.mod @@ -1,6 +1,6 @@ module github.com/infinite-iroha/touka -go 1.24.4 +go 1.24.3 require ( github.com/WJQSERVER-STUDIO/go-utils/copyb v0.0.4