Apache Cassandra作为分布式NoSQL数据库，在需要高可用和海量写入的场景中被广泛采用。对于.NET开发者而言，DataStax官方提供的C#驱动是与Cassandra交互的最佳选择之一，它支持异步编程模型、自动重试和连接池管理等特性。本文将带你从零开始配置该驱动，并通过代码示例掌握基本操作与调优技巧。
准备DataStax C#驱动环境
在开始编写代码之前，需要准备两样东西：一个可访问的Cassandra集群（本地或远程），以及通过NuGet安装的DataStax C#驱动包。驱动包的名称是CassandraCSharpDriver，目前由DataStax维护并持续更新。在Visual Studio的包管理器控制台中执行以下命令即可完成安装：
Install-Package CassandraCSharpDriver
如果使用.NET CLI，可以运行dotnet add package CassandraCSharpDriver。安装完成后，项目会自动引入Cassandra命名空间。需要注意驱动版本与.NET版本的兼容性：驱动支持.NET Standard 2.0及以上目标框架，可以运行在.NET Core、.NET 5/6/7/8以及.NET Framework 4.6.1以上环境。对于生产环境，建议锁定一个经过测试的稳定版本，避免频繁升级引入行为变化。
另外，测试环境中如果没有现成的Cassandra集群，可以使用Docker快速启动一个单节点实例。执行docker run --name cassandra -p 9042:9042 -d cassandra:latest后等待大约30秒让节点完成初始化。此时通过CQL Shell执行DESCRIBE KEYSPACES应该能看到system等内置键空间。本地开发时连接地址直接使用127.0.0.1即可，但需要确保Docker容器的9042端口正确映射到宿主机。
建立集群连接与创建会话
DataStax C#驱动中所有操作的入口是Cluster对象和Session对象。Cluster负责维护与多个节点的连接池，Session则代表一个具体的查询会话。最简单的连接方式如下：
using Cassandra;
var cluster = Cluster.Builder()
.AddContactPoint("127.0.0.1")
.Build();
ISession session = cluster.Connect("my_keyspace");
这里AddContactPoint至少需要一个集群节点的IP地址或主机名。驱动会通过该节点自动发现集群中的其他节点，因此不需要列出全部节点。Connect方法可以指定目标键空间，也可以先不指定，后续通过session.ChangeKeyspace或直接使用完全限定的表名（键空间.表名）来访问数据。如果连接失败，驱动会抛出NoHostAvailableException，此时需要检查网络端口、防火墙以及Cassandra的rpc_address配置。
在生产环境中，强烈建议通过Cluster.Builder的更多选项来定制行为。例如设置WithCredentials启用身份认证，设置WithSocketOptions调整连接超时和读取超时，设置WithQueryTimeout控制单条查询的最大执行时间。一个更健壮的初始化代码片段如下：
var cluster = Cluster.Builder()
.AddContactPoints("10.0.0.1", "10.0.0.2", "10.0.0.3")
.WithCredentials("cassandra", "your_password")
.WithSocketOptions(new SocketOptions()
.SetConnectTimeoutMillis(5000)
.SetReadTimeoutMillis(12000))
.WithQueryTimeout(10000)
.Build();
ISession session = cluster.Connect();
驱动内部会为每个节点维护一个连接池，并且会在节点故障时自动标记为down并在恢复后重新加入。默认的负载均衡策略是TokenAwarePolicy包装DCAwareRoundRobinPolicy，它会尽量将请求路由到持有目标数据副本的节点，减少跨节点的网络开销。对于多数据中心部署，可以用WithLoadBalancingPolicy指定本地数据中心的名称，避免将请求发送到远程数据中心。
执行增删改查与使用PreparedStatement
Cassandra的查询语言是CQL，与SQL相似但并不完全相同。在驱动中执行一条简单的查询可以这样写：
var rs = session.Execute("SELECT * FROM users WHERE id = ?", "user123");
foreach (var row in rs)
{
Console.WriteLine(row.GetValue<string>("name"));
}
Execute方法接受一个简单的字符串查询和位置参数，它对开发者友好但存在性能缺陷。每次调用Execute时，驱动都需要将CQL文本发送到服务器进行解析，即使同一条CQL重复执行多次也无法复用解析结果。更高效的做法是使用PreparedStatement，它会把查询模板预先发送到服务器，之后每次执行只传递绑定变量。典型用法如下：
var prepared = session.Prepare("INSERT INTO users (id, name, age) VALUES (?, ?, ?)");
var bound = prepared.Bind("user456", "Alice", 30);
session.Execute(bound);
PreparedStatement在插入、更新和读取操作中尤其重要，因为它能显著降低服务器CPU占用并提高吞吐量。此外，使用BoundStatement时可以单独设置每条语句的一致性级别、序列化一致性以及时间戳等属性，而不必修改全局配置。例如bound.SetConsistencyLevel(ConsistencyLevel.Quorum);可以覆盖默认的一致性级别。
对于批量写入，驱动提供了BatchStatement，但需要谨慎使用。Cassandra的BatchStatement并不适合海量数据的快速导入，它主要用于保证一组操作在同一个原子批次中执行，且这些操作通常应该具有相同的分区键。如果只是想把大量数据快速写入，应该使用异步的并发Insert配合Task.WhenAll，或者使用数据流处理工具。一个正确的批量写入示例如下：
var batch = new BatchStatement();
batch.Add(prepared.Bind("user1", "Bob", 25));
batch.Add(prepared.Bind("user2", "Carol", 28));
batch.Add(prepared.Bind("user3", "David", 32));
session.Execute(batch);
当表定义了集合类型（如list、set、map）或者使用用户定义类型（UDT）时，C#驱动提供了对应的映射支持。例如row.GetValue<List<string>>("tags")可以直接获取列表，而不需要手动反序列化。对于复杂类型，也可以使用LINQ to CQL（驱动内建的LinqProvider）进行查询，但需要引入Cassandra.Data.Linq命名空间并创建Table<T>映射。这种对象映射方式适合快速开发，但生成的CQL可能不如手写精确，性能敏感场景仍需手工编写PreparedStatement。
处理常见故障与性能调优建议
在使用DataStax C#驱动的过程中，最常见的异常是OperationTimedOutException和WriteTimeoutException。前者通常意味着客户端在设置的超时时间内没有收到任何节点的响应，可能是网络故障或所有节点都处于高负载状态；后者表示Cassandra服务器在写入时未能及时完成，可能由磁盘I/O瓶颈或过小的一致性级别引起。面对超时异常，驱动默认的重试策略会尝试在另一个节点上重试，但只针对幂等的查询（如带主键的INSERT或UPDATE）。如果是非幂等操作，重试可能导致重复写入，因此需要根据业务场景设置合适的RetryPolicy。
一个常见的调优误区是盲目调大连接池大小。Cassandra的节点能够处理的并发请求数是有限的，过多并发连接反而会引起线程切换和内存压力。驱动默认的每个节点连接数对于大多数应用已经足够。更有效的优化方向是减少网络往返：使用PreparedStatement、启用查询缓存、合并小写入为批处理（注意分区键限制）、以及在客户端对相同分区键的写入进行合并。在监控方面，可以开启驱动的指标输出，例如通过Cluster.Builder().WithMetricsEnabled(true)并结合Prometheus等工具观察延迟分布和错误率。
如果你在连接时遇到“所有主机都已尝试但查询失败”的错误，请优先检查Cassandra的start_rpc参数是否为true（旧版本）以及native_transport_port是否使用默认的9042。对于使用TLS加密连接的场景，需要将证书文件路径通过WithSSL选项传递给驱动。最后要记住，Cassandra的数据模型设计与SQL数据库差异很大，在建表之前应当先设计好分区键和聚簇键，否则即使驱动使用正确，查询性能也会随着数据增长而急剧下降。