storage

package
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 9, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Overview

本文件实现 filekv 后端:基于文件系统的键值存储。

本文件实现 memorykv 后端:内存键值存储(测试与临时场景用)。

本文件实现 sqlitekv 后端:基于 SQLite 的键值存储(纯 Go 驱动 modernc.org/sqlite)。

Package storage 提供 Storage Domain KV 抽象(hub → backend → domain 三层)。

对齐上游:packages/core/storage-domain

分层设计:

  • Backend:底层键值存储抽象(Get/Put/Delete/List + 版本号),支持 filekv(JSONL 文件)、sqlitekv(SQLite 表)、memorykv(测试用)多实现;
  • Domain[T]:面向业务域的类型化读写层,通过编码序列化 T 落到 backend, 并对外暴露 CAS(Compare-And-Swap)语义:写时必须携带期望版本号, 版本冲突返回统一的 ErrCASMismatch,跨后端错误行为一致;
  • 供 MessageFeedback / GoalRevisionViews / SessionSidecars / SkillsCatalog / WorkspaceRegistry 等域复用同一套 CAS + 类型化读写。

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func IsCASMismatch

func IsCASMismatch(err error) bool

IsCASMismatch 判断是否为 CAS 版本冲突错误。

func IsKeyNotFound

func IsKeyNotFound(err error) bool

IsKeyNotFound 判断是否为 key 不存在错误。

func Migrate

func Migrate(ctx context.Context, src, dst Backend) (migrated int, skipped []string, err error)

Migrate 将 src 后端全部数据拷贝到 dst 后端(跨后端迁移)。 仅迁移 src 中存在的 key;dest 已有更高版本时跳过冲突 key 并记录。

Types

type Backend

type Backend interface {
	// Get 读取 key 的数据与当前版本;key 不存在返回 ErrKeyNotFound。
	Get(ctx context.Context, key string) (data []byte, version uint64, err error)
	// Put 按 CAS 语义写入 key;expectedVersion=0 表示期望新建。
	Put(ctx context.Context, key string, data []byte, expectedVersion uint64) (version uint64, err error)
	// Delete 删除 key(不存在不报错)。
	Delete(ctx context.Context, key string) error
	// List 返回指定前缀下的所有 key(不含 prefix 前缀)。
	List(ctx context.Context, prefix string) (keys []string, err error)
}

Backend 是底层键值存储后端接口。 约定:

  • 版本号从 0 开始;首次写入(expectedVersion=0)创建记录,成功后版本变为 1;
  • Put 携带的 expectedVersion 必须等于当前版本,否则返回 *ErrCASMismatch。

type Domain

type Domain[T any] struct {
	// contains filtered or unexported fields
}

Domain 是一个业务域的类型化存储视图(key 带统一前缀,避免跨域碰撞)。

func NewDomain

func NewDomain[T any](backend Backend, prefix string) *Domain[T]

NewDomain 创建类型化域存储,prefix 用于隔离不同业务域(如 "feedback/")。

func (*Domain[T]) Delete

func (d *Domain[T]) Delete(ctx context.Context, key string) error

Delete 删除域值。

func (*Domain[T]) Get

func (d *Domain[T]) Get(ctx context.Context, key string) (T, uint64, error)

Get 读取并反序列化域值,返回其当前版本号。

func (*Domain[T]) List

func (d *Domain[T]) List(ctx context.Context) ([]string, error)

List 列出该域下所有业务 key。

func (*Domain[T]) Put

func (d *Domain[T]) Put(ctx context.Context, key string, value T, expectedVersion uint64) (uint64, error)

Put 序列化并 CAS 写入域值。expectedVersion 来自 Get 的返回版本;0 表示新建。

type ErrCASMismatch

type ErrCASMismatch struct {
	Key             string
	ExpectedVersion uint64
	ActualVersion   uint64
}

ErrCASMismatch 表示乐观锁(CAS)版本冲突:写入时携带的期望版本与实际版本不符。

func (*ErrCASMismatch) Error

func (e *ErrCASMismatch) Error() string

Error 实现 error 接口。

type ErrKeyNotFound

type ErrKeyNotFound struct {
	Key string
}

ErrKeyNotFound 表示 key 不存在。

func (*ErrKeyNotFound) Error

func (e *ErrKeyNotFound) Error() string

Error 实现 error 接口。

type FileKV

type FileKV struct {
	// contains filtered or unexported fields
}

FileKV 是基于文件系统的 Backend 实现。 每个 key 对应 <root>/<key> 文件,内容为 {"version":N,"data":"<base64>"}。

func NewFileKV

func NewFileKV(root string) (*FileKV, error)

NewFileKV 创建文件后端,root 为存储根目录(不存在则创建)。

func (*FileKV) Delete

func (f *FileKV) Delete(ctx context.Context, key string) error

Delete 实现 Backend。

func (*FileKV) Get

func (f *FileKV) Get(ctx context.Context, key string) ([]byte, uint64, error)

Get 实现 Backend。

func (*FileKV) List

func (f *FileKV) List(ctx context.Context, prefix string) ([]string, error)

List 实现 Backend:返回根目录下所有 key(相对路径,保持 key 分隔符)。

func (*FileKV) Put

func (f *FileKV) Put(ctx context.Context, key string, data []byte, expectedVersion uint64) (uint64, error)

Put 实现 Backend(CAS 语义)。

type MemoryKV

type MemoryKV struct {
	// contains filtered or unexported fields
}

MemoryKV 是基于内存 map 的 Backend 实现。

func NewMemoryKV

func NewMemoryKV() *MemoryKV

NewMemoryKV 创建空内存后端。

func (*MemoryKV) Delete

func (m *MemoryKV) Delete(ctx context.Context, key string) error

Delete 实现 Backend。

func (*MemoryKV) Get

func (m *MemoryKV) Get(ctx context.Context, key string) ([]byte, uint64, error)

Get 实现 Backend。

func (*MemoryKV) List

func (m *MemoryKV) List(ctx context.Context, prefix string) ([]string, error)

List 实现 Backend(字典序输出保证确定性)。

func (*MemoryKV) Put

func (m *MemoryKV) Put(ctx context.Context, key string, data []byte, expectedVersion uint64) (uint64, error)

Put 实现 Backend(CAS 语义)。

type SQLiteKV

type SQLiteKV struct {
	// contains filtered or unexported fields
}

SQLiteKV 是基于 SQLite 的 Backend 实现。 表结构:kv(key TEXT PRIMARY KEY, version INTEGER, data BLOB)。

func NewSQLiteKV

func NewSQLiteKV(path string) (*SQLiteKV, error)

NewSQLiteKV 打开(或创建)SQLite 数据库并初始化表。

func (*SQLiteKV) Close

func (s *SQLiteKV) Close() error

Close 关闭底层数据库连接。

func (*SQLiteKV) Delete

func (s *SQLiteKV) Delete(ctx context.Context, key string) error

Delete 实现 Backend。

func (*SQLiteKV) Get

func (s *SQLiteKV) Get(ctx context.Context, key string) ([]byte, uint64, error)

Get 实现 Backend。

func (*SQLiteKV) List

func (s *SQLiteKV) List(ctx context.Context, prefix string) ([]string, error)

List 实现 Backend。

func (*SQLiteKV) Put

func (s *SQLiteKV) Put(ctx context.Context, key string, data []byte, expectedVersion uint64) (uint64, error)

Put 实现 Backend(CAS 语义:通过 UPDATE 影响行数判断版本冲突)。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL