Redis Stack功能介绍及redis-om-dotnet使用示例

为了简化开发人员对较新的 Redis 模块及其提供的功能的体验，同时简化支持其功能的文档和客户端。以帮助开发人员从开始使用 Redis 的那一刻起，就能充分提高工作效率。Redis Stack诞生了。Redis Stack 将较新的 Redis 模块整合到一个产品中。这使得我们可以轻松地开始使用我们基于 Redis 的搜索、文档、图形和时间序列功能进行构建。

Redis Stack 是由三个组件组成的套件：

1. Redis Stack Server 将开源 Redis 与 RediSearch、RedisJSON、RedisGraph、RedisTimeSeries 和 RedisBloom 结合在一起。

2. RedisInsight 一款强大的工具，用于可视化和优化 Redis 数据，它使实时应用开发比以往任何时候都更简单、更有趣。

3. Redis Stack Client SDK 包括领先的 Java、JavaScript 和 Python 官方 Redis客户端。 这些客户端还包括Redis全新的对象映射库套件，这些库提供了对开发人员友好的抽象，只需几行代码即可大大提高工作效率。这些库被称为 Redis OM for .NET、Node.js、Java、Python，它们还能比以往更轻松地与 Spring、ASP.NET Core、FastAPI 和 Express 等主要应用程序框架集成。

Redis Stack 入门

几种快速入门 Redis Stack 的方法：

·直接从 redis.io 下载 Redis Stack

· 通过你最喜欢的软件包管理器安装，或直接启动 Redis Stack docker 镜像进行安装

· 通过在 Redis Enterprise Cloud 上创建免费数据库或在云中部署 Redis Stack。Redis Enterprise 中提供了 Redis Stack 的能力，供用户自行管理或在企业内部部署。

当你的 Redis Stack Server 成功启动并运行，你就可以立即利用 RedisInsight 来可视化、分析并优化你的 Redis 数据。RedisInsight 包含一系列指南，可指导你了解多个 Redis Stack 使用案例。Redis Stack 现已全面支持 Redis 6.2，并已存在支持 Redis 7.0 的候选版本。

客户端侧：在几款领先的Redis客户端提供了Redis的全新对象映射库redis-om-dotnet。

Redis Stack会替代Redis吗？

Redis Stack 将为实时应用领域带来无限可能，但Redis Stack 并不是 Redis 的替代品。Redis 是一项核心开源技术，企业始终可以选择下载、构建、安装和运行开源 Redis。当你准备好运行 Redis Stack 时，你可以使用Redis复制机制或通过加载你的RDB或AOF文件来轻松迁移数据。

Redis Stack的许可模式

· Redis Stack 的所有代码库组件都是开放的，每个人都可以免费使用

· Redis Stack Server 是根据 Redis Source Available License 2.0（RSALv2）（与Redis 模块使用的许可证相同）提供的。

· 根据现有的服务器端公共许可证（SSPL）提供 RedisInsight。

· Redis clients 和Redis的对象映射库已根据开源 MIT 许可发布。

FAQ

Redis Stack 包含哪些组件？

· Redis Stack 是一个单独的软件包，其中包括搭载了最新的 Redis 模块的开源 Redis（即 Redis Stack Server）和 RedisInsight。

· 在 Redis Stack Server 的初始版本中，包含了五个模块： RedisJSON、RedisSearch、RedisGraph、RedisTimeSeries 和 RedisBloom。

· Redis Stack 由官方 Redis client 和对象映射库提供支持，允许开发人员在多个应用框架（包括 Spring、ASP.Net Core、Express 和 FastAPI）中轻松使用高级的 Redis Stack 功能。

Redis Stack 为开发人员提供了哪些功能？

· 索引和查询 Redis 数据、聚合、执行全文搜索

· 运行高级向量相似性搜索（KNN）

· 高效存储和处理嵌套的 JSON 文档

· 以属性图的形式构建和模拟关系

· 存储、查询和聚合时间序列数据

· 充分利用快速、空间和计算效率高的概率数据结构

· 使用 RedisInsight 轻松实现 Redis 数据的可视化、调试和分析

Redis Stack 还会添加更多功能吗？

如果有以下情况，Redis官方团队会考虑为 Redis Stack 添加新功能甚至模块：

1. 存在社区的需求

2. 新功能符合Redis的愿景

3. Redis公司的工程团队能够正式支持新增功能

为什么 RedisGears 不是 Redis Stack 第一个版本的一部分？

· RedisGears 为 Redis 增加了数据库触发器、流处理、分布式函数和完全可编程性。为 JavaScript 提供 GA 支持后，将 RedisGears 添加到 Redis Stack 中。

什么是 Redis 对象映射库（object-mapping libraries）？

· Redis 对象映射库在 Redis 命令应用程序接口之上提供了一个抽象层次，就像 ORM 对 SQL 数据库的作用一样。从而可以把 Redis 客户端核心库与 Redis 对象映射库区分开来。

核心 Redis 客户端库有以下职责：

· 执行 Redis 协议（RESP 等）

· 管理连接（TCP 等）、重新连接、服务器发现等

· 管理执行逻辑（线程、异步 io 等）

· 为执行任意 Redis 命令暴露 Redis 的 API

· 以常用的交互语法风格的方式暴露 Redis 命令

· 通过连接字符串连接到任何 Redis 已部署的实例

对象映射库提供了额外的能力：

· 允许开发人员用尽可能少的代码行实现常见的 Redis 用例。目前，这包括领域建模和流畅的查询 API。未来，其他常见 Redis 用例也将受到支持，包括缓存、会话存储、速率限制、排行榜和去重器。

· 为 Redis Stack 提供的功能提供高级应用程序接口

· 在不暴露底层 Redis 命令的情况下提供 Redis 的优势能力

· 与主要应用框架（如ASP.NET Core、TJC.Cyclops、Spring、FastAPI、Express）集成

这些对象映射库总是依赖于一个或多个 Redis 核心库。

适用于 .NET 的 RedisOM

Redis OM .NET 是一个专门构建的库，用于处理 Redis Stack 中的文档。在本教程中，我们将构建一个简单的 ASP.NET Core Web-API 应用，用于在简单的人员和地址模型上执行 CRUD 操作，我们将使用 Redis OM .NET 完成所有这些操作。

先决条件

• .NET 6 SDK
• 用于编写 .NET 的任何 IDE（Visual Studio、Rider、Visual Studio Code）。
• RediSearch 必须作为 Redis 堆栈配置的一部分进行安装。
• 可选：Docker Desktop，用于在 docker 中运行 redis-stack 进行本地测试。

运行 Redis Stack

有多种方法可以运行 Redis Stack。一种方法是使用 docker 映像：

docker run -d -p 6379:6379 -p 8001:8001 redis/redis-stack

创建项目

若要创建项目，只需运行：

dotnet new webapi -n Redis.OM.Skeleton --no-https --kestrelHttpPort 5000

然后在所选的 IDE 中打开该文件。Redis.OM.Skeleton.csproj

配置应用

向文件添加字段以配置应用程序。将该连接字符串设置为 Redis 实例的 URI。如果使用前面提到的 docker 命令，则连接字符串将为 。REDIS_CONNECTION_STRINGappsettings.jsonredis://localhost:6379

连接字符串规范

Redis URI 的规范位于此处。可以将 或 用于不包含 的连接字符串。:password@host:portdefault:password@host:portusername

创建模型

请确保将包添加到您的项目中。通过此软件包，您可以轻松创建模型和查询 Redis 域对象。Redis.OM

dotnet add package Redis.OM

现在是时候创建应用程序将用于存储/检索人员的 / 模型了。创建一个名为的新目录，并将文件添加到其中。在 中，添加以下内容：PersonAddressModelAddress.csPerson.csAddress.cs

using Redis.OM.Modeling;

namespace Redis.OM.Skeleton.Model;

public class Address
{

    [Indexed]
    public int? StreetNumber { get; set; }

    [Indexed]
    public string? Unit { get; set; }

    [Searchable]
    public string? StreetName { get; set; }

    [Indexed]
    public string? City { get; set; }

    [Indexed]
    public string? State { get; set; }

    [Indexed]
    public string? PostalCode { get; set; }

    [Indexed]
    public string? Country { get; set; }

    [Indexed]
    public GeoLoc Location { get; set; }

}

在这里，您会注意到，除了标记为 之外，所有字段都使用该属性进行修饰。这些属性 （ 和 ） 告诉 Redis OM，您希望在 Redis Stack 中查询文档时能够在查询中使用这些字段。 不会是文档本身，所以顶级类不会用任何东西装饰;相反，该模型将嵌入到我们的模型中。StreetNameSearchableIndexedSearchableIndexedAddressAddressPerson

为此，请将以下内容添加到Person.cs

using Redis.OM.Modeling;

namespace Redis.OM.Skeleton.Model;

[Document(StorageType = StorageType.Json, Prefixes = new []{"Person"})]

public class Person

{    

    [RedisIdField] [Indexed]public string? Id { get; set; }

    [Indexed] public string? FirstName { get; set; }

    [Indexed] public string? LastName { get; set; }

    [Indexed] public int Age { get; set; }

    [Searchable] public string? PersonalStatement { get; set; }

    [Indexed] public string[] Skills { get; set; } = Array.Empty<string>();    

    [Indexed(CascadeDepth = 1)] public Address? Address { get; set; }

}

这里有几点需要注意：

1. [Document(StorageType = StorageType.Json, Prefixes = new []{"Person"})]指示 Redis OM 将用于在 Redis 中存储文档的数据类型为 JSON，并且 Person 类的键的前缀为 。Person

2. [Indexed(CascadeDepth = 1)] Address? Address { get; set; }是使用 Redis OM 为嵌入对象编制索引的两种方法之一。这种方式指示索引级联到对象图中的对象，1 表示它只会遍历一个级别，索引对象就像从头开始构建索引一样。另一种方法使用要搜索的各个索引字段的属性。这种更外科手术的方法限制了索引的大小。CascadeDepthJsonPath

3. 该属性被标记为 .这将字段表示为存储在 Redis 中时将用于生成文档键名称的字段。IdRedisIdField

创建索引

构建模型后，下一步是在 Redis 中创建索引。管理此问题的最正确方法是将索引创建旋转到托管服务中，该服务将在应用程序启动时运行。 创建一个目录并添加到该目录中。在该文件中，添加以下内容，这将在启动时创建索引。HostedServicesIndexCreationService.cs

using Redis.OM.Skeleton.Model;

namespace Redis.OM.Skeleton.HostedServices;

public class IndexCreationService : IHostedService

{

    private readonly RedisConnectionProvider _provider;

    public IndexCreationService(RedisConnectionProvider provider)

    {

        _provider = provider;

    }

    public async Task StartAsync(CancellationToken cancellationToken)

    {

        await _provider.Connection.CreateIndexAsync(typeof(Person));

    }

    public Task StopAsync(CancellationToken cancellationToken)

    {

        return Task.CompletedTask;

    }

}

 接下来，添加以下内容以在启动时注册服务：Program.cs

builder.Services.AddHostedService<IndexCreationService>();

注入 RedisConnectionProvider

Redis OM 使用该类来处理与 Redis 的连接，并提供可用于与 Redis 交互的类。若要使用它，只需将 RedisConnectionProvider 的实例注入到应用中即可。在文件中，添加：RedisConnectionProviderProgram.cs

builder.Services.AddSingleton(new RedisConnectionProvider(builder.Configuration["REDIS_CONNECTION_STRING"]));

这会将连接字符串从配置中拉出并初始化提供程序。该提供程序现在可在您的控制器/服务中使用。

创建 PeopleController

最后一个难题是为我们的 People API 编写实际的 API 控制器。在目录中，添加文件，该类的骨架将是：controllersPeopleController.csPeopleController

using Microsoft.AspNetCore.Mvc;

using Redis.OM.Searching;

using Redis.OM.Skeleton.Model;

namespace Redis.OM.Skeleton.Controllers;

[ApiController]

[Route("[controller]")]

public class PeopleController : ControllerBase

{

}

注入 RedisConnectionProvider

若要与 Redis 交互，请注入 RedisConnectionProvider。在此依赖注入过程中，拉出一个实例，该实例将允许在 Redis 中查询文档的流畅界面。RedisCollection<Person>

private readonly RedisCollection<Person> _people;

private readonly RedisConnectionProvider _provider;

public PeopleController(RedisConnectionProvider provider)

{

    _provider = provider;

    _people = (RedisCollection<Person>)provider.RedisCollection<Person>();

}

添加用于创建人员的路由

添加到 API 的第一个路由是用于创建人员的 POST 请求，使用 ，就像调用 一样简单，传入 person 对象：RedisCollectionInsertAsync

[HttpPost]

public async Task<Person> AddPerson([FromBody] Person person)

{

    await _people.InsertAsync(person);

    return person;

}

添加路由以按年龄筛选

要添加到 API 的第一个筛选器路由将允许用户按最小和最大年龄进行筛选。使用 的 LINQ 接口是一个简单的操作：RedisCollection

[HttpGet("filterAge")]

public IList<Person> FilterByAge([FromQuery] int minAge, [FromQuery] int maxAge)

{        

    return _people.Where(x => x.Age >= minAge && x.Age <= maxAge).ToList();

}

按地理位置筛选

Redis OM 有一个数据结构，其实例由模型索引，使用 ，可以使用该方法以及要过滤的字段查找具有特定位置半径的所有对象：GeoLocAddressRedisCollectionGeoFilter

[HttpGet("filterGeo")]
public IList<Person> FilterByGeo([FromQuery] double lon, [FromQuery] double lat, [FromQuery] double radius, [FromQuery] string unit)
{
    return _people.GeoFilter(x => x.Address!.Location, lon, lat, radius, Enum.Parse<GeoLocDistanceUnit>(unit)).ToList();
}

按确切字符串筛选

当模型中的字符串属性标记为 时，例如 并且，Redis OM 可以对它们执行精确的文本匹配。例如，以下两个按 和 name 筛选的路由演示了完全匹配的字符串。IndexedFirstNameLastNamePostalCode

[HttpGet("filterName")]
public IList<Person> FilterByName([FromQuery] string firstName, [FromQuery] string lastName)
{
    return _people.Where(x => x.FirstName == firstName && x.LastName == lastName).ToList();
}

[HttpGet("postalCode")]
public IList<Person> FilterByPostalCode([FromQuery] string postalCode)
{
    return _people.Where(x => x.Address!.PostalCode == postalCode).ToList();
}

使用全文搜索进行筛选

当模型中的属性标记为 、 和 时，您可以执行全文搜索，请参阅 和 的筛选器：SearchableStreetAddressPersonalStatementPersonalStatementStreetAddress

[HttpGet("fullText")]
public IList<Person> FilterByPersonalStatement([FromQuery] string text)
{
    return _people.Where(x => x.PersonalStatement == text).ToList();
}

[HttpGet("streetName")]
public IList<Person> FilterByStreetName([FromQuery] string streetName)
{
    return _people.Where(x => x.Address!.StreetName == streetName).ToList();
}

按数组成员资格筛选

当字符串数组或列表标记为 时，Redis OM 可以使用数组或列表的方法过滤包含给定字符串的所有记录。例如，我们的模型有一个技能列表，您可以通过添加以下路由来查询。IndexedContainsPerson

[HttpGet("skill")]
public IList<Person> FilterBySkill([FromQuery] string skill)
{
    return _people.Where(x => x.Skills.Contains(skill)).ToList();
}

更新人员

使用 Redis OM 更新 Redis Stack 中的文档可以通过以下方法完成：首先具体化 person 对象，进行所需的更改，然后调用集合。该集合负责跟踪对其中实现的实体所做的更新;因此，它将跟踪并应用您在其中所做的任何更新。例如，添加以下路由以更新给定 ID 的人员的年龄：Save

[HttpPatch("updateAge/{id}")]
public IActionResult UpdateAge([FromRoute] string id, [FromBody] int newAge)
{
    foreach (var person in _people.Where(x => x.Id == id))
    {
        person.Age = newAge;
    }
    _people.Save();
    return Accepted();
}

删除人员

可以从 Redis 中删除文档。只需调用 Unlink，传入密钥名称即可。给定一个 id，我们可以使用前缀和 id 重建键名：Unlink

[HttpDelete("{id}")]
public IActionResult DeletePerson([FromRoute] string id)
{
    _provider.Connection.Unlink($"Person:{id}");
    return NoContent();
}

运行应用

现在剩下要做的就是运行应用程序并对其进行测试。您可以通过运行 来执行此操作，该应用程序现在暴露在端口 5000 上，并且应该有一个 swagger UI，您可以使用它来玩 API http://localhost:5000/swagger。有几个脚本以及一些数据文件，用于使用 GitHub 存储库中的 API 将一些人插入到 Redis 中dotnet run

使用 Redis Insight 查看数据

您可以安装 Redis Insight GUI，也可以使用在 http://localhost:8001/ 上运行的 Redis Insight GUI。

您可以按照以下步骤查看数据：

1. 接受 EULA

1. 单击“添加 Redis 数据库”按钮

1. 输入 redis 服务器的主机名和端口名。如果您使用的是 docker 映像，则 this is and 为您的数据库指定别名localhost6379

1. 点击Add Redis Database.