package main

FishGoddess · Jun 24, 2020 · b7ab778 · b7ab778
2 parents 6e0685a + db9d352
commit b7ab778
Show file tree

Hide file tree

Showing 40 changed files with 685 additions and 294 deletions.
diff --git a/FUTURE.md b/FUTURE.md
@@ -1,7 +1,29 @@
-## ✒ 未来版本的新特性 (Features in future version)
-
-### v0.2.5
-* 修复配置文件中出现转义字符导致解析出错的问题
+## ✒ 未来版本的新特性 (Features in future versions)
+
+### v0.2.9
+* 尝试整理包结构，精简 logit 包下的 API
+
+### v0.2.8
+* 加入日志存活天数的特性
+* 加入日志存活个数的特性
+
+### v0.2.7
+* 修复了 DefaultNameGenerator 可能产生重复文件名的 bug
+
+### v0.2.6-alpha
+* 对 writer 包进行重构，改名为 files 包
+* 废弃了原 writer 包的 NewFile 方法，并使用同包下的 CreateFileOf 代替
+* 引入 NameGenerator 组件
+* 修改 NewDurationRollingHandler 的参数顺序
+* 修改 NewSizeRollingHandler 的参数顺序
+* ~~引入 RollinHook 组件~~
+    > 取消这个特性是因为，它的代码入侵太严重了，并且会使代码设计变得很复杂，使用体验也会变差。
+    > 为了这样一个扩展特性要去改动核心特性的代码，有些喧宾夺主了，所以最后取消了这个组件。
+
+### v0.2.5-alpha
+* 加入之前被移除的特性 - 可变长参数列表的日志输出支持，主要可以使用格式化字符串进行多参数传递
+* ~~修复配置文件中出现转义字符导致解析出错的问题~~
+    > 取消这个特性是因为，配置文件是用户写的，如果存在转义字符的问题，用户自行做转义会更适合一点。
 
 ### v0.2.4
 * 新增屏蔽某个日志级别的日志处理器

diff --git a/HISTORY.md b/HISTORY.md
@@ -1,4 +1,20 @@
-## ✒ 历史版本的特性介绍 (Features in old version)
+## ✒ 历史版本的特性介绍 (Features in old versions)
+
+### v0.2.7
+> 此版本发布于 2020-06-25
+* 修复了 DefaultNameGenerator 可能产生重复文件名的 bug
+
+### v0.2.6-alpha
+> 此版本发布于 2020-06-24
+* 对 writer 包进行重构，改名为 files 包
+* 废弃了原 writer 包的 NewFile 方法，并使用同包下的 CreateFileOf 代替
+* 引入 NameGenerator 组件
+* 修改 NewDurationRollingHandler 的参数顺序
+* 修改 NewSizeRollingHandler 的参数顺序
+
+### v0.2.5-alpha
+> 此版本发布于 2020-06-08
+* 加入之前被移除的特性 - 可变长参数列表的日志输出支持，主要可以使用格式化字符串进行多参数传递
 
 ### v0.2.4
 > 此版本发布于 2020-05-27

diff --git a/README.en.md b/README.en.md
@@ -30,47 +30,37 @@ _Check [HISTORY.md](./HISTORY.md) and [FUTURE.md](./FUTURE.md) to know about mor
 
 ### 🚀 Installation
 
-The only requirement is the [Golang Programming Language](https://golang.org).
-
-> Go modules
-
 ```bash
 $ go get -u github.com/FishGoddess/logit
 ```
 
-Or edit your project's go.mod file and execute _**go build**_.
+> Or edit your project's go.mod file if you are using Go modules.
 
 ```bash
 module your_project_name
 
 go 1.14
 
 require (
-    github.com/FishGoddess/logit v0.2.4
+    github.com/FishGoddess/logit v0.2.7
 )
 ```
 
-> Go path
-
-```bash
-$ go get -u github.com/FishGoddess/logit
-```
-
 logit has no more external dependencies.
 
 ```go
 package main
 
 import (
-    "math/rand"
-    "strconv"
-    "time"
-    
-    "github.com/FishGoddess/logit"
+	"math/rand"
+	"strconv"
+	"time"
+
+	"github.com/FishGoddess/logit"
 )
 
 func main() {
-    
+
 	// Log messages with four levels.
 	logit.Debug("I am a debug message!")
 	logit.Info("I am an info message!")
@@ -92,6 +82,12 @@ func main() {
 		return "debug rand int: " + strconv.Itoa(r.Intn(100))
 	})
 
+	// Or you can use formatting method like this:
+	logit.Debugf("This is a debug msg with %d params: %s, %s", 2, "msgFormat", "msgParams")
+	logit.Infof("This is a debug msg with %d params: %s, %s", 2, "msgFormat", "msgParams")
+	logit.Warnf("This is a debug msg with %d params: %s, %s", 2, "msgFormat", "msgParams")
+	logit.Errorf("This is a debug msg with %d params: %s, %s", 2, "msgFormat", "msgParams")
+
 	// If a config file "logit.conf" in "./", then logit will load it automatically.
 	// This is more convenience to use config file and logger.
 }
@@ -104,7 +100,7 @@ func main() {
 * [level_and_disable](./_examples/level_and_disable.go)
 * [config_file](./_examples/config_file.go)
 * [handler](./_examples/handler.go)
-* [writer](./_examples/writer.go)
+* [files](./_examples/files.go)
 * [log_to_file](./_examples/log_to_file.go)
 
 _Check more examples in [_examples](./_examples)._
@@ -119,12 +115,12 @@ $ go test -v ./_examples/benchmarks_test.go -bench=. -benchtime=10s
 
 > Benchmark file：[_examples/benchmarks_test.go](./_examples/benchmarks_test.go)
 
-| test case | times ran (large is better) |  ns/op (small is better) | features | extension |
+| test case | times ran (large is better) |  ns/op (small is better) | B/op | allocs/op |
 | -----------|--------|-------------|-------------|-------------|
-| **logit** | **6429907** | **1855 ns/op** | powerful | high |
-| golog | 3361483 | 3589 ns/op | easy | common |
-| zap | 2971119 | 4066 ns/op | complex | normal |
-| logrus | 1553419 | 7869 ns/op | normal | normal |
+| **logit** | **6429907** | **1855 ns/op** | **384 B/op** | **8 allocs/op** |
+| golog | 3361483 | 3589 ns/op | 712 B/op | 24 allocs/op |
+| zap | 2971119 | 4066 ns/op | 448 B/op | 16 allocs/op |
+| logrus | 1553419 | 7869 ns/op | 1633 B/op | 52 allocs/op |
 
 > Environment：I7-6700HQ CPU @ 2.6 GHZ, 16 GB RAM
 
@@ -143,6 +139,14 @@ $ go test -v ./_examples/benchmarks_test.go -bench=. -benchtime=10s
 **reduce the times of time format. However, is it worth to replace time format operation with concurrent competition?**
 **The answer is no, so we cancel this mechanism in v0.1.1-alpha and higher versions.**
 
+**4. You should know that some APIs like Debugf can't reach high performance as the same as others because of reflection,**
+**however, their performances are not as bad as we think:**
+
+| test case | times ran (large is better) |  ns/op (small is better) | B/op | allocs/op |
+| -----------|--------|-------------|-------------|-------------|
+| logit | 6429907 | 1855 ns/op | 384 B/op | 8 allocs/op |
+| **logit-reflection** | **5288931** | **2334 ns/op** | **424 B/op** | **12 allocs/op** |
+
 ### 👥 Contributing
 
 If you find that something is not working as expected please open an _**issue**_.

diff --git a/README.md b/README.md
@@ -31,47 +31,37 @@ _历史版本的特性请查看 [HISTORY.md](./HISTORY.md)。未来版本的新
 
 ### 🚀 安装方式
 
-唯一需要的依赖就是 [Golang 运行环境](https://golang.org).
-
-> Go modules
-
 ```bash
 $ go get -u github.com/FishGoddess/logit
 ```
 
-您也可以直接编辑 go.mod 文件，然后执行 _**go build**_。
+> 如果是 Go modules 的项目，您还可以直接编辑 go.mod 文件。
 
 ```bash
 module your_project_name
 
 go 1.14
 
 require (
-    github.com/FishGoddess/logit v0.2.4
+    github.com/FishGoddess/logit v0.2.7
 )
 ```
 
-> Go path
-
-```bash
-$ go get -u github.com/FishGoddess/logit
-```
-
 logit 没有任何其他额外的依赖，纯使用 [Golang 标准库](https://golang.org) 完成。
 
 ```go
 package main
 
 import (
-    "math/rand"
-    "strconv"
-    "time"
-    
-    "github.com/FishGoddess/logit"
+	"math/rand"
+	"strconv"
+	"time"
+
+	"github.com/FishGoddess/logit"
 )
 
 func main() {
-    
+
 	// Log messages with four levels.
 	logit.Debug("I am a debug message!")
 	logit.Info("I am an info message!")
@@ -93,6 +83,12 @@ func main() {
 		return "debug rand int: " + strconv.Itoa(r.Intn(100))
 	})
 
+	// Or you can use formatting method like this:
+	logit.Debugf("This is a debug msg with %d params: %s, %s", 2, "msgFormat", "msgParams")
+	logit.Infof("This is a debug msg with %d params: %s, %s", 2, "msgFormat", "msgParams")
+	logit.Warnf("This is a debug msg with %d params: %s, %s", 2, "msgFormat", "msgParams")
+	logit.Errorf("This is a debug msg with %d params: %s, %s", 2, "msgFormat", "msgParams")
+
 	// If a config file "logit.conf" in "./", then logit will load it automatically.
 	// This is more convenience to use config file and logger.
 }
@@ -105,7 +101,7 @@ func main() {
 * [level_and_disable](./_examples/level_and_disable.go)
 * [config_file](./_examples/config_file.go)
 * [handler](./_examples/handler.go)
-* [writer](./_examples/writer.go)
+* [files](./_examples/files.go)
 * [log_to_file](./_examples/log_to_file.go)
 
 _更多使用案例请查看 [_examples](./_examples) 目录。_
@@ -120,12 +116,12 @@ $ go test -v ./_examples/benchmarks_test.go -bench=. -benchtime=10s
 
 > 测试文件：[_examples/benchmarks_test.go](./_examples/benchmarks_test.go)
 
-| 测试 | 单位时间内运行次数 (越大越好) |  每个操作消耗时间 (越小越好) | 功能性 | 扩展性 |
+| 测试 | 单位时间内运行次数 (越大越好) |  每个操作消耗时间 (越小越好) | B/op (越小越好) | allocs/op (越小越好) |
 | -----------|--------|-------------|-------------|-------------|
-| **logit** | **6429907** | **1855 ns/op** | 强大 | 高 |
-| golog | 3361483 | 3589 ns/op | 简单 | 一般 |
-| zap | 2971119 | 4066 ns/op | 复杂 | 正常 |
-| logrus | 1553419 | 7869 ns/op | 正常 | 正常 |
+| **logit** | **6429907** | **1855 ns/op** | **384 B/op** | **8 allocs/op** |
+| golog | 3361483 | 3589 ns/op | 712 B/op | 24 allocs/op |
+| zap | 2971119 | 4066 ns/op | 448 B/op | 16 allocs/op |
+| logrus | 1553419 | 7869 ns/op | 1633 B/op | 52 allocs/op |
 
 > 测试环境：I7-6700HQ CPU @ 2.6 GHZ，16 GB RAM
 
@@ -144,6 +140,13 @@ $ go test -v ./_examples/benchmarks_test.go -bench=. -benchtime=10s
 **目前存在一个疑惑就是使用并发竞争去换取时间格式化的性能消耗究竟值不值得？**
 **答案是不值得，我们在 v0.1.1-alpha 及更高版本中取消了这个时间缓存机制。**
 
+**4. 值得注意的是，Debugf 一类带格式化的 API 性能达不到这个水平，因为还是使用了反射技术，但是性能依旧是不差的：**
+
+| 测试 | 单位时间内运行次数 (越大越好) |  每个操作消耗时间 (越小越好) | B/op (越小越好) | allocs/op (越小越好) |
+| -----------|--------|-------------|-------------|-------------|
+| logit | 6429907 | 1855 ns/op | 384 B/op | 8 allocs/op |
+| **logit-使用反射技术** | **5288931** | **2334 ns/op** | **424 B/op** | **12 allocs/op** |
+
 ### 👥 贡献者
 
 如果您觉得 logit 缺少您需要的功能，请不要犹豫，马上参与进来，发起一个 _**issue**_。

diff --git a/_examples/basic.go b/_examples/basic.go
@@ -13,7 +13,7 @@
 // limitations under the License.
 //
 // Author: FishGoddess
-// Email: fishinlove@163.com
+// Email: fishgoddess@qq.com
 // Created at 2020/02/29 21:59:13
 package main
 
@@ -48,6 +48,12 @@ func main() {
 		return "debug rand int: " + strconv.Itoa(r.Intn(100))
 	})
 
+	// Or you can use formatting method like this:
+	logit.Debugf("This is a debug msg with %d params: %s, %s", 2, "msgFormat", "msgParams")
+	logit.Infof("This is a debug msg with %d params: %s, %s", 2, "msgFormat", "msgParams")
+	logit.Warnf("This is a debug msg with %d params: %s, %s", 2, "msgFormat", "msgParams")
+	logit.Errorf("This is a debug msg with %d params: %s, %s", 2, "msgFormat", "msgParams")
+
 	// If a config file "logit.conf" in "./", then logit will load it automatically.
 	// This is more convenience to use config file and logger.
 }
diff --git a/_examples/benchmarks_test.go b/_examples/benchmarks_test.go
@@ -13,7 +13,7 @@
 // limitations under the License.
 //
 // Author: FishGoddess
-// Email: fishinlove@163.com
+// Email: fishgoddess@qq.com
 // Created at 2020/03/02 20:51:29
 
 package main
@@ -23,7 +23,7 @@ import (
 	//"time"
 
 	"github.com/FishGoddess/logit"
-	//"github.com/FishGoddess/logit/writer"
+	//"github.com/FishGoddess/logit/files"
 	//"github.com/kataras/golog"
 	//"github.com/sirupsen/logrus"
 	//"go.uber.org/zap"
@@ -172,7 +172,7 @@ func BenchmarkLogitLogger(b *testing.B) {
 //// 测试 logit 文件日志记录器的速度
 //func BenchmarkLogitFile(b *testing.B) {
 //
-//    file, _ := writer.NewFile("D:/BenchmarkLogitFile.log")
+//    file, _ := files.CreateFileOf("D:/BenchmarkLogitFile.log")
 //    logger := logit.NewLogger(logit.DebugLevel, logit.NewStandardHandler(file, logit.TextEncoder(), timeFormat))
 //
 //    // 测试用的日志任务
@@ -195,7 +195,7 @@ func BenchmarkLogitLogger(b *testing.B) {
 //func BenchmarkGologFile(b *testing.B) {
 //
 //    logger := golog.New()
-//    file, _ := writer.NewFile("D:/BenchmarkGologFile.log")
+//    file, _ := files.CreateFileOf("D:/BenchmarkGologFile.log")
 //    logger.SetOutput(file)
 //    logger.SetLevel("debug")
 //    logger.SetTimeFormat(timeFormat)
@@ -226,7 +226,7 @@ func BenchmarkLogitLogger(b *testing.B) {
 //        enc.AppendString(t.Format(timeFormat))
 //    }
 //    encoder := zapcore.NewConsoleEncoder(config)
-//    file, _ := writer.NewFile("D:/BenchmarkZapFile.log")
+//    file, _ := files.CreateFileOf("D:/BenchmarkZapFile.log")
 //    writeSyncer := zapcore.AddSync(file)
 //    core := zapcore.NewCore(encoder, writeSyncer, zapcore.DebugLevel)
 //    logger := zap.New(core)
@@ -253,7 +253,7 @@ func BenchmarkLogitLogger(b *testing.B) {
 //func BenchmarkLogrusFile(b *testing.B) {
 //
 //    logger := logrus.New()
-//    file, _ := writer.NewFile("D:/BenchmarkLogrusFile.log")
+//    file, _ := files.CreateFileOf("D:/BenchmarkLogrusFile.log")
 //    logger.SetOutput(file)
 //    logger.SetLevel(logrus.DebugLevel)
 //    logger.SetFormatter(&logrus.TextFormatter{

diff --git a/_examples/config/logit-config-template.conf b/_examples/config/logit-config-template.conf
@@ -1,4 +1,4 @@
-# logit 配置文件的模板 v0.2.4
+# logit 配置文件的模板 v0.2.7
 # 注意：以 # 开头的是注释，不参与配置文件的解析，注释必须是单独的一行，不能写在属性的后面
 # 语法是基于 Json 并作了一些改动使其更适合做配置文件，所以要注意双引号和逗号这些格式
 # 下面所有涉及目录路径的都使用 / 或者 \\ 而不能是 \，否则会造成配置解析出错，这意味着特殊字符需要自行转义
@@ -58,15 +58,15 @@
     # duration 日志处理器
     # 下面是该日志处理器支持的所有参数
     "duration": {
+        # 日志存储的文件夹
+        # 因为会有很多的日志文件需要存储，所以这里配置的是文件夹，如果不配置的话，默认是 ./
+        "directory": "D:/",
+
         # 滚动阈值，时间间隔，单位是秒
         # 假设 10:00:00 创建了日志文件，limit 配置的是 60，则当时间为 10:01:00 的时候，就会滚动到新的日志文件
         # 如果不配置的话，默认是一天
         "limit": 60,
 
-        # 日志存储的文件夹
-        # 因为会有很多的日志文件需要存储，所以这里配置的是文件夹，如果不配置的话，默认是 ./
-        "directory": "D:/",
-
         # 日志编码器，可选值有 text，json
         # text: 使用普通文本形式编码日志，通常是 `[info] [2020-04-24 13:14:15] xxx` 这样的形式
         # json: 使用 Json 形式编码日志，通常是 `{"level":"info", "time":"2020-04-24 13:14:15", "msg":"xxx"}` 这样的形式
@@ -82,15 +82,15 @@
     # size 日志处理器
     # 下面是该日志处理器支持的所有参数
     "size": {
+        # 日志存储的文件夹
+        # 因为会有很多的日志文件需要存储，所以这里配置的是文件夹，如果不配置的话，默认是 ./
+        "directory": "D:/",
+
         # 滚动阈值，最大日志文件大小，单位是 MB
         # 假设 limit 配置的是 16，则当日志文件大小为 16 MB 的时候，就会滚动到新的日志文件
         # 如果不配置的话，默认是 64 MB
         "limit": 16,
 
-        # 日志存储的文件夹
-        # 因为会有很多的日志文件需要存储，所以这里配置的是文件夹，如果不配置的话，默认是 ./
-        "directory": "D:/",
-
         # 日志编码器，可选值有 text，json
         # text: 使用普通文本形式编码日志，通常是 `[info] [2020-04-24 13:14:15] xxx` 这样的形式
         # json: 使用 Json 形式编码日志，通常是 `{"level":"info", "time":"2020-04-24 13:14:15", "msg":"xxx"}` 这样的形式