Tair (Redis® OSS-Compatible)：串連指南

Spring Data Redis

本樣本使用Maven方式進行構建，您也可以手動下載Lettuce或Jedis用戶端。

1. 開啟編譯器，建立專案。

2. 添加下述pom檔案，並下載Lettuce或Jedis。

   重要

   若使用Lettuce，為避免Lettuce用戶端黑洞問題帶來的影響，建議使用6.3.0.RELEASE及以上版本，並設定TCP_USER_TIMEOUT參數。

   <?xml version="1.0" encoding="UTF-8"?>
   <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
       <modelVersion>4.0.0</modelVersion>
       <parent>
           <groupId>org.springframework.boot</groupId>
           <artifactId>spring-boot-starter-parent</artifactId>
           <version>2.4.2</version>
           <relativePath/> <!-- lookup parent from repository -->
       </parent>
       <groupId>com.aliyun.tair</groupId>
       <artifactId>spring-boot-example</artifactId>
       <version>0.0.1-SNAPSHOT</version>
       <name>spring-boot-example</name>
       <description>Demo project for Spring Boot</description>
       <properties>
           <java.version>1.8</java.version>
       </properties>
       <dependencies>
           <dependency>
               <groupId>org.springframework.boot</groupId>
               <artifactId>spring-boot-starter-web</artifactId>
           </dependency>
           <dependency>
               <groupId>org.springframework.boot</groupId>
               <artifactId>spring-boot-starter-test</artifactId>
               <scope>test</scope>
           </dependency>
           <dependency>
               <groupId>org.springframework.boot</groupId>
               <artifactId>spring-boot-starter-data-redis</artifactId>
           </dependency>
           <dependency>
               <groupId>redis.clients</groupId>
               <artifactId>jedis</artifactId>
           </dependency>
           <dependency>
               <groupId>io.lettuce</groupId>
               <artifactId>lettuce-core</artifactId>
               <version>6.3.0.RELEASE</version>
           </dependency>
           <dependency>
               <groupId>io.netty</groupId>
               <artifactId>netty-transport-native-epoll</artifactId>
               <version>4.1.100.Final</version>
               <classifier>linux-x86_64</classifier>
           </dependency>
       </dependencies>
       <build>
           <plugins>
               <plugin>
                   <groupId>org.springframework.boot</groupId>
                   <artifactId>spring-boot-maven-plugin</artifactId>
               </plugin>
           </plugins>
       </build>
   </project>

3. 在Spring Data Redis編輯器中輸入下述代碼，然後根據注釋提示修改代碼。

   本樣本的Spring Data Redis版本為2.4.2。

   • Spring Data Redis With Jedis

     @Configuration
     public class RedisConfig {
         
         @Bean
         JedisConnectionFactory redisConnectionFactory() {
             //本案例僅用於測試連接，生產環境建議將串連資訊填寫到設定檔中，通過@Value註解讀取
             //串連地址（hostName）和連接埠（port）在執行個體詳情頁下方串連資訊地區擷取，請根據用戶端網路環境選擇專用網路或公網串連
             RedisStandaloneConfiguration config = new RedisStandaloneConfiguration("r-8vbwds91ie1rdl****.redis.zhangbei.rds.aliyuncs.com", 6379);
             //password填寫格式為 帳號:密碼，例如：帳號testaccount，密碼Rp829dlwa，password填寫testaccount:Rp829dlwa
             //忘記帳號密碼請在執行個體詳情頁左側菜單列表點擊帳號管理重設密碼或建立帳號
             config.setPassword(RedisPassword.of("帳號:密碼"));
             JedisPoolConfig jedisPoolConfig = new JedisPoolConfig();
             // 最大串連數, 根據業務需要設定，不能超過執行個體規格規定的最大串連數。
             jedisPoolConfig.setMaxTotal(30);
             // 最大空閑串連數, 根據業務需要設定，不能超過執行個體規格規定的最大串連數。
             jedisPoolConfig.setMaxIdle(20);
             // 關閉 testOn[Borrow|Return]，防止產生額外的PING。
             jedisPoolConfig.setTestOnBorrow(false);
             jedisPoolConfig.setTestOnReturn(false);
     
             JedisClientConfiguration jedisClientConfiguration = JedisClientConfiguration.builder().usePooling().poolConfig(
                     jedisPoolConfig).build();
     
             return new JedisConnectionFactory(config, jedisClientConfiguration);
         }
         @Bean
         public RedisTemplate<String, Object> redisTemplate() {
             RedisTemplate<String, Object> template = new RedisTemplate<>();
             template.setConnectionFactory(redisConnectionFactory());
             template.setKeySerializer(new StringRedisSerializer());
             template.setValueSerializer(new GenericJackson2JsonRedisSerializer());
             return template;
         }
     }

   • Spring Data Redis With Lettuce （包含設定TCP_USER_TIMEOUT參數）

     @Configuration
     public class BeanConfig {
         /**
          *  TCP_KEEPALIVE開啟，並且配置三個參數分別為:
          *  TCP_KEEPIDLE = 30
          *  TCP_KEEPINTVL = 10
          *  TCP_KEEPCNT = 3
          */
         private static final int TCP_KEEPALIVE_IDLE = 30;
     
         /**
          * TCP_USER_TIMEOUT參數可以避免在故障宕機情境下，Lettuce持續逾時的問題。
          * refer: https://github.com/lettuce-io/lettuce-core/issues/2082
          */
         private static final int TCP_USER_TIMEOUT = 30;
     
         @Bean
         LettuceConnectionFactory redisConnectionFactory() {
             RedisStandaloneConfiguration config = new RedisStandaloneConfiguration();
             config.setHostName("r-bp1y4is8svonly****pd.redis.rds.aliyuncs.com");
             config.setPort(6379);
             config.setUsername("r-bp1y4is8svonly****");
             config.setPassword("Da****3");
     
             // Config TCP KeepAlive
             SocketOptions socketOptions = SocketOptions.builder()
                 .keepAlive(KeepAliveOptions.builder()
                     .enable()
                     .idle(Duration.ofSeconds(TCP_KEEPALIVE_IDLE))
                     .interval(Duration.ofSeconds(TCP_KEEPALIVE_IDLE / 3))
                     .count(3)
                     .build())
                 .tcpUserTimeout(TcpUserTimeoutOptions.builder()
                     .enable()
                     .tcpUserTimeout(Duration.ofSeconds(TCP_USER_TIMEOUT))
                     .build())
                 .build();
             LettuceClientConfiguration lettuceClientConfiguration = LettuceClientConfiguration.builder().clientOptions(
                 ClientOptions.builder().socketOptions(socketOptions).build()).build();
             return new LettuceConnectionFactory(config, lettuceClientConfiguration);
         }
     
         @Bean
         RedisTemplate<String, Object> redisTemplate(RedisConnectionFactory connectionFactory) {
             RedisTemplate<String, Object> template = new RedisTemplate<>();
             template.setConnectionFactory(connectionFactory);
             return template;
         }
     }

Jedis

本樣本使用Maven方式進行構建，您也可以手動下載Jedis用戶端。

1. 開啟編譯器，建立專案。

2. 在pom.xml檔案中添加下述代碼。

   本樣本的Jedis版本為4.3.0。

   <dependency>
       <groupId>redis.clients</groupId>
       <artifactId>jedis</artifactId>
       <version>4.3.0</version>
   </dependency>

3. 在編輯器中輸入下述代碼，然後根據注釋提示修改代碼。

   import redis.clients.jedis.Jedis;
   import redis.clients.jedis.JedisPool;
   import redis.clients.jedis.JedisPoolConfig;
   
   public class JedisExample {
       public static void main(String[] args) {
           JedisPoolConfig config = new JedisPoolConfig();
           // 最大空閑串連數，需自行評估，不超過Redis執行個體的最大串連數。
           config.setMaxIdle(200);
           // 最大串連數，需自行評估，不超過Redis執行個體的最大串連數。
           config.setMaxTotal(300);
           config.setTestOnBorrow(false);
           config.setTestOnReturn(false);
           // 分別將hostname和password的值替換為執行個體的串連地址、密碼。
           String hostname = "r-bp1s1bt2tlq3p1****pd.redis.rds.aliyuncs.com";
           // 預設帳號password可直接填寫密碼；建立帳號password填寫格式為 帳號:密碼，例如建立帳號testaccount，密碼Rp829dlwa，password填寫testaccount:Rp829dlwa。
           String password = "r-bp1s1bt2tlq3p1****:Database123";
           JedisPool pool = new JedisPool(config, hostname, 6379, 3000, password);
           Jedis jedis = null;
           try {
               jedis = pool.getResource();
               // 執行相關操作，樣本如下。
               jedis.set("foo10", "bar");
               System.out.println(jedis.get("foo10"));
               jedis.zadd("sose", 0, "car");
               jedis.zadd("sose", 0, "bike");
               System.out.println(jedis.zrange("sose", 0, -1));
           }
           catch (Exception e) {
               // 逾時或其他異常處理。
               e.printStackTrace();
           }
           finally {
               if (jedis != null) {
                   jedis.close();
               }
           }
           pool.destroy();    // 當應用退出，需銷毀資源時，調用此方法。此方法會中斷連線、釋放資源。
       }
   }

4. 運行上述Project，預期會返回如下結果：

   bar
   [bike, car]

redis-py

1. 下載並安裝redis-py用戶端。

2. 在Python編輯器中輸入下述代碼，然後根據注釋提示修改代碼。

   本樣本的Python版本為3.9、redis-py版本為4.4.1。

   #!/usr/bin/env python
   #-*- coding: utf-8 -*-
   import redis
   # 分別將hostname和port的值替換為執行個體的串連地址、連接埠號碼。
   hostname = 'r-bp10noxlhcoim2****.redis.rds.aliyuncs.com'
   port = 6379
   # 將pwd的值替換為執行個體的密碼。
   # 預設帳號password可直接填寫密碼；建立帳號password填寫格式 帳號:密碼，例如建立帳號testaccount，密碼Rp829dlwa，password填寫testaccount:Rp829dlwa。
   password = 'testaccount:Rp829dlwa'
   r = redis.Redis(host=hostname, port=port, password=password)
   # 串連建立後即可執行資料庫操作，下述代碼為您提供SET與GET的使用樣本。
   r.set('foo', 'bar')
   print(r.get('foo'))

3. 運行上述Project，預期會返回如下結果：

   b'bar'

PhpRedis

1. 下載並安裝PhpRedis用戶端。

2. 在PHP編輯器中輸入下述代碼，然後根據注釋提示修改代碼。

   本樣本的PHP版本為8.2.1、PhpRedis版本為5.3.7。

   <?php
    /* 分別將hostname和port的值替換為執行個體的串連地址、連接埠號碼。 */
    $hostname = "r-bp10noxlhcoim2****.redis.rds.aliyuncs.com";
    $port = 6379;
    /* 分別將user和password的值替換為執行個體的帳號和密碼 */
    $user = "testaccount";
    $password = "Rp829dlwa";
    $redis = new Redis();
    if ($redis->connect($hostname, $port) == false) {
            die($redis->getLastError());
      }
    if ($redis->auth([$user, $password]) == false) {
            die($redis->getLastError());
     }
     /* 完成認證後可執行資料庫操作，下述代碼為您提供SET與GET的使用樣本。 */
    if ($redis->set("foo", "bar") == false) {
            die($redis->getLastError());
    }
    $value = $redis->get("foo");
    echo $value;
    ?>

3. 執行上述代碼。

   說明

   常見報錯與解決方案：

   • Cannot assign requested address，原因分析及排查方法，請參見使用短串連訪問Redis出現“Cannot assign requested address”錯誤。

   • redis protocol error, got ' ' as reply type byte，請升級您的PhpRedis用戶端版本，參見GitHub issue。

C或C++

1. 下載並安裝Ｃ用戶端。

2. 在C或C++編輯器中輸入下述代碼，然後根據注釋提示修改代碼。

   本樣本的HiRedis版本為1.1.0。

   #include <stdio.h>
   #include <stdlib.h>
   #include <string.h>
   #include <hiredis.h>
   int main(int argc, char **argv) {
       unsigned int j;
       redisContext *c;
       redisReply *reply;
       if (argc < 4) {
               printf("Usage: example r-bp10noxlhcoim2****.redis.rds.aliyuncs.com 6379 instance_id password\n");
               exit(0);
       }
       const char *hostname = argv[1];
       const int port = atoi(argv[2]);
       const char *instance_id = argv[3];
       const char *password = argv[4];
       struct timeval timeout = { 1, 500000 }; // 1.5 seconds
       c = redisConnectWithTimeout(hostname, port, timeout);
       if (c == NULL || c->err) {
       if (c) {
               printf("Connection error: %s\n", c->errstr);
               redisFree(c);
       } else {
           printf("Connection error: can't allocate redis context\n");
       }
       exit(1);
       }
       /* AUTH */
       reply = redisCommand(c, "AUTH %s", password);
       printf("AUTH: %s\n", reply->str);
       freeReplyObject(reply);
       /* PING server */
       reply = redisCommand(c,"PING");
       printf("PING: %s\n", reply->str);
       freeReplyObject(reply);
       /* Set a key */
       reply = redisCommand(c,"SET %s %s", "foo", "hello world");
       printf("SET: %s\n", reply->str);
       freeReplyObject(reply);
       /* Set a key using binary safe API */
       reply = redisCommand(c,"SET %b %b", "bar", (size_t) 3, "hello", (size_t) 5);
       printf("SET (binary API): %s\n", reply->str);
       freeReplyObject(reply);
       /* Try a GET and two INCR */
       reply = redisCommand(c,"GET foo");
       printf("GET foo: %s\n", reply->str);
       freeReplyObject(reply);
       reply = redisCommand(c,"INCR counter");
       printf("INCR counter: %lld\n", reply->integer);
       freeReplyObject(reply);
       /* again ... */
       reply = redisCommand(c,"INCR counter");
       printf("INCR counter: %lld\n", reply->integer);
       freeReplyObject(reply);
       /* Create a list of numbers, from 0 to 9 */
       reply = redisCommand(c,"DEL mylist");
       freeReplyObject(reply);
       for (j = 0; j < 10; j++) {
               char buf[64];
               snprintf(buf,64,"%d",j);
               reply = redisCommand(c,"LPUSH mylist element-%s", buf);
               freeReplyObject(reply);
           }
       /* Let's check what we have inside the list */
       reply = redisCommand(c,"LRANGE mylist 0 -1");
       if (reply->type == REDIS_REPLY_ARRAY) {
               for (j = 0; j < reply->elements; j++) {
               printf("%u) %s\n", j, reply->element[j]->str);
       }
       }
       freeReplyObject(reply);
       /* Disconnects and frees the context */
       redisFree(c);
       return 0;
   }

3. 編譯上述代碼。

   gcc -o example -g example.c -I /usr/local/include/hiredis -lhiredis

4. 測試回合，完成串連。

    ./example r-bp10noxlhcoim2****.redis.rds.aliyuncs.com 6379 r-bp10noxlhcoim2**** password

.NET

1. 請下載並安裝StackExchange.Redis 2.7.20及以上版本用戶端，更多資訊請參見StackExchange.Redis升級公告。

   重要

   不推薦使用ServiceStack.Redis或CSRedis用戶端：

   • 若使用ServiceStack.Redis用戶端時遇到用戶端的相關問題，您需要向該公司購買相關支援人員服務。

   • CSRedis用戶端的原開發人員已停止維護。

2. 在StackExchange.Redis編輯器中輸入下述代碼，然後根據注釋提示修改下述範例程式碼。

   本樣本的StackExchange.Redis版本為2.7.20。

   using StackExchange.Redis;
    // 分別設定執行個體的串連地址、連接埠號碼和密碼。
    private static ConfigurationOptions configurationOptions = ConfigurationOptions.Parse("r-bp10noxlhcoim2****.redis.rds.aliyuncs.com:6379,password=testaccount:Rp829dlwa,connectTimeout=2000");
     //the lock for singleton
    private static readonly object Locker = new object();
     //singleton
    private static ConnectionMultiplexer redisConn;
    //singleton
    public static ConnectionMultiplexer getRedisConn()
    {
        if (redisConn == null)
        {
            lock (Locker)
            {
                if (redisConn == null || !redisConn.IsConnected)
                {
                    redisConn = ConnectionMultiplexer.Connect(configurationOptions);
                }
            }
        }
        return redisConn;
    }

   說明

   • ConfigurationOptions是StackExchange.Redis的核心，它被整個應用程式共用和重用，應該設定為單例，相關參數設定說明，請參見ConfigurationOptions。

   • 由於GetDatabase()返回的對象是輕量級的，每次用的時候從ConnectionMultiplexer對象中擷取即可。

      redisConn = getRedisConn();
      var db = redisConn.GetDatabase();

node-redis

1. 下載並安裝node-redis用戶端。

2. 在node-redis用戶端中輸入下述代碼，然後根據注釋提示修改代碼。

   本樣本的Node.js版本為19.4.0、node-redis版本為4.5.1。

   import { createClient } from 'redis';
   
   // 分別設定執行個體的連接埠號碼、串連地址、帳號、密碼
   const hostname = 'r-bp10noxlhcoim2****.redis.rds.aliyuncs.com';
   const port = 6379;
   const username = 'testaccount';
   // 如果密碼中包含特殊字元（!@#$%^&*()+-=_）建議用encodeURIComponent進行編碼:password = encodeURIComponent(password)
   const password = 'Rp829dlwa';
   const client = createClient({
     // redis://[[username]:[password]@[hostname][:port]/[db-number]
     url: `redis://${username}:${password}@${hostname}:${port}/0`
   });
   
   client.on('error', (err) => console.log('Redis Client Error', err));
   
   await client.connect();
   
   await client.set('foo', 'bar');
   const value = await client.get('foo');
   console.log("get foo: %s", value);
   await client.disconnect();

   說明

   若提示SyntaxError: Cannot use import statement outside a module，請將.js檔案的尾碼改為.mjs，並在調用時增加--experimental-modules選項，例如node --experimental-modules redis.mjs。

Go-redis

1. 下載並安裝Go-Redis用戶端。

2. 在Go-redis編輯器中輸入下述代碼，然後根據注釋提示修改代碼。

   本樣本的Go版本為1.18.5、Go-redis版本為8.11.5。

   package main
   
   import (
   	"github.com/go-redis/redis"
   	"fmt"
   )
   
   func ExampleClient() {
   	client := redis.NewClient(&redis.Options{
           // 替換為執行個體的串連地址和連接埠
   		Addr:     "r-bp10noxlhcoim2****.redis.rds.aliyuncs.com:6379",
           // 替換為執行個體的密碼
   		Password: "testaccount:Rp829dlwa",
   		DB:       0,  // use default DB
   	})
       // 下述代碼為您提供SET與GET的使用樣本。
   	err := client.Set("foo", "bar", 0).Err()
   	if err != nil {
   		panic(err)
   	}
   
   	val, err := client.Get("foo").Result()
   	if err != nil {
   		panic(err)
   	}
   	fmt.Println("set : foo -> ", val)
   }
   
   func main() {
   	ExampleClient()
   }

Lettuce