Skip to content

feat(config): 添加AI-First配置系统及源生成器 #168

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
GeWuYou merged 3 commits into from
Apr 3, 2026
Merged

feat(config): 添加AI-First配置系统及源生成器 #168

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
48fd8a2
feat(config): 添加AI-First配置系统及源生成器
GeWuYou Apr 3, 2026
3bca639
feat(config): 添加JSON schema配置生成器
GeWuYou Apr 3, 2026
76479eb
refactor(GFramework.SourceGenerators): 添加全局命名空间引用以支持代码生成
GeWuYou Apr 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 29 additions & 1 deletion GFramework.SourceGenerators.Tests/Config/SchemaConfigGeneratorSnapshotTests.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ namespace GFramework.SourceGenerators.Tests.Config;
public class SchemaConfigGeneratorSnapshotTests
{
/// <summary>
/// 验证一个最小 monster schema 能生成配置类型和表包装。
/// 验证一个最小 monster schema 能生成配置类型、表包装和注册辅助。
/// </summary>
[Test]
public async Task Snapshot_SchemaConfigGenerator()
Expand All @@ -35,6 +35,32 @@ public interface IConfigTable<TKey, TValue> : IConfigTable
bool ContainsKey(TKey key);
IReadOnlyCollection<TValue> All();
}

public interface IConfigRegistry
{
IConfigTable<TKey, TValue> GetTable<TKey, TValue>(string name)
where TKey : notnull;

bool TryGetTable<TKey, TValue>(string name, out IConfigTable<TKey, TValue>? table)
where TKey : notnull;
}
}

namespace GFramework.Game.Config
{
public sealed class YamlConfigLoader
{
public YamlConfigLoader RegisterTable<TKey, TValue>(
string tableName,
string relativePath,
string schemaRelativePath,
Func<TValue, TKey> keySelector,
IEqualityComparer<TKey>? comparer = null)
where TKey : notnull
{
return this;
}
}
}
""";

Expand Down Expand Up @@ -130,6 +156,8 @@ public interface IConfigTable<TKey, TValue> : IConfigTable

await AssertSnapshotAsync(generatedSources, snapshotFolder, "MonsterConfig.g.cs", "MonsterConfig.g.txt");
await AssertSnapshotAsync(generatedSources, snapshotFolder, "MonsterTable.g.cs", "MonsterTable.g.txt");
await AssertSnapshotAsync(generatedSources, snapshotFolder, "MonsterConfigBindings.g.cs",
"MonsterConfigBindings.g.txt");
}

/// <summary>
Expand Down
89 changes: 89 additions & 0 deletions ...SourceGenerators.Tests/Config/snapshots/SchemaConfigGenerator/MonsterConfigBindings.g.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,89 @@
// <auto-generated />
#nullable enable

namespace GFramework.Game.Config.Generated;

/// <summary>
/// Auto-generated registration and lookup helpers for schema file 'monster.schema.json'.
/// The helper centralizes table naming, config directory, schema path, and strongly-typed registry access so consumer projects do not need to duplicate the same conventions.
/// </summary>
public static class MonsterConfigBindings
{
/// <summary>
/// Gets the runtime registration name of the generated config table.
/// </summary>
public const string TableName = "monster";

/// <summary>
/// Gets the config directory path expected by the generated registration helper.
/// </summary>
public const string ConfigRelativePath = "monster";

/// <summary>
/// Gets the schema file path expected by the generated registration helper.
/// </summary>
public const string SchemaRelativePath = "schemas/monster.schema.json";

/// <summary>
/// Registers the generated config table using the schema-derived runtime conventions.
/// </summary>
/// <param name="loader">The target YAML config loader.</param>
/// <param name="comparer">Optional key comparer for the generated table registration.</param>
/// <returns>The same loader instance so registration can keep chaining.</returns>
public static global::GFramework.Game.Config.YamlConfigLoader RegisterMonsterTable(
this global::GFramework.Game.Config.YamlConfigLoader loader,
global::System.Collections.Generic.IEqualityComparer<int>? comparer = null)
{
if (loader is null)
{
throw new global::System.ArgumentNullException(nameof(loader));
}

return loader.RegisterTable<int, MonsterConfig>(
TableName,
ConfigRelativePath,
SchemaRelativePath,
static config => config.Id,
comparer);
}

/// <summary>
/// Gets the generated config table wrapper from the registry.
/// </summary>
/// <param name="registry">The source config registry.</param>
/// <returns>The generated strongly-typed table wrapper.</returns>
/// <exception cref="global::System.ArgumentNullException">When <paramref name="registry"/> is null.</exception>
public static MonsterTable GetMonsterTable(this global::GFramework.Game.Abstractions.Config.IConfigRegistry registry)
{
if (registry is null)
{
throw new global::System.ArgumentNullException(nameof(registry));
}

return new MonsterTable(registry.GetTable<int, MonsterConfig>(TableName));
}

/// <summary>
/// Tries to get the generated config table wrapper from the registry.
/// </summary>
/// <param name="registry">The source config registry.</param>
/// <param name="table">The generated strongly-typed table wrapper when lookup succeeds; otherwise null.</param>
/// <returns>True when the generated table is registered and type-compatible; otherwise false.</returns>
/// <exception cref="global::System.ArgumentNullException">When <paramref name="registry"/> is null.</exception>
public static bool TryGetMonsterTable(this global::GFramework.Game.Abstractions.Config.IConfigRegistry registry, out MonsterTable? table)
{
if (registry is null)
{
throw new global::System.ArgumentNullException(nameof(registry));
}

if (registry.TryGetTable<int, MonsterConfig>(TableName, out var innerTable) && innerTable is not null)
{
table = new MonsterTable(innerTable);
return true;
}

table = null;
return false;
}
}
174 changes: 170 additions & 4 deletions GFramework.SourceGenerators/Config/SchemaConfigGenerator.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,3 @@
using System.Globalization;
using System.IO;
using System.Text;
using System.Text.Json;
using GFramework.SourceGenerators.Diagnostics;

namespace GFramework.SourceGenerators.Config;
Expand Down Expand Up @@ -41,6 +37,9 @@ public void Initialize(IncrementalGeneratorInitializationContext context)
productionContext.AddSource(
$"{result.Schema.TableName}.g.cs",
SourceText.From(GenerateTableClass(result.Schema), Encoding.UTF8));
productionContext.AddSource(
$"{result.Schema.EntityName}ConfigBindings.g.cs",
SourceText.From(GenerateBindingsClass(result.Schema), Encoding.UTF8));
});
}

Expand Down Expand Up @@ -128,12 +127,18 @@ private static SchemaParseResult ParseSchema(
idProperty.TypeSpec.SchemaType));
}

var schemaBaseName = GetSchemaBaseName(file.Path);
var schema = new SchemaFileSpec(
Path.GetFileName(file.Path),
entityName,
schemaObject.ClassName,
$"{entityName}Table",
GeneratedNamespace,
idProperty.TypeSpec.ClrType.TrimEnd('?'),
idProperty.PropertyName,
schemaBaseName,
schemaBaseName,
GetSchemaRelativePath(file.Path),
TryGetMetadataString(root, "title"),
TryGetMetadataString(root, "description"),
schemaObject);
Expand Down Expand Up @@ -607,6 +612,131 @@ private static string GenerateTableClass(SchemaFileSpec schema)
return builder.ToString().TrimEnd();
}

/// <summary>
/// 生成运行时注册与访问辅助源码。
/// 该辅助类型把 schema 命名约定、配置目录和 schema 相对路径固化为生成代码，
/// 让消费端无需重复手写字符串常量和主键提取逻辑。
/// </summary>
/// <param name="schema">已解析的 schema 模型。</param>
/// <returns>辅助类型源码。</returns>
private static string GenerateBindingsClass(SchemaFileSpec schema)
{
var registerMethodName = $"Register{schema.EntityName}Table";
var getMethodName = $"Get{schema.EntityName}Table";
var tryGetMethodName = $"TryGet{schema.EntityName}Table";
var bindingsClassName = $"{schema.EntityName}ConfigBindings";

var builder = new StringBuilder();
builder.AppendLine("// <auto-generated />");
builder.AppendLine("#nullable enable");
builder.AppendLine();
builder.AppendLine($"namespace {schema.Namespace};");
builder.AppendLine();
builder.AppendLine("/// <summary>");
builder.AppendLine(
$"/// Auto-generated registration and lookup helpers for schema file '{schema.FileName}'.");
builder.AppendLine(
"/// The helper centralizes table naming, config directory, schema path, and strongly-typed registry access so consumer projects do not need to duplicate the same conventions.");
builder.AppendLine("/// </summary>");
builder.AppendLine($"public static class {bindingsClassName}");
builder.AppendLine("{");
builder.AppendLine(" /// <summary>");
builder.AppendLine(" /// Gets the runtime registration name of the generated config table.");
builder.AppendLine(" /// </summary>");
builder.AppendLine(
$" public const string TableName = {SymbolDisplay.FormatLiteral(schema.TableRegistrationName, true)};");
builder.AppendLine();
builder.AppendLine(" /// <summary>");
builder.AppendLine(" /// Gets the config directory path expected by the generated registration helper.");
builder.AppendLine(" /// </summary>");
builder.AppendLine(
$" public const string ConfigRelativePath = {SymbolDisplay.FormatLiteral(schema.ConfigRelativePath, true)};");
builder.AppendLine();
builder.AppendLine(" /// <summary>");
builder.AppendLine(" /// Gets the schema file path expected by the generated registration helper.");
builder.AppendLine(" /// </summary>");
builder.AppendLine(
$" public const string SchemaRelativePath = {SymbolDisplay.FormatLiteral(schema.SchemaRelativePath, true)};");
builder.AppendLine();
builder.AppendLine(" /// <summary>");
builder.AppendLine(
" /// Registers the generated config table using the schema-derived runtime conventions.");
builder.AppendLine(" /// </summary>");
builder.AppendLine(" /// <param name=\"loader\">The target YAML config loader.</param>");
builder.AppendLine(
" /// <param name=\"comparer\">Optional key comparer for the generated table registration.</param>");
builder.AppendLine(" /// <returns>The same loader instance so registration can keep chaining.</returns>");
builder.AppendLine(
$" public static global::GFramework.Game.Config.YamlConfigLoader {registerMethodName}(");
builder.AppendLine(" this global::GFramework.Game.Config.YamlConfigLoader loader,");
builder.AppendLine(
$" global::System.Collections.Generic.IEqualityComparer<{schema.KeyClrType}>? comparer = null)");
builder.AppendLine(" {");
builder.AppendLine(" if (loader is null)");
builder.AppendLine(" {");
builder.AppendLine(" throw new global::System.ArgumentNullException(nameof(loader));");
builder.AppendLine(" }");
builder.AppendLine();
builder.AppendLine(
$" return loader.RegisterTable<{schema.KeyClrType}, {schema.ClassName}>(");
builder.AppendLine(" TableName,");
builder.AppendLine(" ConfigRelativePath,");
builder.AppendLine(" SchemaRelativePath,");
builder.AppendLine($" static config => config.{schema.KeyPropertyName},");
builder.AppendLine(" comparer);");
builder.AppendLine(" }");
builder.AppendLine();
builder.AppendLine(" /// <summary>");
builder.AppendLine(" /// Gets the generated config table wrapper from the registry.");
builder.AppendLine(" /// </summary>");
builder.AppendLine(" /// <param name=\"registry\">The source config registry.</param>");
builder.AppendLine(" /// <returns>The generated strongly-typed table wrapper.</returns>");
builder.AppendLine(
" /// <exception cref=\"global::System.ArgumentNullException\">When <paramref name=\"registry\"/> is null.</exception>");
builder.AppendLine(
$" public static {schema.TableName} {getMethodName}(this global::GFramework.Game.Abstractions.Config.IConfigRegistry registry)");
builder.AppendLine(" {");
builder.AppendLine(" if (registry is null)");
builder.AppendLine(" {");
builder.AppendLine(" throw new global::System.ArgumentNullException(nameof(registry));");
builder.AppendLine(" }");
builder.AppendLine();
builder.AppendLine(
$" return new {schema.TableName}(registry.GetTable<{schema.KeyClrType}, {schema.ClassName}>(TableName));");
builder.AppendLine(" }");
builder.AppendLine();
builder.AppendLine(" /// <summary>");
builder.AppendLine(" /// Tries to get the generated config table wrapper from the registry.");
builder.AppendLine(" /// </summary>");
builder.AppendLine(" /// <param name=\"registry\">The source config registry.</param>");
builder.AppendLine(
" /// <param name=\"table\">The generated strongly-typed table wrapper when lookup succeeds; otherwise null.</param>");
builder.AppendLine(
" /// <returns>True when the generated table is registered and type-compatible; otherwise false.</returns>");
builder.AppendLine(
" /// <exception cref=\"global::System.ArgumentNullException\">When <paramref name=\"registry\"/> is null.</exception>");
builder.AppendLine(
$" public static bool {tryGetMethodName}(this global::GFramework.Game.Abstractions.Config.IConfigRegistry registry, out {schema.TableName}? table)");
builder.AppendLine(" {");
builder.AppendLine(" if (registry is null)");
builder.AppendLine(" {");
builder.AppendLine(" throw new global::System.ArgumentNullException(nameof(registry));");
builder.AppendLine(" }");
builder.AppendLine();
builder.AppendLine(
$" if (registry.TryGetTable<{schema.KeyClrType}, {schema.ClassName}>(TableName, out var innerTable) && innerTable is not null)");
builder.AppendLine(" {");
builder.AppendLine($" table = new {schema.TableName}(innerTable);");
builder.AppendLine(" return true;");
builder.AppendLine(" }");
builder.AppendLine();
builder.AppendLine(" table = null;");
builder.AppendLine(" return false;");
builder.AppendLine(" }");
builder.AppendLine("}");
return builder.ToString().TrimEnd();
}

/// <summary>
/// 递归生成配置对象类型。
/// </summary>
Expand Down Expand Up @@ -773,6 +903,32 @@ private static string GetSchemaBaseName(string path)
return Path.GetFileNameWithoutExtension(fileName);
}

/// <summary>
/// 解析生成注册辅助时要使用的 schema 相对路径。
/// 生成器优先保留 `schemas/` 目录以下的相对路径，以便消费端默认约定和 MSBuild AdditionalFiles 约定保持一致。
/// </summary>
/// <param name="path">Schema 文件路径。</param>
/// <returns>用于运行时注册的 schema 相对路径。</returns>
private static string GetSchemaRelativePath(string path)
{
var normalizedPath = path.Replace('\\', '/');
const string rootMarker = "schemas/";
const string nestedMarker = "/schemas/";

if (normalizedPath.StartsWith(rootMarker, StringComparison.OrdinalIgnoreCase))
{
return normalizedPath;
}

var nestedMarkerIndex = normalizedPath.LastIndexOf(nestedMarker, StringComparison.OrdinalIgnoreCase);
if (nestedMarkerIndex >= 0)
{
return normalizedPath.Substring(nestedMarkerIndex + 1);
}

return $"schemas/{Path.GetFileName(path)}";
}

/// <summary>
/// 将 schema 名称转换为 PascalCase 标识符。
/// </summary>
Expand Down Expand Up @@ -996,19 +1152,29 @@ public static ParsedObjectResult FromDiagnostic(Diagnostic diagnostic)
/// 生成器级 schema 模型。
/// </summary>
/// <param name="FileName">Schema 文件名。</param>
/// <param name="EntityName">实体名基础标识。</param>
/// <param name="ClassName">根配置类型名。</param>
/// <param name="TableName">配置表包装类型名。</param>
/// <param name="Namespace">目标命名空间。</param>
/// <param name="KeyClrType">主键 CLR 类型。</param>
/// <param name="KeyPropertyName">生成配置类型中的主键属性名。</param>
/// <param name="TableRegistrationName">运行时注册名。</param>
/// <param name="ConfigRelativePath">配置目录相对路径。</param>
/// <param name="SchemaRelativePath">Schema 文件相对路径。</param>
/// <param name="Title">根标题元数据。</param>
/// <param name="Description">根描述元数据。</param>
/// <param name="RootObject">根对象模型。</param>
private sealed record SchemaFileSpec(
string FileName,
string EntityName,
string ClassName,
string TableName,
string Namespace,
string KeyClrType,
string KeyPropertyName,
string TableRegistrationName,
string ConfigRelativePath,
string SchemaRelativePath,
string? Title,
string? Description,
SchemaObjectSpec RootObject);
Expand Down
6 changes: 5 additions & 1 deletion GFramework.SourceGenerators/GlobalUsings.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,4 +20,8 @@
global using Microsoft.CodeAnalysis;
global using Microsoft.CodeAnalysis.CSharp.Syntax;
global using Microsoft.CodeAnalysis.CSharp;
global using Microsoft.CodeAnalysis.Text;
global using Microsoft.CodeAnalysis.Text;
global using System.Globalization;
global using System.IO;
global using System.Text;
global using System.Text.Json;
Loading
Loading