Update documents (#48)

* docs: update * style: update * docs: update * docs: update * docs: update
mgtv-tech · Dec 18, 2024 · 7c4b6bd · 7c4b6bd
1 parent 5e6988b
commit 7c4b6bd
Show file tree

Hide file tree

Showing 8 changed files with 213 additions and 203 deletions.
diff --git a/cacheopt.go b/cacheopt.go
@@ -38,8 +38,6 @@ type (
 		remote                     remote.Remote      // Remote is distributed cache, such as Redis.
 		local                      local.Local        // Local is memory cache, such as FreeCache.
 		codec                      string             // Value encoding and decoding method. Default is "msgpack.Name". You can also customize it.
-		separatorDisabled          bool               // Disable separator for cache key. Default is false. If true, the cache key will not be split into multiple parts.
-		separator                  string             // Separator for cache key. Default is ":".
 		errNotFound                error              // Error to return for cache miss. Used to prevent cache penetration.
 		remoteExpiry               time.Duration      // Remote cache ttl, Default is 1 hour.
 		notFoundExpiry             time.Duration      // Duration for placeholder cache when there is a cache miss. Default is 1 minute.
@@ -53,6 +51,8 @@ type (
 		syncLocal                  bool               // Enable events for syncing local cache (only for "Both" cache type).
 		eventChBufSize             int                // Buffer size for event channel (default: 100).
 		eventHandler               func(event *Event) // Function to handle local cache invalidation events.
+		separatorDisabled          bool               // Disable separator for cache key. Default is false. If true, the cache key will not be split into multiple parts.
+		separator                  string             // Separator for cache key. Default is ":".
 	}
 
 	// Option defines the method to customize an Options.

diff --git a/docs/CN/CacheAPI.md b/docs/CN/CacheAPI.md
@@ -45,7 +45,7 @@ func Close()
 
 ## Set 接口
 
-该接口用于设置缓存。它支持多种选项，例如设置值(`Value`)、过期时间(`TTL`)、回源函数(`Do`)、以及针对 `Remote` 缓存的原子操作。
+该接口用于设置缓存。它支持多种选项，例如设置值(`Value`)、远程过期时间(`TTL`)、回源函数(`Do`)、以及针对 `Remote` 缓存的原子操作。
 
 函数签名：
 ```go
@@ -57,7 +57,7 @@ func Set(ctx context.Context, key string, opts ...ItemOption) error
 - `key`: `string`，缓存键。
 - `opts`: `...ItemOption`，可变参数列表，用于配置缓存项的各种选项。 支持以下选项：
     - `Value(value any)`: 设置缓存值。
-    - `TTL(duration time.Duration)`: 设置缓存项的过期时间。
+    - `TTL(duration time.Duration)`: 设置远程缓存项的过期时间。（本地缓存过期时间在构建 Local 缓存实例的时候统一设置）
     - `Do(fn func(context.Context) (any, error))`: 给定的回源函数 `fn` 来获取值，优先级高于 `Value`。
     - `SetNX(flag bool)`: 仅当键不存在时才设置缓存项。 适用于远程缓存，防止覆盖已存在的值。
     - `SetXX(flag bool)`: 仅当键存在时才设置缓存项。适用于远程缓存，确保只更新已存在的值。
@@ -99,7 +99,8 @@ if err != nil {
 
 ## Once 接口
 
-该接口从缓存中获取给定 `Key` 的值，或者执行 `Do` 函数，然后将结果缓存并返回。它确保对于给定的 `Key`，同一时间只有一个执行在进行中。如果出现重复请求，重复的调用者将等待原始请求完成，并接收相同的结果。
+该接口从缓存中获取给定 `Key` 的值。若未命中缓存，则执行 `Do` 函数，然后将结果缓存并返回。它确保对于给定的 `Key`，同一时间只有一个执行在进行中。如果出现重复请求，重复的调用者将等待原始请求完成，并接收相同的结果。
+
 通过设置 `Refresh(true)` 可开启缓存自动刷新。
 
 `Once` 接口：分布式-防缓存击穿利器 - `singleflight`
@@ -115,7 +116,7 @@ if err != nil {
 ![autoRefresh](/docs/images/autorefresh.png)
 
 > `Once`接口提供了自动刷新缓存的能力，目的是为了防止缓存失效时造成的雪崩效应打爆数据库。对一些key比较少，实时性要求不高，加载开销非常大的缓存场景，
-> 适合使用自动刷新。下面的代码指定每分钟刷新一次，1小时如果没有访问就停止刷新。如果缓存是redis或者多级缓存最后一级是redis，缓存加载行为是全局唯一的，
+> 适合使用自动刷新。下面的代码（示例1）指定每分钟刷新一次，1小时如果没有访问就停止刷新。如果缓存是redis或者多级缓存最后一级是redis，缓存加载行为是全局唯一的，
 > 也就是说不管有多少台服务器，同时只有一个服务器在刷新，目的是为了降低后端的加载负担。
 
 > 关于自动刷新功能的使用场景（“适用于按键数量少、实时性要求低、加载开销非常大的场景”），其中“按键数量少”需要进一步说明。
@@ -133,7 +134,7 @@ func Once(ctx context.Context, key string, opts ...ItemOption) error
 - `key`: `string`，缓存键。
 - `opts`: `...ItemOption`，可变参数列表，用于配置缓存项的各种选项。 支持以下选项：
     - `Value(value any)`: 设置缓存值。
-    - `TTL(duration time.Duration)`: 设置缓存项的过期时间。
+    - `TTL(duration time.Duration)`: 设置远程缓存项的过期时间。（本地缓存过期时间在构建 Local 缓存实例的时候统一设置）
     - `Do(fn func(context.Context) (any, error))`: 给定的回源函数 `fn` 来获取值，优先级高于 `Value`。
     - `SkipLocal(flag bool)`: 是否跳过本地缓存。
     - `Refresh(refresh bool)`: 是否开启缓存自动刷新。配合 Cache 配置参数 `config.refreshDuration` 设置刷新周期。

diff --git a/docs/CN/Config.md b/docs/CN/Config.md
@@ -15,9 +15,7 @@
 | name                       | string               | default              | 缓存名称，用于日志标识和指标报告                                                                                                                                  |
 | remote                     | `remote.Remote` 接口   | nil                  | remote 是分布式缓存，例如 Redis。也可以自定义，实现`remote.Remote`接口即可                                                                                               |
 | local                      | `local.Local` 接口     | nil                  | local 是内存缓存，例如 FreeCache、TinyLFU。也可以自定义，实现`local.Local`接口即可                                                                                       |
-| codec                      | string               | msgpack              | value的编码和解码方法。默认为 "msgpack"。可选：msgpack \| sonic，也可以自定义，实现`encoding.Codec`接口并注册即可                                                                  |
-| separatorDisabled          | bool                 | false                | 禁用缓存键的分隔符。默认为false。如果为true，则缓存键不会使用分隔符。目前主要用于泛型接口的缓存key和ID拼接                                                                                      |
-| separator                  | string               | :                    | 缓存键的分隔符。默认为 ":"。目前主要用于泛型接口的缓存key和ID拼接                                                                                                             |
+| codec                      | string               | msgpack              | value的编码和解码方法。默认为 "msgpack"。可选：`json` \| `msgpack` \| `sonic`，也可以自定义，实现`encoding.Codec`接口并注册即可                                                    | 
 | errNotFound                | error                | nil                  | 缓存未命中时返回的错误，例：`gorm.ErrRecordNotFound`。用于防止缓存穿透（即缓存空对象）                                                                                           |
 | remoteExpiry               | `time.Duration`      | 1小时                  | 远程缓存 TTL，默认为 1 小时                                                                                                                                 |
 | notFoundExpiry             | `time.Duration`      | 1分钟                  | 缓存未命中时占位符缓存的过期时间。默认为 1 分钟                                                                                                                         |
@@ -31,7 +29,8 @@
 | syncLocal                  | bool                 | false                | 【缓存事件广播】启用同步本地缓存的事件（仅适用于 "Both" 缓存类型）                                                                                                             |
 | eventChBufSize             | int                  | 100                  | 【缓存事件广播】事件通道的缓冲区大小（默认为 100）                                                                                                                       |
 | eventHandler               | `func(event *Event)` | nil                  | 【缓存事件广播】处理本地缓存失效事件的函数                                                                                                                             |
-
+| separatorDisabled          | bool                 | false                | 禁用缓存键的分隔符。默认为false。如果为true，则缓存键不会使用分隔符。目前主要用于泛型接口的缓存key和ID拼接                                                                                      |
+| separator                  | string               | :                    | 缓存键的分隔符。默认为 ":"。目前主要用于泛型接口的缓存key和ID拼接                                                                                                             |
 
 # Cache 缓存实例创建
 
@@ -57,14 +56,14 @@ ring := redis.NewRing(&redis.RingOptions{
 // 创建二级缓存实例
 mycache := cache.New(cache.WithName("any"),
     cache.WithRemote(remote.NewGoRedisV9Adapter(ring)),
-    cache.WithLocal(local.NewTinyLFU(10000, time.Minute)),
+    cache.WithLocal(local.NewTinyLFU(10000, time.Minute)), // 本地缓存过期时间统一为 1 分钟
     cache.WithErrNotFound(gorm.ErrRecordNotFound))
 
 obj := struct {
     Name string
     Age  int
 }{Name: "John Doe", Age: 30}
-
+// 设置缓存，其中远程缓存过期时间 TTL 为 1 小时
 err := mycache.Set(context.Background(), "mykey", cache.Value(&obj), cache.TTL(time.Hour))
 if err != nil {
     // 错误处理
@@ -98,7 +97,7 @@ obj := struct {
     Age  int
 }{Name: "John Doe", Age: 30}
 
-err := mycache.Set(context.Background(), "mykey", cache.Value(&obj), cache.TTL(time.Hour))
+err := mycache.Set(context.Background(), "mykey", cache.Value(&obj))
 if err != nil {
     // 错误处理
 }
@@ -169,6 +168,7 @@ if err != nil {
     // 错误处理
 }
 ```
+> 示例4 同时集成了 `Log` 和 `Prometheus` 统计。效果见：[Stat](/docs/CN/Stat.md)
 
 ## 示例5：创建缓存实例，并配置 `errNotFound` 防止缓存穿透
 

diff --git a/docs/CN/Embedded.md b/docs/CN/Embedded.md
@@ -13,11 +13,11 @@
 
 # 多种序列化方式
 
-| codec方式                                           | 说明                        | 优势                |
-|---------------------------------------------------|---------------------------|-------------------|
-| native json                                       | golang自带的序列化工具            | 字节开源的高性能json序列化工具 |
-| [msgpack](https://github.com/vmihailenco/msgpack) | msgpack+snappy压缩（内容>64字节) | 性能较强，内存占用小        |
-| [sonic](https://github.com/go-sonic/sonic)        | 字节开源的高性能json序列化工具         | 性能强               |
+| codec方式                                           | 说明                        | 优势         |
+|---------------------------------------------------|---------------------------|------------|
+| native json                                       | golang自带的序列化工具            | 兼容性好       |
+| [msgpack](https://github.com/vmihailenco/msgpack) | msgpack+snappy压缩（内容>64字节) | 性能较强，内存占用小 |
+| [sonic](https://github.com/go-sonic/sonic)        | 字节开源的高性能json序列化工具         | 性能强        |
 
 你也可以通过实现 `encoding.Codec` 接口来自定义自己的序列化，并通过 `encoding.RegisterCodec` 注册进来。
 
@@ -34,7 +34,7 @@ mycache := cache.New(cache.WithName("any"),
     cache.WithRemote(...),
     cache.WithCodec(yourCodec.Name))
 ```
- 
+
 
 # 多种本地缓存、远程缓存
 
@@ -47,10 +47,11 @@ mycache := cache.New(cache.WithName("any"),
 你也可以通过实现 `remote.Remote`、`local.Local` 接口来实现自己的本地、远程缓存。
 
 > FreeCache 使用注意事项：
-> 
+>
 > 缓存key的大小需要小于65535，否则无法存入到本地缓存中（The key is larger than 65535）  
 > 缓存value的大小需要小于缓存总容量的1/1024，否则无法存入到本地缓存中（The entry size need less than 1/1024 of cache size）  
-> 内嵌的FreeCache实例内部共享了一个 `innerCache` 实例，防止当多个缓存实例都使用 FreeCache 时内存占用过多。因此，共享 `innerCache` 会以第一次创建的配置的内存容量和过期时间为准。  
+> 内嵌的FreeCache实例内部共享了一个 `innerCache` 实例，防止当多个缓存实例都使用 FreeCache 时内存占用过多。因此，共享 `innerCache` 会以第一次创建的配置的内存容量和过期时间为准。
+
 
 # 指标采集统计
 

diff --git a/docs/CN/GettingStarted.md b/docs/CN/GettingStarted.md
@@ -73,7 +73,7 @@ import (
 	"github.com/redis/go-redis/v9"
 )
 
-var errRecordNotFound = errors.New("mock gorm.errRecordNotFound")
+var errRecordNotFound = errors.New("mock gorm.ErrRecordNotFound")
 
 type object struct {
 	Str string