连接配置

配置数据连接、驱动和读写分离。

数据连接配置项名称与访问器名称匹配（取得方式见数据访问接口）。一个 DataAccess 可以拥有多个数据源，用于读写分离等场景。

配置位置

连接配置位于 /Data/ConnectionSettings 选项路径下。DataAccessProvider 获取访问器时会从当前应用配置读取该集合：

/Data/ConnectionSettings

如果调用 GetService(null) 时没有指定名称，会使用默认连接；如果指定名称不存在，也会回退到默认连接。没有默认连接且指定名称不存在时会抛出数据配置异常。

访问器名称如何匹配连接配置？

Discussions 传入的访问器名来自 Module.NAME。没有传入名称或指定名称不存在时，会按提供者规则使用默认连接；因此不能仅凭业务代码中的模块名推断实际连接到了哪个数据库。需要强隔离的部署应核对最终匹配项，避免意外回退。

单数据源

Discussions 的 Module.Accessor 按模块名取得访问器：

来源：src/Module.cs（节选；上下文见源文件）。

Module.cs

public IDataAccess Accessor => _accessor ??= this.Services.ResolveRequired<IDataAccessProvider>().GetAccessor(this.Name);

下列 db1 配置来自 framework 的 XML 解析测试，用于解释 option 结构；它不是 Discussions 的现成数据库连接。部署 Discussions 时应配置对应访问器名称或明确默认连接，驱动与实际数据库环境一起核对。

来源：framework/Zongsoft.Core/test/Configuration/Xml/OptionConfigurationTest-1.option（节选；上下文见源文件）。

OptionConfigurationTest-1.option

<option path="/Data">
	<connectionSettings default="db1">
		<connectionSetting connectionSetting.name="db1" driver="mysql" mode="all" value="server=localhost" />
	</connectionSettings>
</option>

connectionSetting.name 应与数据访问名称一致。业务模块通常用模块名作为数据访问名称，例如 Security、Administratives 或 Discussions。

连接字符串属性

value 是传给对应驱动的连接字符串，通常由分号分隔的键值项组成。连接设置对象会把这些键值项映射到驱动定义的属性，并按属性类型转换，例如端口、布尔值、时间间隔、网络端点或集合。

来源：framework/Zongsoft.Core/test/Configuration/ConnectionSettingsTest.cs（节选；上下文见源文件）。

ConnectionSettingsTest.cs

private static readonly DateTime DATE = new(1979, 5, 15);
private static readonly string ConnectionString = $" ;; server=192.168.0.1:8080, localhost:8088  ; Integer=100 ; enabled ; double= 1.23; ;  boolean= true ; text= MyString; dateTime={DATE:yyyy-M-d}; ; mapping=s1:t1,s2 = t2, same ";

集合属性可以写成一个文本值，放在连接字符串 value 内时通常使用逗号或竖线分隔元素，因为分号已经被外层连接项用作分隔符；具体元素如何转换由属性类型或属性上声明的转换器决定。驱动如果为某个集合属性声明了元素转换器，就可以把 mapping=s1:t1,s2=t2,same 这类短格式解析成结构化条目。

上面的 DATE 和 ConnectionString 来自 ConnectionSettingsTest，其 MyDriver 是测试驱动，不能用来连接 MySQL。这个输入用于检验空白、布尔值、端点集合和元素转换。

驱动设置对象还可以把多个扁平键组装成一个复合属性。下面的框架测试不会要求连接字符串里出现完整的 cluster 值，而是用 cluster. 前缀为 Cluster 属性填充子成员：

来源：framework/Zongsoft.Core/test/Configuration/ConnectionSettingsTest.cs（节选；上下文见源文件）。

ConnectionSettingsTest.cs

public void TestConnectionSettingsCompositeProperty()
{
	var settings = MyDriver.Instance.GetSettings("a.b.c=none;cluster.address=192.168.0.100;nothing.property=none;cluster.heartbeat=30s");
	Assert.NotNull(settings);

	Assert.False(settings.Cluster.IsEmpty);
	Assert.Equal("192.168.0.100", settings.Cluster.Address);
	Assert.Equal(TimeSpan.FromSeconds(30), settings.Cluster.Heartbeat);
	Assert.Equal("none", settings.Properties["a.b.c"]);
	Assert.Equal("none", settings.Properties["nothing.property"]);
}

这类写法适合描述集群、证书、代理、重试策略等结构化设置。能否使用取决于驱动的连接设置类是否定义了对应属性，以及该属性类型是否可以被自动创建并写入公共成员。

读写分离

连接名称使用 # 追加数据源标识。应保留与访问器同名的基础连接，因为默认访问器工厂先检查精确连接名；仅配置后缀项可能在取得访问器时回退或失败：

当前 Discussions 没有配置读写副本的完整用例。部署者可以通过同一访问器名称下的数据源设置 Mode；实际筛选逻辑见 DataSourceProvider 与 DataSourceSelector。数据库复制、故障切换和读后写一致性仍由基础设施及业务约定保证。

mode="WriteOnly" 的数据源用于写入，mode="ReadOnly" 的数据源用于读取。驱动和数据源提供器会根据操作类型选择合适的数据源。

驱动名称

driver 属性必须匹配已部署驱动注册的名称。例如 MySQL 驱动插件会注册：

• /Workbench/Configuration/ConnectionSettings/Drivers/MySql

• /Workbench/Data/Drivers/MySql

如果插件目录中没有部署对应驱动，连接字符串即使正确也无法被解析和执行。

按驱动阅读

注意事项

连接字符串由对应数据库驱动解释。配置时应同时确认驱动包已经部署到宿主插件目录。

生产环境中建议把敏感信息交给环境配置、密钥系统或部署平台注入，避免把账号密码提交到源码仓库。

配置文件里可以放真实连接串吗？

开发环境可以使用本地测试连接串，但生产环境不建议把账号、密码、访问密钥写入仓库。更稳妥的做法是由部署平台、环境变量、密钥管理服务或站点级配置注入敏感值。

路由与一致性

数据源提供器选择精确名称及 名称#后缀 项，再按操作从可读或可写集合选择数据源。查询、存在判断和聚合走可读源；命名命令根据映射中的 mutability 路由。只读命令应明确写 mutability="none"，详见映射文件。

读写分离依赖数据库自身的复制与一致性策略。刚写完立即读取可能受到复制延迟影响；需要读到本次写入时，应根据业务的事务和数据源方案处理，不能认为配置多个连接就自动保证强一致。

连接故障保护

当前引擎通过 DataConnector 管理物理连接建立。同一数据源的连接建立受串行保护，失败后的一段时间内可快速拒绝后续连接，避免大量请求同时冲击不可用数据库。

首次物理连接失败通常保留数据库提供程序的原始异常；熔断期间快速拒绝使用 DataConnectionException，可读取 RetryAt、RetryAfter 等信息。恢复数据库后仍应考虑重试等待时间，不要把每次快速拒绝都当成新的网络故障。

实现定位：连接名筛选、分隔符和访问模式、访问器名称、连接保护。