RavenDB起步--客户端API（二）

文档会话

会话是代码和 RavenDB 交互的主要方式。会话 API 中包含如下七个常用的高级 API ：

• Load()
• Include()
• Delete()
• Query()
• Store()
• SaveChanges()
• Advanced

下面我们对这七个 API 分别讲解。

Load()

我们使用 Load 可以将一个文档或多个文档加载到会话中，加载到会话中的文档由会话管理。一个文档只能在会话中加载一次。我们先来看一下代码：

var t1 = session.Load<ToDoTask>("ToDoTasks/1-A");
var t2 = session.Load<ToDoTask>("ToDoTasks/1-A");
Assert.True(Object.ReferenceEquals(t1, t2));

在上面的代码中虽然我们两次调用了 session.Load(“ToDoTasks/1-A”); ，但是它只对 RavenDB 进行了一次查询，并且在会话中只有一个 ToDoTask 实例。每当我们加载文档的时候，都会首先检查会话管理内部的字典是否存在该文档，如果不存在就返回现有的实例，这样做有助于提高系统性能。 Load 可以一次加载多个文档，比如像下面这个代码那样，一次加载了三个文档：

Dictionary<string, ToDoTask> tasks = session.Load<ToDoTask>(
    "ToDoTasks/1-A",
    "ToDoTasks/2-A",
    "ToDoTasks/3-A"
);

在上面的代码中，将生成一个包含所有三个文档的字典，这三个文档是通过一次查询检索出来的。 如果在 RavenDB 中没有找到指定的文档，那么字典中文档的 ID 值为 null。 这里需要说明的是，如果加载已经加载完成的文档，那么会话会从会话缓存中返回它们，如果文档不存在的话，会话也会记住无法加载该文档，并马上返回 null 不会再去尝试该文档。

Include()

在项目中我们大部分情况是在处理具有关联关系的文档，那么在 RavenDB 中我们该怎么处理呢？那么，着这一小节里我们来看看如何处理多文档。 首先更新我们的 Model ，在代码中添加 Person 实体类，并修改 ToDoTask 实体类：

public class Person
{
    public string Id { get; set; }
    public string Name { get; set; }
}
public class ToDoTask
{
    public string Id { get; set; }
    public string Task { get; set; }
    public bool Completed { get; set; }
    public DateTime DueDate { get; set; }

    public string AssignedTo { get; set; } 
    public string CreatedBy { get; set; } 
}

这两个实体类是相互独立，没有相互引用的， 这就说明我们可以获取单个文档以及使用单个文档，并且不需要加载其他文档。但是，我们在 ToDoTask 类中增加了 CreatedBy 和 AssignedTo 属性，这两个属性分别表示任务创建人和任务的执行人，他们的 Value 都是来自 Person 类中的 Id 字段。如果这时我们要在新增 Person 的同时给这个 Person 新增一个 ToDoTask 该怎么做呢？我相信有部分同学是这么想的：

using (var session = store.OpenSession())
{
    var person = new Person
    {
        Name = "Oscar Arava"
    };
    session.Store(person);
    session.SaveChanges();
    
    var task = new ToDoTask
    {
        DueDate = DateTime.Today.AddDays(1),
        Task = "Buy milk",
        AssignedTo = person.Id,
        CreatedBy = person.Id
    };
    session.Store(task);
    session.SaveChanges();
}

代码中执行了两次 SaveChanges 方法，这样看来似乎是没毛病。我前面的文章中也提到过 SaveChanges 方法会把前面所有的新增、修改、删除的内容一次性全部提交的 RavenDB 中，因此我们可以把第一个 SaveChanges 方法删掉。那么这时又有同学问了，我不保存 Person ，调用 person.Id 不就报错了吗？其实这个问题完全不必担心，当我们调用 session.Store(person) 后，RavenDB 客户端已经为 Perosn 的 Id 属性赋予了一个唯一值 ，因此在调用 person.Id 时不会出错。那么，现在我们知道了该如何保存多个文档了，下面我们就来看看如何将相关连的文档查询出来。 在 RavenDB 中其实是没有咱们常说的外键关系的，对另一个文档的引用只是一个字符串的属性。那么我们该如何查询出文档及其关联的文档呢？我相信，有的同学一定是这么想的:

using (var session = store.OpenSession())
{
    string taskId = Console.ReadLine();

    ToDoTask task = session.Load<ToDoTask>(taskId);
    Person assignedTo = session.Load<Person>(task.AssignedTo);

    Console.WriteLine(
        $"{task.Id} - {task.Task} by {assignedTo.Name}");
}

上面的代码虽然可以查出关联的数据，但是效率比较低，他执行了两次调用 RavenDB ，一次是获取 Task，另一次是获取 Poerson 。这个案例只是一个简单的查询，但是如果要查询复杂文档的话，这种多次调用就会严重影响效率和性能，那么如何解决呢？其实解决起来也很简单，我们可以使用 Include() 这个 API 。下面的代码就是修改过后的样子：

using (var session = store.OpenSession())
{
    string taskId = Console.ReadLine();

    ToDoTask task = session
              .Include<ToDoTask>(x => x.AssignedTo)
              .Load(taskId);
    
    Person assignedTo = session.Load<Person>(task.AssignedTo);

    Console.WriteLine(
      $"{task.Id} - {task.Task} by {assignedTo.Name}");
}

在这段代码中，我们在 Load 方法之前调用好了 Include 方法，这个方法告诉 RavenDB 当加载文档是，也应该同时根据 AssignedTo 属性去加载对应的 Person 文档。如果 AssignedTo 有值，那么就会和 ToDoTask 文档一起发送个客户端。这时，当我们调用 Load 方法来获取 Person 文档时，因为会话缓存中已经存在了这个文档，因此不会再去查询 RavenDB ，而是直接返回数据。在同一个操作中我们可以调用多次 Include() API，代码如下：

ToDoTask task = session.Include(x => x.AssignedTo)
                       .Include(x => x.CreatedBy)
                       .Load(taskId);

一上面这段代码为了，如果 AssignedTo 和 CreatedBy 都指向同一个文档的话，它只会返回一个文档副本，无论它被引用了多少次。 但是，这里要注意的是 Include 不能在被包含的文档中查询引用的文档，也就是说我们可以通过 ToDoTask 文档查询对应的 Person 文档，但是不能通过 Person 文档查询出是哪些 ToDoTask 文档引用了它，具体原理我将在后续的专题中讲解。