source

Source · 脚本来源模块

Go Scripts 的脚本加载与变更监听核心接口

中文 · English · 日本語

概述

Source 模块定义了脚本来源的核心接口，为所有引擎提供统一的脚本加载和热更新能力。它包含三个核心接口、六种内置实现和多个扩展子模块。

核心接口

内置实现

扩展子模块

接口定义

// Reader - 脚本加载
type Reader interface {
    Load(ctx context.Context, key string) (code string, err error)
    Close() error
}

// Watcher - 变更监听
type Watcher interface {
    Watch(ctx context.Context, key string) (<-chan struct{}, error)
}

// ReadWatcher - 组合接口
type ReadWatcher interface {
    Reader
    Watcher
}

快速开始

package main

import (
    "context"
    "fmt"
    "os"
    "github.com/liujitcn/go-scripts/source"
)

func main() {
    ctx := context.Background()

    // 使用 FileSource
    fileSrc := source.NewFileSource()
    defer fileSrc.Close()
    code, _ := fileSrc.Load(ctx, "/path/to/script.lua")
    fmt.Println(code)

    // 使用 FileSystemSource（基于 io/fs.FS）
    // 适用于 go:embed、archive/zip、os.DirFS 等
    fsSrc, _ := source.NewFileSystemSource(os.DirFS("/scripts"))
    defer fsSrc.Close()
    code, _ = fsSrc.Load(ctx, "hello.lua")

    // 使用 MemSource
    memSrc := source.NewMemSource()
    defer memSrc.Close()
    memSrc.Set("hello.lua", `print("hello")`)
    code, _ = memSrc.Load(ctx, "hello.lua")

    // Fallback 聚合（File → Memory 回退）
    multi, _ := source.NewFallbackSource(fileSrc, memSrc)
    code, _ = multi.Load(ctx, "backup.lua")

    // CachedSource：S3 远程源 + 内存缓存
    // cached, _ := source.NewCachedSource(s3Source, source.WithTTL(5*time.Minute))
    // defer cached.Close()
    // code, _ = cached.Load(ctx, "script.lua")

    // TransformSource：解密中间件
    // decrypt := source.TransformFunc(func(key, raw string) (string, error) {
    //     return aesDecrypt(raw, secretKey)
    // })
    // transformSrc, _ := source.NewTransformSource(cached, decrypt)
    // defer transformSrc.Close()
    // code, _ = transformSrc.Load(ctx, "script.lua")
}

TransformSource 源码变换中间件

TransformSource 在 Load 之后、返回给引擎之前，对脚本源码执行可配置的变换链。

典型场景：

• 解密：S3 / Git / DB 中存储的 AES/XXTEA 加密脚本
• 解压：gzip / zstd 压缩的脚本
• 过滤：去除敏感信息、编码转换

// 解密钩子
decrypt := source.TransformFunc(func(key string, raw string) (string, error) {
    return aesDecrypt(raw, secretKey)
})

// 包装 S3 Source
src, _ := source.NewTransformSource(s3Source, decrypt)

// 链式追加：解密后再解压
src, _ = src.Then(decompress)

CachedSource 缓存层

CachedSource 在远程源（S3 / DB / HTTP）之上添加内存缓存，大幅减少网络 IO。

特性：

• 缓存命中时零网络开销
• 支持 TTL 自动过期（WithTTL）
• 如果远程源实现 Watcher，变更信号自动失效缓存
• 支持手动失效（Invalidate / InvalidateAll）

// S3 + 内存缓存，TTL 5 分钟
cached, _ := source.NewCachedSource(s3Source, source.WithTTL(5*time.Minute))

// 叠加解密中间件
decrypted, _ := source.NewTransformSource(cached, decrypt)

code, _ := decrypted.Load(ctx, "script.lua")

MultiSource 聚合策略

测试

cd source && go test -v ./...

相关文档

• 返回主文档
• S3 Source 文档
• etcd Source 文档
• Consul Source 文档
• Redis Source 文档
• HTTP Source 文档
• Git Source 文档
• Database Source 文档

License

MIT License