Liburkel项目API详解：高效键值存储库的核心接口指南

概述

Liburkel是一个高性能的键值存储库，采用优化的Merkle Patricia Trie数据结构实现。本文将从技术角度深入解析其核心API接口，帮助开发者全面理解和使用这个强大的存储引擎。

全局变量与错误处理

错误代码变量

extern int urkel_errno;

该全局变量存储最近一次API调用产生的错误代码，开发者应检查该变量以处理异常情况。

错误常量详解

Liburkel定义了多种错误状态，主要分为以下几类：

1. 验证类错误：

   • URKEL_EHASHMISMATCH：哈希值不匹配
   • URKEL_ESAMEKEY：密钥相同但预期不同
   • URKEL_ESAMEPATH：路径前缀相同但预期不同
   • URKEL_EPATHMISMATCH：路径前缀与密钥不匹配

2. 操作类错误：

   • URKEL_ENOTFOUND：记录不存在
   • URKEL_ECORRUPTION：数据损坏
   • URKEL_EITEREND：迭代器结束

数据库核心操作

初始化与销毁

urkel_t* urkel_open(const char *prefix);
void urkel_close(urkel_t *tree);
int urkel_destroy(const char *prefix);

• urkel_open：创建/打开数据库，参数为存储路径前缀
• urkel_close：关闭数据库连接
• urkel_destroy：彻底销毁数据库

哈希计算

void urkel_hash(unsigned char *hash, const void *data, size_t size);

使用BLAKE2b-256算法计算数据哈希，输出32字节结果。

数据操作

int urkel_get(urkel_t *tree, unsigned char *value, size_t *size, 
             const unsigned char *key, const unsigned char *root);
int urkel_insert(urkel_t *tree, const unsigned char *key,
                const unsigned char *value, size_t size);
int urkel_remove(urkel_t *tree, const unsigned char *key);

• 支持基本的CRUD操作
• 值大小限制为1023字节
• 可指定历史根节点进行查询

状态管理

void urkel_root(urkel_t *tree, unsigned char *hash);
int urkel_inject(urkel_t *tree, const unsigned char *hash);

• urkel_root：获取当前Merkle根
• urkel_inject：回滚到指定历史状态

事务处理API

Liburkel提供了完整的事务支持：

urkel_tx_t* urkel_tx_create(urkel_t *tree, const unsigned char *hash);
void urkel_tx_destroy(urkel_tx_t *tx);
int urkel_tx_commit(urkel_tx_t *tx);

事务特性包括：

1. 快照隔离级别
2. 原子性提交
3. 支持回滚操作

迭代器设计

urkel_iter_t* urkel_iter_create(urkel_tx_t *tx);
int urkel_iter_next(urkel_iter_t *iter, unsigned char *key,
                   unsigned char *value, size_t *size);
void urkel_iter_destroy(urkel_iter_t *iter);

迭代器特点：

• 支持事务级别的遍历
• 前向遍历模式
• 必须显式销毁释放资源

证明与验证机制

Liburkel的核心特性之一是高效的Merkle证明：

int urkel_prove(urkel_t *tree, unsigned char **proof_raw,
               size_t *proof_len, const unsigned char *key,
               const unsigned char *root);
int urkel_verify(int *exists, unsigned char *value,
                size_t *value_len, const unsigned char *proof_raw,
                size_t proof_len, const unsigned char *key,
                const unsigned char *root);

证明机制特点：

1. 支持存在性证明
2. 支持不存在证明
3. 验证效率高

内存管理

void urkel_free(void *ptr);

专用于释放由Liburkel分配的内存，目前主要处理证明数据。

最佳实践建议

1. 错误处理：每次API调用后都应检查urkel_errno
2. 资源释放：迭代器、事务等资源必须显式释放
3. 事务使用：批量操作应使用事务保证原子性
4. 值大小限制：注意1023字节的值大小限制
5. 历史查询：利用root参数可实现历史状态查询

通过本文的详细解析，开发者可以全面掌握Liburkel的核心API功能，在实际项目中高效利用这个高性能键值存储引擎。