From 469e62067c5c13a56eecf4c6cb9fc5a7d9109a95 Mon Sep 17 00:00:00 2001
From: Kevin Wan <wanjunfeng@gmail.com>
Date: Fri, 6 May 2022 11:05:06 +0800
Subject: [PATCH] add conf documents (#1869)

* add conf documents

* chore: use {} instead of () for environment variables
---
 core/conf/config.go | 31 ++++++++++++++++++++++++-------
 core/conf/readme.md | 45 +++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 69 insertions(+), 7 deletions(-)
 create mode 100644 core/conf/readme.md

diff --git a/core/conf/config.go b/core/conf/config.go
index d39739b9..a38c3009 100644
--- a/core/conf/config.go
+++ b/core/conf/config.go
@@ -11,13 +11,13 @@ import (
 )
 
 var loaders = map[string]func([]byte, interface{}) error{
-	".json": LoadConfigFromJsonBytes,
-	".yaml": LoadConfigFromYamlBytes,
-	".yml":  LoadConfigFromYamlBytes,
+	".json": LoadFromJsonBytes,
+	".yaml": LoadFromYamlBytes,
+	".yml":  LoadFromYamlBytes,
 }
 
-// LoadConfig loads config into v from file, .json, .yaml and .yml are acceptable.
-func LoadConfig(file string, v interface{}, opts ...Option) error {
+// Load loads config into v from file, .json, .yaml and .yml are acceptable.
+func Load(file string, v interface{}, opts ...Option) error {
 	content, err := ioutil.ReadFile(file)
 	if err != nil {
 		return err
@@ -40,14 +40,31 @@ func LoadConfig(file string, v interface{}, opts ...Option) error {
 	return loader(content, v)
 }
 
+// LoadConfig loads config into v from file, .json, .yaml and .yml are acceptable.
+// Deprecated: use Load instead.
+func LoadConfig(file string, v interface{}, opts ...Option) error {
+	return Load(file, v, opts...)
+}
+
+// LoadFromJsonBytes loads config into v from content json bytes.
+func LoadFromJsonBytes(content []byte, v interface{}) error {
+	return mapping.UnmarshalJsonBytes(content, v)
+}
+
 // LoadConfigFromJsonBytes loads config into v from content json bytes.
+// Deprecated: use LoadFromJsonBytes instead.
 func LoadConfigFromJsonBytes(content []byte, v interface{}) error {
-	return mapping.UnmarshalJsonBytes(content, v)
+	return LoadFromJsonBytes(content, v)
+}
+
+func LoadFromYamlBytes(content []byte, v interface{}) error {
+	return mapping.UnmarshalYamlBytes(content, v)
 }
 
 // LoadConfigFromYamlBytes loads config into v from content yaml bytes.
+// Deprecated: use LoadFromYamlBytes instead.
 func LoadConfigFromYamlBytes(content []byte, v interface{}) error {
-	return mapping.UnmarshalYamlBytes(content, v)
+	return LoadFromYamlBytes(content, v)
 }
 
 // MustLoad loads config into v from path, exits on error.
diff --git a/core/conf/readme.md b/core/conf/readme.md
new file mode 100644
index 00000000..d5143c55
--- /dev/null
+++ b/core/conf/readme.md
@@ -0,0 +1,45 @@
+## How to use
+
+1. Define a config structure, like below:
+
+```go
+RestfulConf struct {
+	Host         string        `json:",default=0.0.0.0"`
+	Port         int
+	LogMode      string        `json:",options=[file,console]"
+	Verbose      bool          `json:",optional"`
+	MaxConns     int           `json:",default=10000"`
+	MaxBytes     int64         `json:",default=1048576"`
+	Timeout      time.Duration `json:",default=3s"`
+	CpuThreshold int64         `json:",default=900,range=[0:1000]"`
+}
+```
+
+2. Write the yaml or json config file:
+
+```yaml
+# most fields are optional or have default values
+Port: 8080
+LogMode: console
+# you can use env settings
+MaxBytes: ${MAX_BYTES}
+```
+
+3. Load the config from a file:
+
+```go
+// exit on error
+var config RestfulConf
+conf.MustLoad(configFile, &config)
+
+// or handle the error on your own
+var config RestfulConf
+if err := conf.Load(configFile, &config); err != nil {
+  log.Fatal(err)
+}
+
+// enable reading from environments
+var config RestfulConf
+conf.MustLoad(configFile, &config, conf.UseEnv())
+```
+