add conf documents (#1869)

* add conf documents

* chore: use {} instead of () for environment variables

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.

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())
+```
+