eqfile

EQFile - 目录结构管理工具

EQFile 是一个用于管理和序列化目录结构的 Go 语言库，它能够将文件系统目录结构转换为可序列化的格式，并提供高效的查询和管理功能。

功能特性

• 📁 目录结构序列化：将文件系统目录转换为可存储的二进制格式

• 🔍 快速查询：支持按名称快速查找目录记录

• 💾 持久化存储：使用 Gob 编码将数据持久化到文件

• 🛡️ 错误处理：统一的错误处理系统，支持错误链和类型判断

• 🔄 自检功能：自动验证记录的有效性和一致性

• 📊 状态管理：实时跟踪每个目录节点的状态

• ✅ 存在性检查：快速检查记录是否存在

• 📈 统计功能：获取记录数量和过滤有效记录

安装

go get git.ted49.top/eq/eqfile@latest

或者指定最新版本：

go get git.ted49.top/eq/[email protected]

快速开始

基本用法

package main

import (
    "fmt"
    "log"
    "git.ted49.top/eq/eqfile"
)

func main() {
    // 创建目录管理器
    manager := &eqfile.DirectoryManger{}
    
    // 添加目录记录
    err := manager.AddRecord("MyMusic", "/path/to/music")
    if err != nil {
        log.Fatalf("添加记录失败: %v", err)
    }
    
    // 检查记录是否存在
    exists, err := manager.RecordExists("MyMusic")
    if err != nil {
        log.Fatalf("检查记录存在性失败: %v", err)
    }
    fmt.Printf("记录存在: %v\n", exists)
    
    // 获取记录数量
    count, err := manager.GetRecordsCount()
    if err != nil {
        log.Fatalf("获取记录数量失败: %v", err)
    }
    fmt.Printf("总记录数: %d\n", count)
    
    // 获取所有有效记录
    activeRecords, err := manager.GetActiveRecords()
    if err != nil {
        log.Fatalf("获取有效记录失败: %v", err)
    }
    fmt.Printf("有效记录数: %d\n", len(activeRecords))
}

核心概念

目录记录 (DirectoryRecord)

每个目录记录包含以下信息：

type DirectoryRecord struct {
    ID         string    `json:"id"`           // 唯一标识符 (UUIDv4)
    Name       string    `json:"name"`         // 记录名称
    Path       string    `json:"path"`         // 目录路径
    NodeEQPath string    `json:"node_eq_path"` // 对应的EQ文件路径
    CreatedAt  time.Time `json:"created_at"`   // 创建时间
    UpdatedAt  time.Time `json:"updated_at"`   // 更新时间
    Status     string    `json:"status"`       // 状态标识
    IsExistEQ  bool      `json:"is_exist_eq"`  // EQ文件是否存在
    ErrorCount int       `json:"error_count"`  // 错误计数
}

API 参考

管理器方法

AddRecord - 添加记录

func (d *DirectoryManger) AddRecord(memberName, musicDirPath string) error

添加一个新的目录记录。

RemoveRecord - 删除记录

func (d *DirectoryManger) RemoveRecord(memberName string) error

删除指定的目录记录。

UpdateRecord - 更新记录

func (d *DirectoryManger) UpdateRecord(oldName, newName, newPath string) error

更新现有记录的名称和路径。

GetRecord - 获取单个记录

func (d *DirectoryManger) GetRecord(memberName string) (*DirectoryRecord, error)

按名称获取特定的目录记录。

GetAllRecords - 获取所有记录

func (d *DirectoryManger) GetAllRecords() ([]*DirectoryRecord, error)

获取所有目录记录的列表。

RecordExists - 检查记录是否存在

func (d *DirectoryManger) RecordExists(memberName string) (bool, error)

检查指定名称的记录是否存在。

GetActiveRecords - 获取有效记录

func (d *DirectoryManger) GetActiveRecords() ([]*DirectoryRecord, error)

获取所有有效的（EQ文件存在的）记录。

GetRecordsCount - 获取记录数量

func (d *DirectoryManger) GetRecordsCount() (int, error)

获取记录的总数量。

SelfInspection - 自检

func (d *DirectoryManger) SelfInspection() error

检查所有记录的有效性，移除无效记录。

错误处理工具函数

IsKind - 判断错误种类

func IsKind(err error, kind Kind) bool

检查错误是否属于特定种类。

IsCode - 判断错误代码

func IsCode(err error, code string) bool

检查错误是否具有特定的错误代码。

AsEQError - 提取错误信息

func AsEQError(err error) (*EQError, bool)

从错误链中提取 EQError 实例。

使用示例

新增功能使用示例

// 检查记录是否存在
exists, err := manager.RecordExists("MyMusic")
if err != nil {
    fmt.Printf("检查失败: %v\n", err)
} else if exists {
    fmt.Println("记录存在")
} else {
    fmt.Println("记录不存在")
}

// 获取统计信息
total, err := manager.GetRecordsCount()
if err != nil {
    fmt.Printf("获取总数失败: %v\n", err)
} else {
    fmt.Printf("总记录数: %d\n", total)
}

active, err := manager.GetActiveRecords()
if err != nil {
    fmt.Printf("获取有效记录失败: %v\n", err)
} else {
    fmt.Printf("有效记录数: %d\n", len(active))
    for _, record := range active {
        fmt.Printf("- %s: %s\n", record.Name, record.Path)
    }
}

// 组合使用：检查并获取有效记录数
exists, err := manager.RecordExists("ImportantData")
if err == nil && exists {
    active, err := manager.GetActiveRecords()
    if err == nil {
        fmt.Printf("有 %d 个有效记录\n", len(active))
    }
}

完整的工作流程示例

func main() {
    manager := &eqfile.DirectoryManger{}
    
    // 1. 添加多个记录
    directories := map[string]string{
        "Music": "/home/user/music",
        "Docs": "/home/user/documents", 
        "Pics": "/home/user/pictures",
    }
    
    for name, path := range directories {
        if err := manager.AddRecord(name, path); err != nil {
            fmt.Printf("添加 %s 失败: %v\n", name, err)
        }
    }
    
    // 2. 检查记录存在性
    if exists, err := manager.RecordExists("Music"); err == nil && exists {
        fmt.Println("音乐目录已配置")
    }
    
    // 3. 获取统计信息
    if total, err := manager.GetRecordsCount(); err == nil {
        fmt.Printf("配置了 %d 个目录\n", total)
    }
    
    // 4. 获取有效记录
    if active, err := manager.GetActiveRecords(); err == nil {
        fmt.Printf("%d 个目录有效\n", len(active))
        for _, record := range active {
            fmt.Printf("✓ %s\n", record.Name)
        }
    }
    
    // 5. 定期自检
    if err := manager.SelfInspection(); err != nil {
        if eqfile.IsCode(err, eqfile.CodeInspectionFailed) {
            fmt.Println("自检发现并修复了一些问题")
        }
    }
}

错误处理

// 新增功能的错误处理示例
count, err := manager.GetRecordsCount()
if err != nil {
    if eqfile.IsCode(err, eqfile.CodeFileNotExist) {
        fmt.Println("首次运行，没有记录")
    } else if eqfile.IsCode(err, eqfile.CodeManagerLoad) {
        fmt.Println("加载数据失败")
    } else {
        fmt.Printf("未知错误: %v\n", err)
    }
}

exists, err := manager.RecordExists("")
if err != nil {
    if eqfile.IsCode(err, eqfile.CodeInvalidArgument) {
        fmt.Println("错误：记录名不能为空")
    }
}

下载和更新

首次安装

go get git.ted49.top/eq/eqfile@latest

更新到最新版本

go get -u git.ted49.top/eq/eqfile

查看可用版本

go list -m -versions git.ted49.top/eq/eqfile

指定特定版本

go get git.ted49.top/eq/[email protected]

版本历史

• v1.0.1 (最新) - 新增功能增强

  • ✅ RecordExists() - 记录存在性检查

  • ✅ GetActiveRecords() - 获取有效记录

  • ✅ GetRecordsCount() - 获取记录数量统计

  • ✅ 改进的错误处理系统

  • ✅ 更好的API一致性

• v1.0.0 - 初始版本

  • 基本目录管理功能

  • 统一的错误处理系统

  • Gob序列化支持

  • 自检和验证功能

许可证

Apache License 2.0 - 详见 LICENSE 文件

支持

如果你遇到问题或有疑问，请：

1. 查看详细的错误信息

2. 检查文件系统权限

3. 确认目录路径的有效性

4. 在项目仓库中创建 Issue

联系开发者

项目开发者: Mr.EQ101 和 Ted49