Hiredis C 客戶端 API 完整指南：同步/異步/流水線/訂閱模式

Hiredis 官方 API 深度整理：從編譯安裝到生產級用法模式

Hiredis 是 Redis 官方推薦的極簡 C 客戶端庫，無依賴、事件驅動友好。本文系統整理同步 API、異步 API、流水線、發布訂閱、錯誤處理、內存管理等核心用法，並給出生產環境最佳實踐模式。

編譯安裝

make
make install              # 默認 /usr/local
make install PREFIX=~/myredis # 自定義路徑

同步阻塞 API（最常用）

1. 連接與斷開

redisContext *c = redisConnect("127.0.0.1", 6379);
if (c->err) { fprintf(stderr, "Error: %s\n", c->errstr); redisFree(c); return; }
// ... 業務邏輯 ...
redisFree(c); // 釋放上下文

2. 執行命令：redisCommand (printf 風格)

redisReply *r = redisCommand(c, "SET key %s", value); // 字符串參數
redisReply *r = redisCommand(c, "SET key %b", data, len); // 二進制數據 %b
redisReply *r = redisCommand(c, "GET key");

3. 回覆對象 redisReply 類型處理

if (r->type == REDIS_REPLY_ARRAY) {
    for (size_t i = 0; i < r->elements; i++)
        printf("元素 %zu: %s\n", i, r->element[i]->str);
}
freeReplyObject(r); // **必須釋放**，否則內存洩漏

4. 批量命令流水線

redisAppendCommand(c, "SET k1 v1");
redisAppendCommand(c, "GET k1");
redisReply *r;
redisGetReply(c, (void**)&r); freeReplyObject(r); // SET 回覆
redisGetReply(c, (void**)&r); freeReplyObject(r); // GET 回覆

5. 發布訂閱模式

redisReply *r = redisCommand(c, "SUBSCRIBE chan");
freeReplyObject(r); // 訂閱確認回覆
while (redisGetReply(c, (void**)&r) == REDIS_OK) {
    // r->element[0]: "message"/"subscribe"/"unsubscribe"
    // r->element[1]: 頻道名
    // r->element[2]: 消息內容 (message 類型時)
    freeReplyObject(r);
}

異步非阻塞 API（高併發必備）

redisAsyncContext *ac = redisAsyncConnect("127.0.0.1", 6379);
if (ac->err) { /* handle */ }

redisAsyncSetConnectCallback(ac, on_connect);
redisAsyncSetDisconnectCallback(ac, on_disconnect);

redisAsyncCommand(ac, on_set_cb, NULL, "SET key val");
redisAsyncCommand(ac, on_get_cb, NULL, "GET key");
// 事件循環驅動 (libevent/libev/ae 等)
// 需定期調用 redisAsyncHandleRead/Write

錯誤碼體系

所有錯誤可通過 `c->errstr` 獲取描述字符串。

輔助解析器 API（語言綁定用）

redisReader *rd = redisReaderCreate();
redisReaderFeed(rd, buf, len); // 喂入網絡數據
redisReply *r;
while (redisReaderGetReply(rd, (void**)&r) == REDIS_OK) {
    // 處理 r
    freeReplyObject(r);
}
redisReaderFree(rd);

生產環境最佳實踐

1. 連接池： 維護 `redisContext*` 池，避免頻繁連接/斷開開銷。
2. 超時控制： `redisConnectWithTimeout` 設置連接/讀寫超時。
3. 錯誤重試： 網絡抖動時指數退避重試，避免雪崩。
4. 二進制安全： 所有數據用 `%b` 格式或 `redisCommandArgv` 傳遞長度。
5. 內存檢查： 配合 Valgrind/ASan 確保無 `freeReplyObject` 遺漏。