mirror of
https://github.com/GeWuYou/GFramework.git
synced 2026-05-07 08:44:29 +08:00
a75194337e
- 修复 AGENTS 中 latest-head review thread 指向的英文标点一致性问题 - 删除 MediatorAdvancedFeaturesTests 中未使用的 TestLoggingBehavior 测试基础设施 - 重构 VersionedMigrationRunner 的迁移执行上下文传递并补充对应 XML 文档 - 更新 analyzer warning reduction 的 active tracking 与 trace，记录 PR #291 复核结果和 639 条根构建基线
259 lines
12 KiB
C#
259 lines
12 KiB
C#
// Copyright (c) 2026 GeWuYou
|
|
// Licensed under the Apache License, Version 2.0 (the "License");
|
|
// you may not use this file except in compliance with the License.
|
|
// You may obtain a copy of the License at
|
|
//
|
|
// http://www.apache.org/licenses/LICENSE-2.0
|
|
//
|
|
// Unless required by applicable law or agreed to in writing, software
|
|
// distributed under the License is distributed on an "AS IS" BASIS,
|
|
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
// See the License for the specific language governing permissions and
|
|
// limitations under the License.
|
|
|
|
namespace GFramework.Game.Internal;
|
|
|
|
/// <summary>
|
|
/// 提供版本化数据迁移链的共享执行逻辑。
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// 该运行器只负责“按版本号推进”的公共约束，包括：
|
|
/// 前向注册校验、缺失链路失败、声明目标版本与实际结果版本一致性，以及避免版本回退或死循环。
|
|
/// 它不关心具体存储、日志、回写或异常吞吐策略；这些由调用方负责。
|
|
/// </remarks>
|
|
internal static class VersionedMigrationRunner
|
|
{
|
|
/// <summary>
|
|
/// 复用一次迁移链执行期间不会变化的上下文，避免多个 helper 重复传递同一组委托和消息元数据。
|
|
/// </summary>
|
|
/// <typeparam name="TData">迁移数据类型。</typeparam>
|
|
/// <typeparam name="TMigration">迁移描述类型。</typeparam>
|
|
private readonly record struct MigrationExecutionContext<TData, TMigration>(
|
|
Func<TData, int> GetVersion,
|
|
Func<TMigration, int> GetToVersion,
|
|
Func<TMigration, TData, TData> ApplyMigration,
|
|
string SubjectName,
|
|
string MigrationKind)
|
|
where TData : class;
|
|
|
|
/// <summary>
|
|
/// 校验迁移注册是否表示一次有效的前向升级。
|
|
/// </summary>
|
|
/// <param name="subjectName">迁移所作用的主体名称，例如设置类型或存档类型。</param>
|
|
/// <param name="migrationKind">用于异常消息的迁移类别名称。</param>
|
|
/// <param name="fromVersion">源版本。</param>
|
|
/// <param name="toVersion">目标版本。</param>
|
|
/// <param name="paramName">异常中要使用的参数名。</param>
|
|
/// <exception cref="ArgumentException">目标版本不大于源版本时抛出。</exception>
|
|
internal static void ValidateForwardOnlyRegistration(
|
|
string subjectName,
|
|
string migrationKind,
|
|
int fromVersion,
|
|
int toVersion,
|
|
string paramName)
|
|
{
|
|
if (toVersion <= fromVersion)
|
|
{
|
|
throw new ArgumentException(
|
|
$"{migrationKind} for {subjectName} must advance the version number.",
|
|
paramName);
|
|
}
|
|
}
|
|
|
|
/// <summary>
|
|
/// 按目标运行时版本执行连续迁移。
|
|
/// </summary>
|
|
/// <typeparam name="TData">迁移数据类型。</typeparam>
|
|
/// <typeparam name="TMigration">迁移描述类型。</typeparam>
|
|
/// <param name="data">原始加载的数据。</param>
|
|
/// <param name="targetVersion">当前运行时支持的目标版本。</param>
|
|
/// <param name="getVersion">从数据对象提取版本号的委托。</param>
|
|
/// <param name="resolveMigration">根据当前版本查找下一步迁移器的委托。</param>
|
|
/// <param name="getToVersion">从迁移器提取声明目标版本的委托。</param>
|
|
/// <param name="applyMigration">执行单步迁移的委托。</param>
|
|
/// <param name="subjectName">迁移主体名称，用于异常消息。</param>
|
|
/// <param name="migrationKind">迁移类别名称，用于异常消息。</param>
|
|
/// <returns>迁移到目标版本后的数据；如果已经是最新版本，则返回原对象。</returns>
|
|
/// <exception cref="ArgumentNullException">
|
|
/// <paramref name="data" />、<paramref name="getVersion" />、<paramref name="resolveMigration" />、
|
|
/// <paramref name="getToVersion" /> 或 <paramref name="applyMigration" /> 为 <see langword="null" /> 时抛出。
|
|
/// </exception>
|
|
/// <exception cref="ArgumentException">
|
|
/// <paramref name="subjectName" /> 或 <paramref name="migrationKind" /> 为空白时抛出。
|
|
/// </exception>
|
|
/// <exception cref="InvalidOperationException">
|
|
/// 数据版本高于当前运行时、迁移链缺失、迁移器返回 <see langword="null" />、
|
|
/// 迁移结果版本与声明不一致、版本未前进或超出目标版本时抛出。
|
|
/// </exception>
|
|
internal static TData MigrateToTargetVersion<TData, TMigration>(
|
|
TData data,
|
|
int targetVersion,
|
|
Func<TData, int> getVersion,
|
|
Func<int, TMigration?> resolveMigration,
|
|
Func<TMigration, int> getToVersion,
|
|
Func<TMigration, TData, TData> applyMigration,
|
|
string subjectName,
|
|
string migrationKind)
|
|
where TData : class
|
|
{
|
|
ArgumentNullException.ThrowIfNull(data);
|
|
ArgumentNullException.ThrowIfNull(getVersion);
|
|
ArgumentNullException.ThrowIfNull(resolveMigration);
|
|
ArgumentNullException.ThrowIfNull(getToVersion);
|
|
ArgumentNullException.ThrowIfNull(applyMigration);
|
|
ArgumentException.ThrowIfNullOrWhiteSpace(subjectName);
|
|
ArgumentException.ThrowIfNullOrWhiteSpace(migrationKind);
|
|
|
|
var currentVersion = getVersion(data);
|
|
EnsureRuntimeVersionIsSupported(currentVersion, targetVersion, subjectName);
|
|
|
|
if (currentVersion == targetVersion)
|
|
{
|
|
return data;
|
|
}
|
|
|
|
var context = new MigrationExecutionContext<TData, TMigration>(
|
|
getVersion,
|
|
getToVersion,
|
|
applyMigration,
|
|
subjectName,
|
|
migrationKind);
|
|
|
|
var current = data;
|
|
|
|
while (currentVersion < targetVersion)
|
|
{
|
|
var migration = GetRequiredMigration(resolveMigration, currentVersion, in context);
|
|
var result = ApplyMigrationStep(
|
|
migration,
|
|
current,
|
|
currentVersion,
|
|
targetVersion,
|
|
in context);
|
|
current = result.Data;
|
|
currentVersion = result.Version;
|
|
}
|
|
|
|
return current;
|
|
}
|
|
|
|
/// <summary>
|
|
/// 拒绝比当前运行时更高的数据版本，避免迁移器在未知版本上继续执行。
|
|
/// </summary>
|
|
/// <param name="currentVersion">数据当前版本。</param>
|
|
/// <param name="targetVersion">运行时支持的目标版本。</param>
|
|
/// <param name="subjectName">迁移主体名称。</param>
|
|
/// <exception cref="InvalidOperationException">数据版本高于运行时版本时抛出。</exception>
|
|
private static void EnsureRuntimeVersionIsSupported(int currentVersion, int targetVersion, string subjectName)
|
|
{
|
|
if (currentVersion > targetVersion)
|
|
{
|
|
throw new InvalidOperationException(
|
|
$"{subjectName} is version {currentVersion}, which is newer than the current runtime version {targetVersion}.");
|
|
}
|
|
}
|
|
|
|
/// <summary>
|
|
/// 解析当前版本必须存在的下一步迁移器，避免在调用循环中重复拼接相同错误。
|
|
/// </summary>
|
|
/// <typeparam name="TData">迁移数据类型。</typeparam>
|
|
/// <typeparam name="TMigration">迁移描述类型。</typeparam>
|
|
/// <param name="resolveMigration">迁移解析委托。</param>
|
|
/// <param name="currentVersion">当前版本。</param>
|
|
/// <param name="context">本轮迁移链共享的执行上下文。</param>
|
|
/// <returns>已解析的迁移器。</returns>
|
|
/// <exception cref="InvalidOperationException">缺少迁移器时抛出。</exception>
|
|
private static TMigration GetRequiredMigration<TData, TMigration>(
|
|
Func<int, TMigration?> resolveMigration,
|
|
int currentVersion,
|
|
in MigrationExecutionContext<TData, TMigration> context)
|
|
where TData : class
|
|
{
|
|
var migration = resolveMigration(currentVersion);
|
|
if (migration is null)
|
|
{
|
|
throw new InvalidOperationException(
|
|
$"No {context.MigrationKind} is registered for {context.SubjectName} from version {currentVersion}.");
|
|
}
|
|
|
|
return migration;
|
|
}
|
|
|
|
/// <summary>
|
|
/// 执行单步迁移并验证声明目标版本、结果版本与运行时上限之间的一致性。
|
|
/// </summary>
|
|
/// <typeparam name="TData">迁移数据类型。</typeparam>
|
|
/// <typeparam name="TMigration">迁移描述类型。</typeparam>
|
|
/// <param name="migration">当前步骤的迁移器。</param>
|
|
/// <param name="current">迁移前数据。</param>
|
|
/// <param name="currentVersion">迁移前版本。</param>
|
|
/// <param name="targetVersion">运行时目标版本。</param>
|
|
/// <param name="context">本轮迁移链共享的执行上下文。</param>
|
|
/// <returns>迁移后的数据与新版本号。</returns>
|
|
/// <exception cref="InvalidOperationException">
|
|
/// 迁移结果为空、声明目标版本不匹配、版本未前进或超出运行时版本时抛出。
|
|
/// </exception>
|
|
private static (TData Data, int Version) ApplyMigrationStep<TData, TMigration>(
|
|
TMigration migration,
|
|
TData current,
|
|
int currentVersion,
|
|
int targetVersion,
|
|
in MigrationExecutionContext<TData, TMigration> context)
|
|
where TData : class
|
|
{
|
|
var migratedData = context.ApplyMigration(migration, current)
|
|
?? throw new InvalidOperationException(
|
|
$"{context.MigrationKind} for {context.SubjectName} from version {currentVersion} returned null.");
|
|
var migratedVersion = context.GetVersion(migratedData);
|
|
ValidateMigrationResult(
|
|
currentVersion,
|
|
targetVersion,
|
|
migratedVersion,
|
|
context.GetToVersion(migration),
|
|
in context);
|
|
return (migratedData, migratedVersion);
|
|
}
|
|
|
|
/// <summary>
|
|
/// 校验单步迁移结果与声明目标版本一致，并确保版本严格单调递增且不越过运行时版本。
|
|
/// </summary>
|
|
/// <typeparam name="TData">迁移数据类型。</typeparam>
|
|
/// <typeparam name="TMigration">迁移描述类型。</typeparam>
|
|
/// <param name="currentVersion">迁移前版本。</param>
|
|
/// <param name="targetVersion">运行时目标版本。</param>
|
|
/// <param name="migratedVersion">迁移后实际版本。</param>
|
|
/// <param name="declaredTargetVersion">迁移器声明的目标版本。</param>
|
|
/// <param name="context">本轮迁移链共享的执行上下文。</param>
|
|
/// <exception cref="InvalidOperationException">
|
|
/// 声明目标版本不匹配、版本未前进或超出运行时版本时抛出。
|
|
/// </exception>
|
|
private static void ValidateMigrationResult<TData, TMigration>(
|
|
int currentVersion,
|
|
int targetVersion,
|
|
int migratedVersion,
|
|
int declaredTargetVersion,
|
|
in MigrationExecutionContext<TData, TMigration> context)
|
|
where TData : class
|
|
{
|
|
if (declaredTargetVersion != migratedVersion)
|
|
{
|
|
throw new InvalidOperationException(
|
|
$"{context.MigrationKind} for {context.SubjectName} declared target version {declaredTargetVersion} " +
|
|
$"but returned version {migratedVersion}.");
|
|
}
|
|
|
|
if (migratedVersion <= currentVersion)
|
|
{
|
|
throw new InvalidOperationException(
|
|
$"{context.MigrationKind} for {context.SubjectName} must advance beyond version {currentVersion}.");
|
|
}
|
|
|
|
if (migratedVersion > targetVersion)
|
|
{
|
|
throw new InvalidOperationException(
|
|
$"{context.MigrationKind} for {context.SubjectName} produced version {migratedVersion}, " +
|
|
$"which exceeds the current runtime version {targetVersion}.");
|
|
}
|
|
}
|
|
}
|