Bump to version 4.4.0 (#136)

CHANGELOG.md

@@ -1,6 +1,17 @@
 # Change Log
 All notable changes to QingStor SDK for Go will be documented in this file.
 
+## [v4.4.0] - 2021-08-27
+
+### Changed
+
+- logger: Replace logger with zap.Logger (#135)
+- metadata: ToLower when receive and send (#133)
+
+### Fixed
+
+- docs: Fix typo about LoadConfigFromFilePath (#131)
+
 ## [v4.3.0] - 2021-01-29
 
 ### Added
@@ -289,6 +300,7 @@ All notable changes to QingStor SDK for Go will be documented in this file.
 
 - QingStor SDK for the Go programming language.
 
+[v4.4.0]: https://github.com/qingstor/qingstor-sdk-go/compare/v4.3.0...v4.4.0
 [v4.3.0]: https://github.com/qingstor/qingstor-sdk-go/compare/v4.2.0...v4.3.0
 [v4.2.0]: https://github.com/qingstor/qingstor-sdk-go/compare/v4.1.0...v4.2.0
 [v4.1.0]: https://github.com/qingstor/qingstor-sdk-go/compare/v4.0.0...v4.1.0

README.md

@@ -23,6 +23,7 @@ Now you are ready to code. You can read the detailed guides in the list below to
 - [Configuration](./docs/config.md)
 - [Service Initialization](./docs/service.md)
 - [Code Examples](./docs/examples.md)
+- [Custom Logger](./docs/logger.md)
 
 Checkout our [releases](https://github.com/qingstor/qingstor-sdk-go/releases) and [change log](./CHANGELOG.md) for information about the latest features, bug fixes and new ideas.
 

README_zh-CN.md

@@ -23,6 +23,7 @@ Go 语言版本的 QingStor 官方 SDK.
 - [配置](./docs/config_zh-CN.md)
 - [初始化服务](./docs/service_zh-CN.md)
 - [代码示例](./docs/examples_zh-CN.md)
+- [自定义日志组件](./docs/logger_zh-CN.md)
 
 查看我们的 [发布历史](https://github.com/qingstor/qingstor-sdk-go/releases) 和 [更改日志](./CHANGELOG.md) 获取最新的特性和 bug 修复。
 

docs/config.md

@@ -23,9 +23,6 @@ endpoint: 'https://qingstor.com:443'
 
 enable_virtual_host_style: false # default false.
 enable_dual_stack: false # default false.
-
-# Valid log levels are "debug", "info", "warn", "error", and "fatal".
-log_level: 'warn'
 ```
 
 We also support setting the following environment variables:

docs/config_zh-CN.md

@@ -23,9 +23,6 @@ endpoint: 'https://qingstor.com:443'
 
 enable_virtual_host_style: false # default false.
 enable_dual_stack: false # default false.
-
-# Valid log levels are "debug", "info", "warn", "error", and "fatal".
-log_level: 'warn'
 ```
 
 我们也支持设置如下环境变量：

docs/logger.md

@@ -0,0 +1,54 @@
+# Custom Logger
+
+From v4.4.0, we introduced `zap.Logger` which is a widely used, production
+ready [logger component](https://github.com/uber-go/zap). The `log_level` field in config is deprecated, you can
+initialize your own logger and pass it by `context`.
+
+## Package log
+
+The logger helper methods are defined in `log` package, which contains
+`func ContextWithLogger(ctx context.Context, l *zap.Logger) context.Context` and
+`func FromContext(ctx context.Context) *zap.Logger` two methods.
+
+You can conduct your own `*zap.Logger` by methods such as `zap.New`, `zap.NewDevelopment`, `zap.NewProducton` and so on,
+and set it into `context` by `ContextWithLogger`, then you can pass this `context` into API function
+like `PutObjectWithContext`.
+
+## Default logger
+
+Usually, we get logger from `context` by method `FromContext`. If `context` is `nil` or no `logger` is set before, 
+a default logger is returned, which is initialized by `zap.NewProduction` and `LevelWarn` is set.
+[Here](https://github.com/qingstor/qingstor-sdk-go/blob/master/log/context.go#L39) is the detail.
+
+## Use custom logger
+
+You can also customize you own logger depend on your scenario. Then conduct the `context` by `ContextWithLogger`.
+
+Here are some examples:
+
+```go
+package main
+
+import (
+	"context"
+
+	"github.com/qingstor/qingstor-sdk-go/v4/log"
+	"go.uber.org/zap"
+)
+
+func main() {
+	// ignore the process of conducting bucketService
+
+	// no context passed, will use default logger
+	bucketService.PutObject(objectKey, input)
+
+	options := []zap.Option{
+		// customize your own options
+	}
+	logger, _ := zap.NewDevelopment(options...)
+	ctx := log.ContextWithLogger(context.Background(), logger)
+
+	// logger set above will be used
+	bucketService.PutObjectWithContext(ctx, objectKey, input)
+}
+```

docs/logger_zh-CN.md

@@ -0,0 +1,53 @@
+# 自定义日志组件
+
+从 v4.4.0 版本开始，我们引入了 `zap.Logger` 组件，这是一个被广泛应用于生产环境的[日志组件](https://github.com/uber-go/zap). 
+并且我们废弃了配置文件中的 `log_level` 字段，你可以初始化自定义的 logger，并且通过 `context` 来进行传递。
+
+## log 包
+
+SDK 中，日志组件的帮助方法被定义在了 `log` 包中，这个包主要包含了以下两个方法：
+`func ContextWithLogger(ctx context.Context, l *zap.Logger) context.Context` 和
+`func FromContext(ctx context.Context) *zap.Logger`.
+
+你可以构建自己的 `*zap.Logger` 实例，通过 `zap.New`, `zap.NewDevelopment`, `zap.NewProducton` 等方法，
+然后将该实例设置在 `context` 中，通过 `ContextWithLogger` 方法，之后你可以将得到的 `context` 作为参数传至 API 请求方法中，例如 
+`PutObjectWithContext`.
+
+## 默认的 logger
+
+通常情况下，我们会通过 `FromContext` 方法从 `context` 中获取 `*zap.Logger` 实例。但如果 `context` 为 `nil`，或者之前没有实例被设置，
+我们会返回一个默认的实例，该实例是通过 `zap.NewProduction` 方法初始化的，并被设置为 `LevelWarn` 等级。
+点击 [这里](https://github.com/qingstor/qingstor-sdk-go/blob/master/log/context.go#L39) 可以看到具体的函数逻辑。
+
+## 使用自定义的 logger
+
+你也可以根据实际场景需要，自定义一个 `*zap.Logger` 实例，并通过 `ContextWithLogger` 来构建 `context`. 
+
+示例代码如下:
+
+```go
+package main
+
+import (
+	"context"
+
+	"github.com/qingstor/qingstor-sdk-go/v4/log"
+	"go.uber.org/zap"
+)
+
+func main() {
+	// 忽略构造 bucketService 的过程
+
+	// 没有 context 参数，将会使用默认的 logger
+	bucketService.PutObject(objectKey, input) 
+
+	options := []zap.Option{
+		// 自定义你的 logger 选项
+	}
+	logger, _ := zap.NewDevelopment(options...)
+	ctx := log.ContextWithLogger(context.Background(), logger)
+
+	// 上边构造的 logger 将会被使用
+	bucketService.PutObjectWithContext(ctx, objectKey, input) 
+}
+```