refactor(ecache): revise code comments

Author: voidint

ecache/entity_cache.go

@@ -13,36 +13,112 @@ import (
 var (
 	singleFlightGroup singleflight.Group
 
-	// Marshal 默认序列化方案
+	// Marshal specifies the default serialization function for cache values
 	Marshal func(v any) ([]byte, error) = json.Marshal
-	// Unmarshal 默认反序列化方案
+
+	// Unmarshal specifies the default deserialization function for cached data
 	Unmarshal func(data []byte, v any) error = json.Unmarshal
-	// DefaultExpiration 缓存默认过期时间
-	DefaultExpiration time.Duration = time.Hour * 24
-	// Disabled 缓存开关
+
+	// DefaultExpiration defines the default time-to-live for cache entries
+	DefaultExpiration time.Duration = 0 // no expiration
+
+	// Disabled globally turns off caching when true
 	Disabled bool
-	// 缓存键名分隔符
+
+	// Delimiter separates components in cache key strings
 	Delimiter = ':'
 )
 
+// Cache defines the contract for cache implementations.
+// Implementations must handle:
+// - Serialization/deserialization using Marshal/Unmarshal functions
+// - Error handling with proper error wrapping
+// - Concurrency control for thread-safe operations
+//
+// All methods should return errors compatible with IsKeyNotFound check
+// for consistent cache miss detection.
+
 type Cache interface {
+	// Del removes multiple entries from cache.
+	//
+	// Args:
+	//   ctx: Context for request cancellation/timeout
+	//   keys: Cache keys to delete
+	//
+	// Returns:
+	//   affected: Number of successfully deleted entries
+	//   err: Storage errors (e.g. connection issues), nil on success
 	Del(ctx context.Context, keys ...string) (affected int64, err error)
+
+	// Get retrieves raw byte slice from cache.
+	//
+	// Args:
+	//   ctx: Context for request cancellation/timeout
+	//   key: Cache entry identifier
+	//
+	// Returns:
+	//   val: Cached byte slice (nil on cache miss)
+	//   err: Storage errors or nil. Use IsKeyNotFound() to detect cache misses
 	Get(ctx context.Context, key string) (val []byte, err error)
+
+	// Set stores byte slice in cache with expiration.
+	//
+	// Args:
+	//   ctx: Context for request cancellation/timeout
+	//   key: Cache entry identifier
+	//   val: Data to store (nil allowed for cache deletion)
+	//   expire: TTL duration (<=0 means no expiration)
+	//
+	// Returns:
+	//   error: Storage errors, nil on success
 	Set(ctx context.Context, key string, val []byte, expire time.Duration) error
+	// GetAsUint64 retrieves and converts cached value to unsigned integer.
+	//
+	// Performs strict conversion:
+	// - Returns error if value is not 8-byte little-endian format
+	// - Returns error if value exceeds uint64 range
+	//
+	// Args:
+	//   key: Cache entry identifier
+	//
+	// Returns:
+	//   val: Converted unsigned integer value
+	//   err: Conversion errors or storage errors
 	GetAsUint64(ctx context.Context, key string) (val uint64, err error)
+	// SetUint64 stores unsigned integer in 8-byte little-endian format.
+	//
+	// Args:
+	//   key: Cache entry identifier
+	//   val: Unsigned integer to store
+	//   expire: TTL duration (<=0 uses default expiration)
+	//
+	// Returns:
+	//   error: Storage errors, nil on success
 	SetUint64(ctx context.Context, key string, val uint64, expire time.Duration) error
+	// IsKeyNotFound checks if error represents cache miss (key not exists).
+	//
+	// Implementation should return true for:
+	// - Cache storage-specific "not found" errors
+	// - Wrapped versions of these errors
+	//
+	// This enables reliable cache miss detection across implementations
 	IsKeyNotFound(err error) bool
 }
 
 type UnsignedInt interface {
 	~uint | ~uint8 | ~uint16 | ~uint32 | ~uint64
 }
 
+// CacheableEntity defines the contract for cacheable domain entities
+// Used to enforce ID-based caching constraints
+// Implementations should:
+// - Use unsigned integer types for identifiers
+// - Maintain immutable ID properties
 type CacheableEntity[INT UnsignedInt] interface {
 	ID() INT
 }
 
-// DelCachedEntity 删除指定键的缓存数据
+// DelCachedEntity deletes cached data for specified key
 func DelCachedEntity(ctx context.Context, cache Cache, key string) (affected int64, err error) {
 	if Disabled {
 		return 0, nil
@@ -54,18 +130,21 @@ func DelCachedEntity(ctx context.Context, cache Cache, key string) (affected int
 	return affected, nil
 }
 
-// GetEntityByID 返回主键ID对应的实体对象。
-// 查找顺序：主键ID --> 缓存中实体对象 --> 数据库中实体对象。
-// 局限：
-// 1、缓存 key格式无法自定义且不够内聚
+// GetEntityByID implements a dual-check mechanism:
+// 1. Check cache first with singleflight deduplication
+// 2. Fallback to database on cache miss
+// 3. Repopulate cache with database result
+//
+// The cache-aside pattern prevents stale cache returns while
+// singleflight prevents cache stampede
 func GetEntityByID[T CacheableEntity[INT], INT UnsignedInt](
 	ctx context.Context,
 	cache Cache,
 	entityKeyPrefix string,
 	id INT,
 	getEntityByID func(context.Context, INT) (*T, error),
 ) (*T, error) {
-	// 0、若未启用缓存，则直接查询数据库。
+	// 0. When cache is disabled, directly query database
 	if Disabled {
 		one, err := getEntityByID(ctx, id)
 		if err != nil {
@@ -74,7 +153,7 @@ func GetEntityByID[T CacheableEntity[INT], INT UnsignedInt](
 		return one, nil
 	}
 
-	// 1、优先尝试从缓存中获取对象
+	// 1. First attempt to retrieve object from cache
 	key := fmt.Sprintf("%s%c%d", entityKeyPrefix, Delimiter, id)
 
 	data, err := cache.Get(ctx, key)
@@ -83,35 +162,39 @@ func GetEntityByID[T CacheableEntity[INT], INT UnsignedInt](
 	}
 
 	if err == nil {
-		// 2、若获取到键对应的值，尝试反序列化，并返回对象。
+		// 2. If value exists, attempt deserialization and return object
 		var one T
 		if err = Unmarshal(data, &one); err == nil {
 			return &one, nil
 		}
-		// 若反序列化失败，不返回，允许继续向下执行。
+		// If deserialization fails, continue execution flow
 	}
 
-	// 2、从数据库查询指定ID对象
-	entity, err, _ := singleFlightGroup.Do(key, func() (any, error) { // 防止缓存击穿
+	// 2. Query database for target ID
+	entity, err, _ := singleFlightGroup.Do(key, func() (any, error) { // Prevent cache breakdown
 		return getEntityByID(ctx, id)
 	})
 	if err != nil {
 		return nil, errors.WithStack(err)
 	}
 
-	// 3、序列化对象并存入Redis
+	// 3. Serialize object and store in cache
 	if data, err = Marshal(entity); err != nil {
 		return nil, errors.WithStack(err)
 	}
 	if err = cache.Set(ctx, key, data, DefaultExpiration); err != nil {
 		return nil, errors.WithStack(err)
 	}
 
-	// 4、返回查询到的对象
+	// 4. Return fetched object
 	return entity.(*T), nil
 }
 
-// GetEntitiesByID 从Redis缓存中读取指定实体列表。若缓存中不存在，则从指定方法中读取并存入Redis缓存。
+// GetEntitiesByID retrieves entity list with cache-aside pattern
+// Implements:
+// 1. Batch cache lookup with singleflight deduplication
+// 2. Database fallback on cache miss
+// 3. Cache population with serialized results
 func GetEntitiesByID[T CacheableEntity[INT], INT UnsignedInt](
 	ctx context.Context,
 	cache Cache,
@@ -122,15 +205,15 @@ func GetEntitiesByID[T CacheableEntity[INT], INT UnsignedInt](
 	var err error
 	var items []*T
 
-	// 0、若未启用缓存，则直接查询数据库。
+	// 0. When cache is disabled, directly query database
 	if Disabled {
 		if items, err = getEntitiesByID(ctx, id); err != nil {
 			return nil, errors.WithStack(err)
 		}
 		return items, nil
 	}
 
-	// 1、优先尝试从Redis中获取对象列表
+	// 1. First attempt to retrieve object from cache列表
 	key := fmt.Sprintf("%s%citems%c%d", entityKeyPrefix, Delimiter, Delimiter, id)
 
 	data, err := cache.Get(ctx, key)
@@ -139,14 +222,14 @@ func GetEntitiesByID[T CacheableEntity[INT], INT UnsignedInt](
 	}
 
 	if err == nil {
-		// 2、若获取到键对应的值，尝试反序列化，并返回对象列表。
+		// 2. If cached data exists, deserialize and return the entity list
 		if err = Unmarshal(data, &items); err == nil {
 			return items, nil
 		}
-		// 若反序列化失败，不返回，允许继续向下执行。
+		// If deserialization fails, continue execution flow
 	}
 
-	// 2、从数据库查询指定ID对象列表
+	// 2. Query database for target ID列表
 	entities, err, _ := singleFlightGroup.Do(key, func() (any, error) {
 		return getEntitiesByID(ctx, id)
 	})
@@ -159,7 +242,7 @@ func GetEntitiesByID[T CacheableEntity[INT], INT UnsignedInt](
 		return items, nil
 	}
 
-	// 3、序列化对象列表并存入Redis
+	// 3、序列化对象列表并存入缓存
 	if data, err = Marshal(&items); err != nil {
 		return nil, errors.WithStack(err)
 	}
@@ -170,17 +253,23 @@ func GetEntitiesByID[T CacheableEntity[INT], INT UnsignedInt](
 	return items, nil
 }
 
-// UniqueKey 唯一索引约束
+// UniqueKey defines constraints for database unique keys
+// Used in GetEntityByUniqueKey to enforce:
+// - String or unsigned integer types
+// - Single-field uniqueness (composite keys not supported)
 type UniqueKey interface {
 	~string | UnsignedInt
 }
 
-// GetEntityByUniqueKey 返回唯一索引值对应的实体对象。
-// 查找顺序：唯一索引值 --> Redis中主键ID --> 数据库中主键ID --> Redis中实体对象 --> 数据库中实体对象。
-// 局限：
-// 1、Redis key格式无法自定义
-// 2、不支持联合唯一索引
-// 3、多一次查询
+// GetEntityByUniqueKey implements two-level cache resolution:
+// 1. UK -> PK lookup cache
+// 2. PK -> Entity cache
+// Features:
+// - Prevents cache stampede with singleflight
+// - Automatic cache population for both UK-PK and PK-Entity mappings
+// Limitations:
+// - Composite unique keys not supported
+// - Fixed cache key format
 func GetEntityByUniqueKey[T CacheableEntity[INT], INT UnsignedInt, UK UniqueKey](
 	ctx context.Context,
 	cache Cache,
@@ -190,7 +279,7 @@ func GetEntityByUniqueKey[T CacheableEntity[INT], INT UnsignedInt, UK UniqueKey]
 	getIDByUK func(context.Context, UK) (INT, error),
 	getEntityByID func(context.Context, INT) (*T, error),
 ) (*T, error) {
-	// 0、若未启用缓存，则直接查询数据库。
+	// 0. When cache is disabled, directly query database
 	if Disabled {
 		id, err := getIDByUK(ctx, ukVal)
 		if err != nil {
@@ -203,28 +292,27 @@ func GetEntityByUniqueKey[T CacheableEntity[INT], INT UnsignedInt, UK UniqueKey]
 		return one, nil
 	}
 
-	// 键：唯一索引值
-	// 值：主键ID
+	// Key represents unique index value
+	// Value stores corresponding primary key ID
 	ukKey := fmt.Sprintf("%s%c%v", ukKeyPrefix, Delimiter, ukVal)
 
-	// 1、根据数据库表唯一索引key找到数据库表主键ID
+	// 1. Resolve primary key ID using unique index key
 	u64ID, err := cache.GetAsUint64(ctx, ukKey)
 	if err == nil {
-		// 2、若找到数据库表主键ID，则根据主键ID尝试返回实体对象。
 		return GetEntityByID(ctx, cache, entityKeyPrefix, INT(u64ID), getEntityByID)
 	}
-	if !cache.IsKeyNotFound(err) { // 发生了除「Redis key不存在」之外的其他未知错误
+	if !cache.IsKeyNotFound(err) { // Handle unexpected errors beyond cache miss
 		return nil, errors.WithStack(err)
 	}
-	// 2、若未找到数据库表主键ID，则调用查询函数获取主键ID值。
+	// 2. If the primary key ID of the database table is not found, call the query function to obtain the primary key ID value.
 	id, err := getIDByUK(ctx, ukVal)
 	if err != nil {
 		return nil, errors.WithStack(err)
 	}
-	// 3、保存唯一索引值（键）与主键ID（值）关系
+	// 3. Persist unique index to primary key mapping
 	if err = cache.SetUint64(ctx, ukKey, uint64(id), -1); err != nil {
 		return nil, errors.WithStack(err)
 	}
-	// 4、根据主键ID尝试返回实体对象
+	// 4. Retrieve entity using resolved primary key
 	return GetEntityByID(ctx, cache, entityKeyPrefix, id, getEntityByID)
 }

ecache/redis/redis_cache.go

@@ -8,44 +8,72 @@ import (
 	"github.com/redis/go-redis/v9"
 )
 
+// cache implements Redis-based caching solution.
+// It wraps go-redis client to provide standard cache interface.
 type cache struct {
 	rdb *redis.Client
 }
 
+// NewCache creates a Redis cache instance.
+// client: Configured go-redis client connection
 func NewCache(client *redis.Client) *cache {
 	return &cache{
 		rdb: client,
 	}
 }
 
+// Del removes multiple keys from cache.
+// Returns number of deleted keys and any error encountered.
+// Wraps redis DEL command errors with stack trace.
 func (c *cache) Del(ctx context.Context, keys ...string) (affected int64, err error) {
 	if affected, err = c.rdb.Del(ctx, keys...).Result(); err != nil {
 		return affected, errors.WithStack(err)
 	}
 	return affected, nil
 }
 
+// Get retrieves byte slice value for given key.
+// Returns redis.Nil error when key does not exist.
+// Wraps underlying redis GET command errors.
 func (c *cache) Get(ctx context.Context, key string) (val []byte, err error) {
 	if val, err = c.rdb.Get(ctx, key).Bytes(); err != nil {
 		return nil, errors.WithStack(err)
 	}
 	return val, nil
 }
 
+// Set stores value with TTL expiration.
+// expire: Time-to-live duration (<=0 means no expiration)
+// Wraps redis SET command errors with stack trace.
+func (c *cache) Set(ctx context.Context, key string, val []byte, expire time.Duration) (err error) {
+	if err = c.rdb.Set(ctx, key, val, expire).Err(); err != nil {
+		return errors.WithStack(err)
+	}
+	return nil
+}
+
+// GetAsUint64 retrieves uint64 value for given key.
+// Returns 0 and error if value cannot be converted.
+// Wraps underlying redis GET command errors.
 func (c *cache) GetAsUint64(ctx context.Context, key string) (val uint64, err error) {
 	if val, err = c.rdb.Get(ctx, key).Uint64(); err != nil {
 		return 0, errors.WithStack(err)
 	}
 	return val, nil
 }
 
-func (c *cache) Set(ctx context.Context, key string, val []byte, expire time.Duration) (err error) {
+// SetUint64 stores uint64 value with TTL expiration.
+// expire: Time-to-live duration (<=0 means no expiration)
+// Wraps redis SET command errors with stack trace.
+func (c *cache) SetUint64(ctx context.Context, key string, val uint64, expire time.Duration) (err error) {
 	if err = c.rdb.Set(ctx, key, val, expire).Err(); err != nil {
 		return errors.WithStack(err)
 	}
 	return nil
 }
 
+// IsKeyNotFound checks if error represents missing key.
+// Returns true if error is redis.Nil.
 func (c *cache) IsKeyNotFound(err error) bool {
 	return errors.Is(err, redis.Nil)
 }