Couchbase 和 Spring Data Couchbase 入门

工程 | Josh Long | 2015 年 3 月 16 日 | ...

这篇博客受到了 Couchbase 的开发者倡导者 Laurent Doguin 和我在去年 Couchbase Connect 上的一次演讲的启发。谢谢 Laurent！

这是一个 Spring Data Couchbase 集成的演示。根据项目页面的描述，Spring Data Couchbase 是

Spring Data Couchbase 项目提供了与 Couchbase Server 数据库的集成。Spring Data Couchbase 的主要功能领域是与 Couchbase Buckets 交互的以 POJO 为中心的模型，以及轻松编写 Repository 风格的数据访问层。

什么是 Couchbase？

Couchbase 是一个分布式数据存储，真正实现了水平扩展。我喜欢把它看作是 Redis 和 MongoDB 的混合体：你处理通过键访问的文档。它有适用于所有语言的众多客户端 API。如果你在后端使用 Couchbase 并使用 JVM，你会喜欢 Spring Data Couchbase。项目主页上的要点最好地列出了它的许多特性

使用基于 Java 的 @Configuration 类或 Couchbase 驱动程序的 XML 命名空间提供 Spring 配置支持。
CouchbaseTemplate 辅助类，提高了执行常见 Couchbase 操作的生产力。包括文档和 POJO 之间的集成对象映射。
将异常转换为 Spring 可移植的数据访问异常体系。
与 Spring 的 Conversion Service 集成的功能丰富的对象映射。
基于注解的映射元数据，但可扩展以支持其他元数据格式。
Repository 接口的自动实现，包括支持自定义查找方法（由 Couchbase Views 支持）。
JMX 管理和监控
透明的 @Cacheable 支持，可缓存你需要高速访问的任何对象。

运行 Couchbase

使用 Vagrant 在本地运行 Couchbase

如果你还没有安装 Couchbase（当然），你需要安装它。Michael Nitschinger（@daschl，也是 Spring Data Couchbase 项目的负责人）曾写了一篇博客，介绍了如何在此处搭建一个简单的 4 节点 Vagrant 集群。我在这里的 vagrant 目录中重现了他的示例。要使用它，你当然需要安装 Virtual Box 和 Vagrant，然后只需在 vagrant 目录中运行 vagrant up。为了获得此配置脚本的最新版本，我去了 Michael 的 GitHub vagrants 项目，发现除了此示例外，还有大量其他 Vagrant 脚本可用。在此代码的项目目录中，我有一个指向该项目的子模块，但请务必查阅该项目以获取最新版本。为了让所有东西在我的机器上运行，我选择了 Couchbase 3.0.2 的 Ubuntu 12 安装。你可以通过在启动前配置 VAGRANT_NODES 环境变量来更改启动的节点数量

VAGRANT_NODES=2 vagrant up

在初始设置时，你需要管理和配置 Couchbase。将浏览器指向每个节点的正确 IP。确定该 IP 的规则在 README 中有详细描述。在我看来，管理界面可在 192.168.105.101:8091 和 192.168.105.102:8091 访问。有关此过程的更多信息，我建议你在此处按照指南获取详细信息。

我是这样做的。我访问第一个节点上的管理界面，并创建了一个新集群。我使用 admin 作为用户名，password 作为密码。在所有后续管理页面上，我只需将节点指向 192.168.105.101 并使用前面提到的 admin 凭据加入现有集群。加入所有节点后，在服务器节点面板中查找 Rebalance 按钮并触发集群再平衡。

如果你完成了 Vagrant 集群的使用，可以使用 vagrant halt 命令干净地将其关闭。非常方便的是 vagrant suspend，它会保存节点的状态而不是完全关闭它们。

如果你想从命令行管理 Couchbase 集群，可以使用便捷的 couchbase-cli。你可以简单地使用 vagrant ssh 命令进入每个节点（通过它们的节点名称：node1、node2 等）。进入后，你可以运行集群配置命令。例如，server-list 命令将枚举集群节点。

/opt/couchbase/bin/couchbase-cli server-list -c 192.168.56.101 -u admin -p password

使用以下方法很容易触发再平衡

/opt/couchbase/bin/couchbase-cli rebalance -c 192.168.56.101 -u admin -p password

云端和 Cloud Foundry 上的 Couchbase

Couchbase 非常适合在云端使用。它是水平可扩展的（类似于 Gemfire 或 Cassandra），没有单点故障。它不采用主从或主动/被动系统。有几种方法可以在你的应用程序运行的地方将其启动并运行。如果你正在运行 Cloud Foundry 安装，那么你可以安装 Cumulogic Service Broker，它允许你的 Cloud Foundry 安装与 Cumulogic 平台通信，而 Cumulogic 平台本身可以管理 Couchbase 实例。服务代理是集成的代码片段，它们教 Cloud Foundry 如何配置、销毁以及通常如何与托管服务（在这种情况下是 Couchbase）进行交互。

使用 Spring Data Couchbase 存储 Facebook 地点信息

让我们看一个简单的示例，它读取数据（本例中是使用 Spring Social Facebook 的 FacebookTemplate API 从 Facebook Places API 读取）然后将其加载到 Couchbase 服务器中。

获取 Facebook 访问令牌

你还需要一个 Facebook 访问令牌。最简单的方法是访问Facebook 开发者门户并创建一个新应用程序，然后获取应用程序 ID 和应用程序密钥。将这两个值与竖线字符（|）连接起来。因此，你将获得如下形式的内容：appID|appSecret。示例应用程序使用 Spring 的 Environment 机制来解析 facebook.accessToken 键。你可以在 src/main/resources/application.properties 文件中或使用任何其他受支持的 Spring Boot 属性解析机制为其提供值。你甚至可以将值作为 -D 参数提供：-Dfacebook.accessToken=...|...

告诉 Spring Data Couchbase 关于我们的集群

Couchbase 中的数据存储在桶（buckets）中。它逻辑上与 SQL RDBMS 中的数据库相同。它通常在节点之间复制并有自己的配置。我们将使用默认（default）桶，但创建更多桶也很容易。

让我们看一下使用 Spring Data Couchbase 所需的基本配置（本例中是针对 Spring Boot 应用程序）


@SpringBootApplication
@EnableScheduling
@EnableCaching
public class Application {

  @EnableCouchbaseRepositories
	@Configuration
	static class CouchbaseConfiguration extends AbstractCouchbaseConfiguration {

		@Value("${couchbase.cluster.bucket}")
		private String bucketName;

		@Value("${couchbase.cluster.password}")
		private String password;

		@Value("${couchbase.cluster.ip}")
		private String ip;

		@Override
		protected List<String> bootstrapHosts() {
			return Arrays.asList(this.ip);
		}

		@Override
		protected String getBucketName() {
			return this.bucketName;
		}

		@Override
		protected String getBucketPassword() {
			return this.password;
		}
	}

  // more beans

}

一个 Spring Data Couchbase Repository

Spring Data 提供了 Repository 的概念——处理典型数据访问逻辑并提供基于约定的查询的对象。它们可用于将 POJO 映射到后端数据存储中的数据。

我们的示例简单地存储从 Facebook Places API 读取的商家信息。为了实现这一点，我们创建了一个简单的 Place 实体，Spring Data Couchbase Repository 将知道如何持久化它。


@Document(expiry = 0)
class Place {

	@Id
	private String id;

	@Field
	private Location location;

	@Field
	@NotNull
	private String name;

	@Field
	private String affilitation, category, description, about;

	@Field
	private Date insertionDate;
  // .. getters, constructors, toString, etc
}

Place 实体引用了另一个实体 Location，两者基本相同。

在 Spring Data Couchbase 中，Repository 查找方法映射到 Couchbase 服务器中的视图（views）——用 JavaScript 编写的查询。你需要在 Couchbase 服务器上设置视图。转到任何 Couchbase 服务器的管理控制台，访问视图屏幕，然后点击创建开发视图并将其命名为 place，因为我们的实体将是 demo.Place（开发视图名称默认从实体类名改编）。

我们将创建两个视图，通用视图 all（任何 Spring Data Couchbase POJO 都需要）和 byName 视图（将用于驱动 Repository 的 findByName 查找方法）。这种映射是基于约定的，但你可以通过在查找方法的声明上使用 @View 注解来覆盖使用的视图。

首先，all

现在，byName

完成后，务必发布每个视图！

现在你可以按预期使用 Spring Data Repository 了。这些 Repository 唯一有点不同的是，我们为 findByName 查找方法的参数声明了一个 Spring Data Couchbase 的 Query 类型，而不是 String。使用 @Query 非常简单。

Query query = new Query();
query.setKey("Philz Coffee");
Collection<Place> places = placeRepository.findByName(query);
places.forEach(System.out::println);

下一步何去何从

我们在这里只介绍了一些基础知识。Spring Data Couchbase 支持 Java bean validation API，并且可以配置为遵守其实体上的验证约束。如果你需要，Spring Data Couchbase 还提供了对 CouchbaseClient API 的更低级别访问。Spring Data Couchbase 还实现了Spring CacheManager 抽象——你可以在服务方法中使用 @Cacheable 及相关注解来缓存数据，它将透明地持久化到 Couchbase。

此示例的代码在我的 Github 仓库中，由我和我在 Couchbase 的朋友 Laurent Doguin (@ldoguin) 共同开发。

Spring 博客