云数据库 Tair（兼容 Redis®）：客户端程序连接教程

本示例使用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);
           // 分别将host和password的值替换为实例的连接地址、密码。
           String host = "r-bp1s1bt2tlq3p1****pd.redis.rds.aliyuncs.com";
           // 默认账号password可直接填写密码；新建账号password填写格式为 账号:密码，例如新建账号testaccount，密码Rp829dlwa，password填写testaccount:Rp829dlwa。
           String password = "r-bp1s1bt2tlq3p1****:Database123";
           JedisPool pool = new JedisPool(config, host, 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]

   重要

   在使用Jedis的过程中，如果设置了一些不合理的参数或错误使用某些功能可能会引起报错，关于如何排查，请参见常见报错。

1. 下载并安装PhpRedis客户端。

2. 在PHP编辑器中输入下述代码，然后根据注释提示修改代码。

   本示例的PHP版本为8.2.1、PhpRedis版本为5.3.7。

   <?php
    /* 分别将host和port的值替换为实例的连接地址、端口号。 */
    $host = "r-bp10noxlhcoim2****.redis.rds.aliyuncs.com";
    $port = 6379;
    /* 分别将user和pwd的值替换为实例的账号和密码 */
    $user = "testaccount";
    $pwd = "Rp829dlwa";
    $redis = new Redis();
    if ($redis->connect($host, $port) == false) {
            die($redis->getLastError());
      }
    if ($redis->auth([$user, $pwd]) == 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。

1. 下载并安装redis-py客户端。

2. 在Python编辑器中输入下述代码，然后根据注释提示修改代码。

   本示例的Python版本为3.9、redis-py版本为4.4.1。

   #!/usr/bin/env python
   #-*- coding: utf-8 -*-
   import redis
   # 分别将host和port的值替换为实例的连接地址、端口号。
   host = 'r-bp10noxlhcoim2****.redis.rds.aliyuncs.com'
   port = 6379
   # 将pwd的值替换为实例的密码。
   # 默认账号password可直接填写密码；新建账号password填写格式 账号:密码，例如新建账号testaccount，密码Rp829dlwa，password填写testaccount:Rp829dlwa。
   pwd = 'testaccount:Rp829dlwa'
   r = redis.Redis(host=host, port=port, password=pwd)
   # 连接建立后即可执行数据库操作，下述代码为您提供SET与GET的使用示例。
   r.set('foo', 'bar')
   print(r.get('foo'))

3. 执行上述代码。

本示例使用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

     @Bean
          JedisConnectionFactory redisConnectionFactory() {
              RedisStandaloneConfiguration config = new RedisStandaloneConfiguration("host", port);
      
              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);
          }

   • 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;
         }
     }

4. 执行上述代码。

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

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();

3. 通过客户端程序操作常见的数据结构，示例如下：

   String

   //set get
   string strKey = "hello";
   string strValue = "world";
   bool setResult = db.StringSet(strKey, strValue);
   Console.WriteLine("set " + strKey + " " + strValue + ", result is " + setResult);
   //incr
   string counterKey = "counter";
   long counterValue = db.StringIncrement(counterKey);
   Console.WriteLine("incr " + counterKey + ", result is " + counterValue);
   //expire
   db.KeyExpire(strKey, new TimeSpan(0, 0, 5));
   Thread.Sleep(5 * 1000);
   Console.WriteLine("expire " + strKey + ", after 5 seconds, value is " + db.StringGet(strKey));
   //mset mget
   KeyValuePair<RedisKey, RedisValue> kv1 = new KeyValuePair<RedisKey, RedisValue>("key1", "value1");
   KeyValuePair<RedisKey, RedisValue> kv2 = new KeyValuePair<RedisKey, RedisValue>("key2", "value2");
   db.StringSet(new KeyValuePair<RedisKey, RedisValue>[] {kv1,kv2});            
   RedisValue[] values = db.StringGet(new RedisKey[] {kv1.Key, kv2.Key});
   Console.WriteLine("mget " + kv1.Key.ToString() + " " + kv2.Key.ToString() + ", result is " + values[0] + "&&" + values[1]);

   Hash

   string hashKey = "myhash";
   //hset
   db.HashSet(hashKey,"f1","v1");
   db.HashSet(hashKey,"f2", "v2");
   HashEntry[] values = db.HashGetAll(hashKey);
   //hgetall
   Console.Write("hgetall " + hashKey + ", result is");
   for (int i = 0; i < values.Length;i++) 
   {
     HashEntry hashEntry = values[i];
     Console.Write(" " + hashEntry.Name.ToString() + " " + hashEntry.Value.ToString());
   }
   Console.WriteLine();

   List

   //list key
   string listKey = "myList";
   //rpush
   db.ListRightPush(listKey, "a");
   db.ListRightPush(listKey, "b");
   db.ListRightPush(listKey, "c");
   //lrange
   RedisValue[] values = db.ListRange(listKey, 0, -1);
   Console.Write("lrange " + listKey + " 0 -1, result is ");
   for (int i = 0; i < values.Length; i++)
   {
    Console.Write(values[i] + " ");
   }
   Console.WriteLine();

   Set

   //set key
   string setKey = "mySet";
   //sadd
   db.SetAdd(setKey, "a");
   db.SetAdd(setKey, "b");
   db.SetAdd(setKey, "c");
   //sismember
   bool isContains = db.SetContains(setKey, "a");
   Console.WriteLine("set " + setKey + " contains a is " + isContains );

   Sorted Set

   string sortedSetKey = "myZset";
   //sadd
   db.SortedSetAdd(sortedSetKey, "xiaoming", 85);
   db.SortedSetAdd(sortedSetKey, "xiaohong", 100);
   db.SortedSetAdd(sortedSetKey, "xiaofei", 62);
   db.SortedSetAdd(sortedSetKey, "xiaotang", 73);
   //zrevrangebyscore
   RedisValue[] names = db.SortedSetRangeByRank(sortedSetKey, 0, 2, Order.Ascending);
   Console.Write("zrevrangebyscore " + sortedSetKey + " 0 2, result is ");
   for (int i = 0; i < names.Length; i++)
   {
     Console.Write(names[i] + " ");
   }
   Console.WriteLine();

1. 下载并安装node-redis客户端。

2. 在node-redis客户端中输入下述代码，然后根据注释提示修改代码。

   本示例的Node.js版本为19.4.0、node-redis版本为4.5.1。

   import { createClient } from 'redis';
   
   // 分别设置实例的端口号、连接地址、账号、密码
   const host = '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]@[host][:port]/[db-number]
     url: `redis://${username}:${password}@${host}:${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。

3. 执行上述代码。

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()
   }

3. 执行上述代码。