fix: address v6 client review feedback

Author: zouyx

.github/workflows/release.yml

@@ -11,10 +11,13 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v4
+        with:
+          persist-credentials: false
       - name: Set up Go
         uses: actions/setup-go@v5
         with:
           go-version-file: go.mod
+          cache: false
       - name: Verify v6 release contract
         run: |
           test "$(go list -m)" = "github.com/apolloconfig/agollo/v6"

CHANGELOG.md

@@ -6,8 +6,9 @@
 
 * **Module path updated** from `github.com/apolloconfig/agollo/v5` to `github.com/apolloconfig/agollo/v6`:
 
-  ```
-  go get github.com/apolloconfig/agollo/v6@latest
+  ```sh
+  # Run after the v6.0.0 release tag is published.
+  go get github.com/apolloconfig/agollo/v6@v6.0.0
   ```
 
 * New integrations use the instance-scoped `NewClient` / `ApolloClient` API.

README.md

@@ -28,12 +28,14 @@ A Golang client for the configuration center framework [Apollo](https://github.c
 
 # Usage
 
-## Quick Start
+Quick Start
+-----------
 
 ### Import agollo
 
-```
-go get github.com/apolloconfig/agollo/v6@latest
+```sh
+# Run after the v6.0.0 release tag is published.
+go get github.com/apolloconfig/agollo/v6@v6.0.0
 ```
 
 ### Initialize agollo

README_CN.md

@@ -28,35 +28,48 @@ Agollo - Go Client for Apollo
 
 # Usage
 
-## 快速入门
+快速入门
+--------
 
 ### 导入 agollo
 
-```
-go get github.com/apolloconfig/agollo/v6@latest
+```sh
+# 请在 v6.0.0 release tag 发布后执行。
+go get github.com/apolloconfig/agollo/v6@v6.0.0
 ```
 
 ### 启动 agollo
 
 新项目使用实例级 `ApolloClient`，避免进程全局状态并显式管理客户端生命周期：
 
 ```go
-client, err := agollo.NewClient(context.Background(), agollo.ClientOptions{
-	AppID:      "orders",
-	Cluster:    "default",
-	MetaServer: "http://apollo-meta:8080",
-	CacheDir:   "/var/lib/orders/apollo",
-})
-if err != nil {
-	panic(err)
-}
-defer client.Close()
-
-cfg, err := client.Config(context.Background(), "application")
-if err != nil {
-	panic(err)
+package main
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/apolloconfig/agollo/v6"
+)
+
+func main() {
+	client, err := agollo.NewClient(context.Background(), agollo.ClientOptions{
+		AppID:      "orders",
+		Cluster:    "default",
+		MetaServer: "http://apollo-meta:8080",
+		CacheDir:   "/var/lib/orders/apollo",
+	})
+	if err != nil {
+		panic(err)
+	}
+	defer client.Close()
+
+	cfg, err := client.Config(context.Background(), "application")
+	if err != nil {
+		panic(err)
+	}
+	fmt.Println(cfg.Int("server.port", 8080))
 }
-port := cfg.Int("server.port", 8080)
 ```
 
 新版通过 `ConfigForApp` 支持单 Client 多 AppId，通过 `ConfigFile` 读取 YAML、JSON、XML、TXT 等 namespace 原文。需要启动即失败的服务可调用 `Load` 预加载必需 namespace。v5 到 v6 的字段映射、Getter、监听器和扩展点替代方式见[迁移指南](docs/migration-to-apollo-client.md)。

docs/agollo-java-client-parity-implementation.md

@@ -15,13 +15,15 @@ client, err := agollo.NewClient(ctx, agollo.ClientOptions{
     MetaServer: "http://apollo-meta:8080",
     CacheDir:   "/var/lib/orders/apollo",
 })
-if err != nil { /* handle error */ }
+if err != nil { panic(err) }
 defer client.Close()
 
 cfg, err := client.Config(ctx, "application")
+if err != nil { panic(err) }
 port := cfg.Int("server.port", 8080)
 
 file, err := client.ConfigFile(ctx, "application", agollo.ConfigFileFormatYAML)
+if err != nil { panic(err) }
 cancel := cfg.Subscribe(onChange, agollo.WithInterestedKeyPrefixes("db."))
 defer cancel()
 _ = port
@@ -34,7 +36,7 @@ _ = file
 - `Config` 的并发安全实时快照、`Lookup`、字符串/int/int64/float/bool/duration/字符串切片/整数切片 Getter、有序 `Keys` 与来源查询。
 - `ConfigFile` 的原文、格式、来源、变更订阅；properties、yaml/yml 支持 `AsMap`。
 - Config Service 直连或 Meta `/services/config` 发现、轮转节点选择、`releaseKey`、`ip`、`label`、`dataCenter`、`messages` 与按 AppId 的 Access Key 签名。
-- `FULL_SYNC` 和 `INCREMENTAL_SYNC`；增量结果在无全量基线、未知同步类型或非法变更类型时拒绝发布。
+- `FULL_SYNC` 和 `INCREMENTAL_SYNC`；无全量基线的增量结果会立即重试全量拉取，未知同步类型或非法变更类型拒绝发布。
 - 按 AppId 的 `/notifications/v2` 长轮询、Context/`Close` 取消、退避和通知触发刷新。
 - 容灾链：Remote → 原子本地 JSON 缓存 → 可选 `ConfigMapStore`；Local Mode 只读取本地缓存。读取兼容旧 agollo JSON 缓存。
 - 有界监听队列、溢出合并到最新事件、panic 隔离、精确 key/prefix/正则监听，以及无第三方依赖的 `Monitor` 快照。
@@ -53,7 +55,7 @@ _ = file
 | 基础加载和鉴权 | Config URL、ip/DC/label、签名、类型化读取、来源、指标 | `TestApolloClientLoadsConfigAndAppliesProtocolParameters` |
 | YAML ConfigFile | `.yaml` namespace、原文、扁平化 Map、原文变更事件 | `TestApolloClientConfigFileYAMLAndRawListener` |
 | 多 AppId + 增量 | Secret 隔离、`messages`/`releaseKey` 回传、增加/修改/删除、key 前缀过滤 | `TestApolloClientMultiAppIDAndIncrementalSync` |
-| 安全失败 | 无基线的增量同步不能覆盖内存配置 | `TestApolloClientRejectsIncrementalConfigWithoutBaseline` |
+| 增量恢复 | 无基线的增量同步立即回退全量拉取 | `TestApolloClientRecoversIncrementalConfigWithoutBaseline` |
 | 失败后的恢复 | 首次加载失败后可成功重试；成功后不再返回过期错误 | `TestApolloClientRetriesFailedInitialLoad` |
 | 304 通知确认 | 保持内容和事件不变，同时推进 `notificationId` | `TestApolloClientAcknowledges304NotificationWithoutChangeEvent` |
 | 刷新故障 | 已有远端快照时拒绝以旧缓存回滚 | `TestApolloClientRefreshFailureKeepsLastKnownGoodSnapshot` |
@@ -77,7 +79,7 @@ go test -race . -run '^TestApolloClient|^TestPublicApolloClientAPI|^TestClientOp
 go test ./protocol/http ./storage ./utils ./utils/parse/... -count=1
 ```
 
-`go vet ./...` 仍会报告旧包中复制 `sync.Map`/`sync.Once` 的告警（`env`、`storage`、`component/serverlist`）；本次新增文件没有对应告警。它们应在后续 M0/M3 单独清理，不能据此宣称发布门禁已全部达成。
+`go vet ./...` 已通过；同步映射和零值 `Cache` 的实现避免复制或解引用未初始化的同步原语。
 
 ## 尚未完成的发布级工作
 

docs/agollo-refactor-java-client-migration-plan.html

@@ -1108,7 +1108,7 @@ <h2>14. 参考资料</h2>
     </main>
   </div>
 
-  <script src="https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/mermaid@11.16.1/dist/mermaid.min.js" integrity="sha384-aBQXj4hK6Jm05i7aQAsUV3bLdSUrHX1BGYfMB0166TtWt/RRaw+h0Eelme9eOCOvy" crossorigin="anonymous"></script>
   <script>
     (() => {
       const article = document.getElementById('document');

docs/migration-to-apollo-client.md

@@ -11,7 +11,8 @@ import "github.com/apolloconfig/agollo/v6"
 ```
 
 ```sh
-go get github.com/apolloconfig/agollo/v6@latest
+# Run after the v6.0.0 release tag is published.
+go get github.com/apolloconfig/agollo/v6@v6.0.0
 ```
 
 ## 为什么重新设计 API
@@ -181,7 +182,7 @@ cancel := cfg.Subscribe(func(event agollo.ConfigChangeEvent) {
 },
     agollo.WithInterestedKeys("server.port"),
     agollo.WithInterestedKeyPrefixes("db."),
-	    agollo.WithInterestedKeyRegexps(regexp.MustCompile(`^feature\\.`)),
+    agollo.WithInterestedKeyRegexps(regexp.MustCompile(`^feature\.`)),
 )
 defer cancel()
 ```

env/app_config_test.go

@@ -17,7 +17,6 @@ package env
 import (
 	"encoding/json"
 	"os"
-	"sync"
 	"testing"
 	"time"
 
@@ -154,12 +153,3 @@ func TestLoadEnvConfig(t *testing.T) {
 
 	os.Remove(envConfigFile)
 }
-
-func getNotifyLen(s *sync.Map) int {
-	l := 0
-	s.Range(func(k, v interface{}) bool {
-		l++
-		return true
-	})
-	return l
-}

go.mod

@@ -5,6 +5,7 @@ go 1.20
 require (
 	github.com/spf13/viper v1.8.1
 	github.com/tevid/gohamcrest v1.1.1
+	gopkg.in/yaml.v2 v2.4.0
 )
 
 require (
@@ -21,5 +22,4 @@ require (
 	golang.org/x/sys v0.1.0 // indirect
 	golang.org/x/text v0.3.8 // indirect
 	gopkg.in/ini.v1 v1.62.0 // indirect
-	gopkg.in/yaml.v2 v2.4.0 // indirect
 )

modern_cache.go

@@ -95,6 +95,7 @@ func (c *ApolloClient) persistLocalSnapshot(snapshot ConfigSnapshot) error {
 }
 
 func (c *ApolloClient) loadLocalSnapshot(ctx context.Context, key ConfigKey) (ConfigSnapshot, error) {
+	var lastDecodeErr error
 	for _, file := range []string{c.cacheFile(key), c.legacyCacheFile(key)} {
 		if err := ctx.Err(); err != nil {
 			return ConfigSnapshot{}, err
@@ -111,8 +112,13 @@ func (c *ApolloClient) loadLocalSnapshot(ctx context.Context, key ConfigKey) (Co
 		}
 		if snapshot, err := decodeDiskSnapshot(key, body); err == nil {
 			return snapshot, nil
+		} else {
+			lastDecodeErr = err
 		}
 	}
+	if lastDecodeErr != nil {
+		return ConfigSnapshot{}, fmt.Errorf("agollo: no readable local cache for %s: %w", key, lastDecodeErr)
+	}
 	return ConfigSnapshot{}, fmt.Errorf("agollo: no readable local cache for %s", key)
 }
 
@@ -121,6 +127,9 @@ func decodeDiskSnapshot(key ConfigKey, body []byte) (ConfigSnapshot, error) {
 	if err := json.Unmarshal(body, &disk); err != nil {
 		return ConfigSnapshot{}, err
 	}
+	if disk.Version > modernCacheVersion {
+		return ConfigSnapshot{}, fmt.Errorf("local cache version %d is newer than supported version %d", disk.Version, modernCacheVersion)
+	}
 	// agollo legacy cache has the same JSON field names but no version/format.
 	if disk.AppID != "" && disk.AppID != key.AppID {
 		return ConfigSnapshot{}, errors.New("local cache AppId does not match requested AppId")