feat:完善文档目录

README.md

@@ -30,30 +30,3 @@ NexFrame是一款基于 Go 语言免费开源的，快速、简单的企业级
 在发布本资料时，请严格遵守开放出版许可协议 1.0 或其后续版本的规定。未经版权所有者的明确书面授权，不得擅自发布本文档的修改版本。此外，除非事先获得版权所有者的特别许可，否则禁止将此作品或其衍生作品以标准纸质书籍的形式进行发行。
 
 若您有意再发行或再版本手册的全部或部分内容，无论是否经过修改，或有任何相关疑问，请及时与版权所有者联系，邮箱地址为：[email protected]。我们期待与您共同维护和尊重知识产权，确保作品的合法合规传播。
-
-## web服务
-
-```go
-package main
-
-import (
-	"fmt"
-	"github.com/sagoo-cloud/nexframe"
-	"net/http"
-)
-
-func main() {
-	server := nexframe.Server()
-	// 注册控制器
-	err := server.BindHandlerFunc("/", func(w http.ResponseWriter, r *http.Request) {
-		fmt.Println(w, "Hello, world!")
-	})
-	if err != nil {
-		return
-	}
-	server.SetPort(":8080")
-	server.Run()
-}
-
-```
-

SUMMARY.md

@@ -3,11 +3,30 @@
 
 <!--一级目录-->
 * [介绍](README.md)
-* [数据结构](/dataStructure/README.md)
-<!--二级目录-->
-	  * [二叉树](/dataStructure/binaryTree.md)
-* [Maven](/maven/README.md)
-    * [搭建maven仓库](/maven/nexus.md)
+* [准备工作](install.md)
+* [快速开始](start.md)
+* [服务组件](servers.md)
+  * [消息队列服务](/queue.md)
+  * [定时器服务](/timers.md)
+  * [mqtt订阅服务](/mqttc.md)
+  * [websocket服务](/websockets.md)
+
+* [数据处理](/database.md)
+    * [数据库组件](/gorm.md)
+    * [redisdb组件](/redisdb.md)
+    * [数据聚合器组件](/aggregator.md)
+* [实用工具](/tools.md)
+  * [数据校验](/valid.md)
+  * [http客户端](/httputil.md)
+  * [随机数](/rand.md)
+  * [速率限制](/retelimit.md)
+* [配置管理](/config.md)
+* [日志管理](/zlog.md)
+* [i18n国际化](/i18n.md)
+* [协程池管理](/gpool.md)
+* [文件管理](/file.md)
+  * [文件上传/水印](/file.md)  
+  * [文件操作工具](/fileop.md)  
 <!--分割线-->
 ---
 * [关于作者](personalIntroduction.md)

aggregator.md

@@ -0,0 +1,159 @@
+# Aggregator数据聚合器
+
+## 1. 概述
+
+Aggregator模块是一个用于批量处理数据的高性能并发组件。它能够将输入的数据项聚合成批次，然后异步处理这些批次，同时提供了灵活的配置选项和错误处理机制。
+
+## 2. 主要结构
+
+### 2.1 Aggregator
+
+`Aggregator` 是这个模块的核心结构，它包含以下主要字段：
+
+- `option`: 聚合器配置选项
+- `eventQueue`: 事件队列，用于存储待处理的数据项
+- `batchProcessor`: 批处理函数
+- `pool`: 对象池，用于复用批次切片
+- `lingerTimer`: 延迟处理计时器
+- `lastProcessTime`: 上次处理时间
+
+### 2.2 AggregatorOption
+
+`AggregatorOption` 结构体用于配置Aggregator，包括以下字段：
+
+- `BatchSize`: 批处理大小
+- `Workers`: 工作协程数量
+- `ChannelBufferSize`: 通道缓冲区大小
+- `LingerTime`: 延迟处理时间
+- `ErrorHandler`: 错误处理函数
+- `Logger`: 日志记录器
+
+## 3. 初始化和配置
+
+### 3.1 创建新的Aggregator实例
+
+使用 `NewAggregator` 函数创建新的Aggregator实例：
+
+```go
+aggregator, err := database.NewAggregator(batchProcessFunc, optionFuncs...)
+```
+
+### 3.2 配置选项
+
+使用以下函数来设置Aggregator的配置选项：
+
+- `WithBatchSize(size int)`: 设置批处理大小
+- `WithWorkers(workers int)`: 设置工作协程数量
+- `WithChannelBufferSize(size int)`: 设置通道缓冲区大小
+- `WithLingerTime(duration time.Duration)`: 设置延迟处理时间
+- `WithLogger(logger *log.Logger)`: 设置日志记录器
+- `WithErrorHandler(handler ErrorHandlerFunc)`: 设置错误处理函数
+
+示例：
+
+```go
+aggregator, err := database.NewAggregator(
+    batchProcessFunc,
+    database.WithBatchSize(10),
+    database.WithWorkers(4),
+    database.WithLingerTime(time.Second * 30),
+)
+```
+
+## 4. 主要功能
+
+### 4.1 数据入队
+
+#### 4.1.1 非阻塞入队
+
+```go
+success := aggregator.TryEnqueue(item)
+```
+
+#### 4.1.2 阻塞入队
+
+```go
+err := aggregator.Enqueue(item)
+```
+
+#### 4.1.3 带重试的入队
+
+```go
+success := aggregator.EnqueueWithRetry(item, maxRetries, backoff)
+```
+
+### 4.2 启动和停止
+
+#### 4.2.1 启动Aggregator
+
+```go
+aggregator.Start()
+```
+
+#### 4.2.2 停止Aggregator
+
+```go
+aggregator.Stop()
+```
+
+#### 4.2.3 安全停止Aggregator
+
+```go
+aggregator.SafeStop()
+```
+
+## 5. 批处理函数
+
+批处理函数是Aggregator的核心，它定义了如何处理一批数据项：
+
+```go
+type BatchProcessFunc func([]interface{}) error
+```
+
+示例：
+
+```go
+func batchProcessFunc(items []interface{}) error {
+    // 处理一批数据项
+    for _, item := range items {
+        // 处理单个数据项
+    }
+    return nil
+}
+```
+
+## 6. 错误处理
+
+错误处理函数允许自定义如何处理批处理过程中的错误：
+
+```go
+type ErrorHandlerFunc func(err error, items []interface{}, batchProcessFunc BatchProcessFunc, aggregator *Aggregator)
+```
+
+示例：
+
+```go
+func errorHandler(err error, items []interface{}, batchProcessFunc BatchProcessFunc, aggregator *Aggregator) {
+    log.Printf("处理错误: %v", err)
+    // 可以选择重试、跳过或其他处理方式
+}
+```
+
+## 7. 最佳实践
+
+1. 根据实际需求调整批处理大小和工作协程数量，以平衡吞吐量和资源使用。
+2. 使用 `SafeStop()` 来确保所有数据都被处理后再停止Aggregator。
+3. 实现适当的错误处理函数，以便在批处理失败时采取合适的措施。
+4. 使用日志记录器来监控Aggregator的运行状况。
+5. 在高并发场景下，考虑使用 `TryEnqueue()` 或 `EnqueueWithRetry()` 来避免阻塞。
+
+## 8. 注意事项
+
+1. Aggregator 不保证严格的顺序处理，如果需要保持顺序，需要在批处理函数中额外实现。
+2. 在使用 `Stop()` 或 `SafeStop()` 后，不应再尝试向Aggregator中添加新的数据项。
+3. 批处理函数应该是幂等的，因为在某些错误情况下可能会重试处理同一批数据。
+4. 注意设置合适的 `LingerTime`，以平衡实时性和批处理效率。
+
+## 9. 结论
+
+Aggregator模块提供了一个高效的方式来批量处理数据，特别适用于需要高吞吐量的场景。通过合理配置和使用，可以显著提高数据处理的效率和可靠性。在使用过程中，需要根据具体的应用场景和需求来调整各项参数，以达到最佳的性能和资源利用。

config.md

@@ -0,0 +1,2 @@
+# 配置管理
+

database.md

@@ -0,0 +1,3 @@
+# 数据组件
+
+

gorm.md

@@ -0,0 +1,8 @@
+# 数据库操作
+
+nexframe中集成的是GORM，GORM是一个流行的Go语言ORM库，它提供了丰富的数据库操作功能，包括CRUD、关联查询、事务处理等。
+
+在本架构中可以直接使用。
+
+通过全局方法，直接获取到数据库实例。`g.DB`。
+

i18n.md

@@ -0,0 +1,141 @@
+# 国际化（i18n）
+
+## 1. 概述
+
+这个国际化（i18n）支持库提供了一个简单而强大的方式来为Go应用程序添加多语言支持。它支持动态加载翻译、切换语言、添加新的翻译，以及格式化带参数的翻译。
+
+## 2. 主要特性
+
+- 支持多种语言的翻译
+- 动态加载和切换语言
+- 线程安全的操作
+- 支持从文件或字节数组加载翻译
+- 支持添加和更新翻译
+- 支持带参数的翻译格式化
+
+## 3. 初始化
+
+### 3.1 初始化全局i18n实例
+
+使用 `InitGlobal` 函数初始化全局i18n实例：
+
+```go
+err := i18n.InitGlobal("en", "path/to/translations")
+if err != nil {
+    log.Fatalf("初始化i18n失败: %v", err)
+}
+```
+
+参数：
+- 第一个参数是初始语言代码
+- 第二个参数（可选）是翻译文件的自定义目录路径
+
+## 4. 基本用法
+
+### 4.1 翻译文本
+
+使用 `T` 函数翻译文本：
+
+```go
+translatedText := i18n.T("hello_world")
+```
+
+### 4.2 格式化翻译
+
+使用 `FormatTranslation` 函数格式化带参数的翻译：
+
+```go
+formattedText := i18n.FormatTranslation("welcome_message", "Alice")
+```
+
+### 4.3 切换语言
+
+使用 `SetLang` 函数切换当前语言：
+
+```go
+err := i18n.SetLang("fr")
+if err != nil {
+    log.Printf("切换语言失败: %v", err)
+}
+```
+
+### 4.4 获取当前语言
+
+使用 `GetCurrentLang` 函数获取当前语言：
+
+```go
+currentLang := i18n.GetCurrentLang()
+```
+
+## 5. 高级用法
+
+### 5.1 添加新的翻译
+
+使用 `AddTranslation` 函数为当前语言添加或更新翻译：
+
+```go
+err := i18n.AddTranslation("new_key", "New translation")
+if err != nil {
+    log.Printf("添加翻译失败: %v", err)
+}
+```
+
+### 5.2 从字节数组加载翻译
+
+使用 `LoadTranslationsFromBytes` 函数从字节数组加载翻译：
+
+```go
+data := []byte(`{"hello": "Bonjour"}`)
+err := i18n.LoadTranslationsFromBytes("fr", data)
+if err != nil {
+    log.Printf("从字节数组加载翻译失败: %v", err)
+}
+```
+
+## 6. 文件结构
+
+翻译文件应该是JSON格式，每种语言一个文件，文件名应为语言代码加`.json`后缀。例如：
+
+- `en.json`
+- `fr.json`
+- `zh.json`
+
+文件内容示例（en.json）：
+
+```json
+{
+  "hello_world": "Hello, World!",
+  "welcome_message": "Welcome, %s!"
+}
+```
+
+## 7. 线程安全
+
+这个库的所有操作都是线程安全的，可以在并发环境中安全使用。
+
+## 8. 错误处理
+
+所有可能失败的操作都返回一个 `error`。建议在生产环境中妥善处理这些错误。
+
+## 9. 最佳实践
+
+1. 在应用启动时调用 `InitGlobal` 初始化i18n库。
+2. 使用有意义的键来组织你的翻译，例如 `user.greeting` 而不是简单的 `greeting`。
+3. 对于包含变量的翻译，使用 `FormatTranslation` 函数。
+4. 定期备份你的翻译文件，特别是在使用 `AddTranslation` 函数时。
+5. 在开发过程中，可以使用 `AddTranslation` 函数快速添加新的翻译，但在生产环境中，最好通过更新翻译文件来管理翻译。
+
+## 10. 性能考虑
+
+- 翻译会被缓存在内存中，所以重复的翻译查询非常快。
+- 切换语言会触发新的语言文件加载，可能会有轻微的性能影响。
+- 添加新的翻译会触发文件写入操作，在高并发场景下要谨慎使用。
+
+## 11. 局限性
+
+- 目前不支持复数形式的处理。
+- 不支持基于地区的变体（例如 en-US 和 en-GB 的区别）。
+
+## 12. 结论
+
+这个i18n支持库提供了一个简单而有效的方式来为Go应用程序添加国际化支持。通过合理使用这个库，可以轻松地创建多语言应用，提高应用的国际化水平。在使用过程中，如果遇到任何问题或有改进建议，请及时反馈给开发团队。

install.md

@@ -0,0 +1,4 @@
+# 准备工作
+
+nexframe 本程序是基于golang语言编写，推荐使用golang版本高于1.23.0，golang相关信息具体可以访问其官网查询。
+