Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
7 changes: 6 additions & 1 deletion .editorconfig
Original file line number Diff line number Diff line change
Expand Up @@ -12,10 +12,15 @@ dotnet_diagnostic.GFX0020.severity = error
dotnet_diagnostic.GFX0021.severity = error

# Hotfix Wrapper 源码生成器诊断(GameFrameX.Hotfix.WrapperGenerator/Utils/Logger.cs 分配):
# GFW 前缀与分析器 GFX0001-0021 错开;GFW0001=契约违规(Error)、GFW0002=契约警示(Warning),可按 ID 抑制或升级
# GFW 前缀与分析器 GFX0001-0022 错开;GFW0001=契约违规(Error)、GFW0002=契约警示(Warning),可按 ID 抑制或升级
dotnet_diagnostic.GFW0001.severity = error
dotnet_diagnostic.GFW0002.severity = warning

# 静态便捷层过渡标注(GameDb/GameEventDispatcher/HotfixManager/PlayerSessionManager/ConfigComponent 的
# [Obsolete] 指向注入面):仓内存量调用点约数百处,迁移由后续收敛阶段分批完成;仓内构建把 CS0618
# 降为 none 保持告警基线不变,nupkg 消费方仍见完整 Obsolete 文案(迁移信标不失真)。
dotnet_diagnostic.CS0618.severity = none

# PB 库(vendored 生态移植,不按本仓风格改造,整目录排除)
[GameFrameX.ProtoBuf.Net/**.cs]
csharp_prefer_braces = true:none
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
// ==========================================================================================
// GameFrameX 组织及其衍生项目的版权、商标、专利及其他相关权利
// GameFrameX organization and its derivative projects' copyrights, trademarks, patents, and related rights
// 均受中华人民共和国及相关国际法律法规保护。
// are protected by the laws of the People's Republic of China and relevant international regulations.
// 使用本项目须严格遵守相应法律法规与开源许可证之规定。
// Usage of this project must strictly comply with applicable laws, regulations, and open-source licenses.
// 本项目采用 Apache License 2.0 单协议分发,
// This project is licensed solely under the Apache License 2.0,
// 完整许可证文本请参见源代码根目录下的 LICENSE 文件。
// please refer to the LICENSE file in the root directory of the source code for the full license text.
// 禁止利用本项目实施任何危害国家安全、破坏社会秩序、
// It is prohibited to use this project to engage in any activities that endanger national security, disrupt social order,
// 侵犯他人合法权益等法律法规所禁止的行为!
// or infringe upon the legitimate rights and interests of others as prohibited by laws and regulations!
// 因基于本项目二次开发所产生的一切法律纠纷与责任,
// Any legal disputes or liabilities arising from secondary development based on this project
// 本组织与贡献者概不承担。
// shall be borne solely by the developer; the project organization and contributors assume no responsibility.
// GitHub 仓库:https://github.com/GameFrameX
// GitHub Repository: https://github.com/GameFrameX
// Gitee 仓库:https://gitee.com/GameFrameX
// Gitee Repository: https://gitee.com/GameFrameX
// CNB 仓库:https://cnb.cool/GameFrameX
// CNB Repository: https://cnb.cool/GameFrameX
// 官方文档:https://gameframex.doc.alianblank.com/
// Official Documentation: https://gameframex.doc.alianblank.com/
// ==========================================================================================

namespace GameFrameX.Capability.Hosting.Abstractions;

/// <summary>
/// 宿主基础设施模块的激活相位(组合选项的 <c>AddHostModule</c> 声明):
/// 机制在依赖拓扑定序时为相位注入合成定序边——<see cref="BeforeCapabilities"/> 模块先于全部能力模块激活,
/// <see cref="AfterCapabilities"/> 模块晚于全部能力模块与全部 Before 模块激活;停用一律按激活逆序。
/// <para>
/// 维护约束:合成边只参与定序,不进入服务解析来源策略(<c>AllowedOwnersByConsumer</c>)——
/// 宿主模块与能力模块之间的服务可见性仍由 <c>Requires</c> / <c>Optional</c> 显式声明决定。
/// </para>
/// </summary>
public enum CapabilityHostModulePhase
{
/// <summary>
/// 早段宿主模块:在全部能力模块激活之前激活(承载旧栈早段固定序列,如数据库初始化、发现层激活、组件注册、热更装载)。
/// </summary>
BeforeCapabilities = 0,

/// <summary>
/// 晚段宿主模块:在全部能力模块与全部早段宿主模块激活之后激活(承载依赖能力桥就绪的收尾序列,如网络监听开放、ServiceOnline 分发)。
/// </summary>
AfterCapabilities = 1,
}
140 changes: 137 additions & 3 deletions Capability/GameFrameX.Capability.Hosting.Core/CapabilityComposition.cs
Original file line number Diff line number Diff line change
Expand Up @@ -37,11 +37,19 @@ namespace GameFrameX.Capability.Hosting.Core;
/// 编排责任全部收回机制层)。
/// <para>
/// 维护约束(机制开放红线):机制包零能力硬编码——第二个能力族只需提供 <see cref="ICapabilityFamily"/>
/// 实现,机制零改动;装配问题逐条打日志后抛汇总异常(一次报全);业务面与管理面至少启用其一。
/// 实现,机制零改动;装配问题逐条打日志后抛汇总异常(一次报全);业务面与管理面至少启用其一;
/// 宿主基础设施模块(<see cref="CapabilityCompositionOptions.AddHostModule"/>)与能力模块进入同一宿主,
/// 由机制统一拓扑定序与启停——组合根唯一,不承认任何静态组合面。
/// </para>
/// </summary>
public static class CapabilityComposition
{
/// <summary>
/// 无族组合(宿主基础设施模块 only)的族标识占位:服务覆盖与解析来源标记使用,
/// 不对应任何部署扫描面或配置段。
/// </summary>
internal const string HostOnlyFamilyId = "host";

/// <summary>
/// 组合一个能力族(族基建 → 宿主覆盖 → 部署目录扫描 → 同 Id 校验 → 过滤 → 依赖检查 → 定序 →
/// Options 合并 → Register → 宿主 / 管理面 / 报告)。
Expand Down Expand Up @@ -96,8 +104,8 @@ public static CapabilityRuntime Compose(ICapabilityFamily family, CapabilityComp
CapabilityHost host;
try
{
var modules = CapabilityAssembly.DiscoverFromDeploymentDirectory(family.DeploymentAssemblyPrefix);
host = builder.Build(modules);
var discoveredModules = CapabilityAssembly.DiscoverFromDeploymentDirectory(family.DeploymentAssemblyPrefix);
host = builder.Build(MergeHostModules(discoveredModules, options));
}
catch (CapabilityAssemblyException exception)
{
Expand Down Expand Up @@ -131,4 +139,130 @@ public static CapabilityRuntime Compose(ICapabilityFamily family, CapabilityComp

return new CapabilityRuntime(options.EnableRuntime ? host : null, adminApiPlane, host.Report);
}

/// <summary>
/// 无族组合(宿主基础设施模块 only):不执行族基建注册、部署目录扫描、管理面组装与成功报告渲染,
/// 仅把 <see cref="CapabilityCompositionOptions.HostModules"/> 组装为业务宿主——供未启用任何能力族的
/// 进程 / Role 承载宿主侧固定启停序列(组合根仍唯一收敛于机制)。
/// <para>
/// 维护约束:至少声明一个宿主模块;<c>EnableRuntime</c> 必须为 true(无族形态无管理面可退);
/// 管理面工厂不得设置(管理面属族组合产物,需与 <see cref="ICapabilityFamily"/> 同用)。
/// </para>
/// </summary>
/// <param name="options">组合选项(须含至少一个宿主模块)。</param>
/// <returns>业务宿主组合产物(管理面为 null)。</returns>
public static CapabilityRuntime Compose(CapabilityCompositionOptions options)
{
if (options == null)
{
throw new ArgumentNullException(nameof(options));
}

if (options.HostModules.Count == 0)
{
// Localization: Capability.Hosting.Composition.HostModulesRequired - 无族组合缺少宿主模块。
throw new InvalidOperationException(LocalizationService.GetString(Localization.Keys.Capability.Hosting.Composition.HostModulesRequired));
}

if (options.AdminApiPlaneFactory != null)
{
// Localization: Capability.Hosting.Composition.AdminApiPlaneRequiresFamily - 管理面工厂需与能力族同用。
throw new InvalidOperationException(LocalizationService.GetString(Localization.Keys.Capability.Hosting.Composition.AdminApiPlaneRequiresFamily));
}

if (!options.EnableRuntime)
{
// Localization: Capability.Hosting.Composition.NoPlaneEnabled - 未启用任何能力面。
throw new InvalidOperationException(LocalizationService.GetString(Localization.Keys.Capability.Hosting.Composition.NoPlaneEnabled));
}

if (options.HostOptions == null)
{
options.HostOptions = new CapabilityHostOptions();
}

if (!options.HostOptions.IsValid())
{
// Localization: Capability.Hosting.OptionsInvalid - 能力宿主选项非法(作用域三元组 / 调度间隔)。
throw new InvalidOperationException(LocalizationService.GetString(Localization.Keys.Capability.Hosting.OptionsInvalid));
}

var services = new CapabilityServices();
services.SetFamilyCapabilityId(HostOnlyFamilyId);
var eventBus = new CapabilityEventBus(options.AssemblyLog);

var overrideEntries = options.OverrideEntries;
for (var i = 0; i < overrideEntries.Count; i++)
{
var entry = overrideEntries[i];
services.AddOverride(new CapabilityServiceRegistration(entry.ServiceType, string.Empty, entry.Factory, HostOnlyFamilyId, true));
}

var builder = new CapabilityHostBuilder(services, eventBus, new HostOnlyCapabilityFamily(), options);
var hostModules = new List<ICapabilityModule>(options.HostModules.Count);
for (var i = 0; i < options.HostModules.Count; i++)
{
hostModules.Add(options.HostModules[i].Module);
}

var host = builder.Build(hostModules);
return new CapabilityRuntime(host, null, host.Report);
}

/// <summary>
/// 合并宿主基础设施模块到发现序模块表(宿主模块追加于尾部;同 Id 查重在装配表构建时统一执行)。
/// </summary>
/// <param name="discoveredModules">部署目录发现的能力模块。</param>
/// <param name="options">组合选项(宿主模块来源)。</param>
/// <returns>合并后的模块表。</returns>
private static IReadOnlyList<ICapabilityModule> MergeHostModules(IReadOnlyList<ICapabilityModule> discoveredModules, CapabilityCompositionOptions options)
{
if (options.HostModules.Count == 0)
{
return discoveredModules;
}

var merged = new List<ICapabilityModule>(discoveredModules.Count + options.HostModules.Count);
for (var i = 0; i < discoveredModules.Count; i++)
{
merged.Add(discoveredModules[i]);
}

for (var i = 0; i < options.HostModules.Count; i++)
{
merged.Add(options.HostModules[i].Module);
}

return merged;
}

/// <summary>
/// 无族组合的占位族(族标识 / 配置段名 / 部署前缀均为宿主占位语义;不注册任何族基建)。
/// </summary>
private sealed class HostOnlyCapabilityFamily : ICapabilityFamily
{
/// <summary>获取族标识(宿主占位)。</summary>
public string FamilyId
{
get { return HostOnlyFamilyId; }
}

/// <summary>获取配置段名(宿主占位;错误路径前缀不出现)。</summary>
public string ConfigurationSectionName
{
get { return "Host"; }
}

/// <summary>获取部署程序集前缀(占位值;无族组合不执行部署扫描)。</summary>
public string DeploymentAssemblyPrefix
{
get { return "GameFrameX.Host"; }
}

/// <summary>无族基建可注册(空实现)。</summary>
/// <param name="context">族基建注册面(不使用)。</param>
public void RegisterInfrastructure(CapabilityFamilyContext context)
{
}
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@
namespace GameFrameX.Capability.Hosting.Core;

/// <summary>
/// 能力组合选项(<see cref="CapabilityComposition.Compose"/> 的唯一配置面:族配置段 + 装配日志出口 +
/// 能力组合选项(<see cref="CapabilityComposition.Compose(ICapabilityFamily, CapabilityCompositionOptions)"/> 的唯一配置面:族配置段 + 装配日志出口 +
/// 双面开关 + 宿主选项 + 代码层 Options 覆盖与服务覆盖 + 管理面工厂)。
/// <para>
/// 维护约束(GFX0018 符号检查面):<see cref="Configure{TOptions}"/> / <see cref="Override{TService}(TService)"/> /
Expand All @@ -52,6 +52,11 @@ public sealed class CapabilityCompositionOptions
/// </summary>
private readonly List<OverrideEntry> _overrideEntries = new();

/// <summary>
/// 宿主基础设施模块(相位声明;注册序落表)。
/// </summary>
private readonly List<HostModuleEntry> _hostModules = new();

/// <summary>
/// 管理面工厂(由 Hosting.AdminApi 包的 UseAdminApi 扩展设置)。
/// </summary>
Expand Down Expand Up @@ -104,6 +109,34 @@ public CapabilityCompositionOptions(JsonElement familyConfigurationSection, ICap
/// </summary>
public ICapabilitySchedulerObserver SchedulerObserver { get; set; }

/// <summary>
/// 获取宿主基础设施模块表(机制装配期读取)。
/// </summary>
internal IReadOnlyList<HostModuleEntry> HostModules
{
get { return _hostModules; }
}

/// <summary>
/// 声明一个宿主基础设施模块:与能力模块进入同一宿主参与统一拓扑定序与生命周期——
/// <see cref="CapabilityHostModulePhase.BeforeCapabilities"/> 先于全部能力模块激活,
/// <see cref="CapabilityHostModulePhase.AfterCapabilities"/> 晚于全部能力模块激活;停用按激活逆序。
/// <para>维护约束:宿主模块不受 <see cref="Filter"/> 影响(恒启用);其 <c>Requires</c> 只允许引用
/// 其它已在模块表中的能力 Id;同一 Id 重复声明 = 装配失败。</para>
/// </summary>
/// <param name="module">宿主模块实例(不可为 null)。</param>
/// <param name="phase">激活相位。</param>
public void AddHostModule(ICapabilityModule module, CapabilityHostModulePhase phase)
{
if (module == null)
{
throw new ArgumentNullException(nameof(module));
}

_hostModules.Add(new HostModuleEntry(module, phase));
}


/// <summary>
/// 声明代码层 Options 覆盖(只改需要改的字段;合并优先级:包内默认 &lt; 配置段 &lt; 代码 Configure)。
/// </summary>
Expand Down Expand Up @@ -236,4 +269,32 @@ public OverrideEntry(Type serviceType, Func<CapabilityServiceResolver, object> f
/// </summary>
public Func<CapabilityServiceResolver, object> Factory { get; }
}

/// <summary>
/// 宿主基础设施模块条目(模块 + 激活相位)。
/// </summary>
internal sealed class HostModuleEntry
{
/// <summary>
/// 初始化 <see cref="HostModuleEntry"/>。
/// </summary>
/// <param name="module">宿主模块。</param>
/// <param name="phase">激活相位。</param>
public HostModuleEntry(ICapabilityModule module, CapabilityHostModulePhase phase)
{
Module = module;
Phase = phase;
}

/// <summary>
/// 获取宿主模块。
/// </summary>
public ICapabilityModule Module { get; }

/// <summary>
/// 获取激活相位。
/// </summary>
public CapabilityHostModulePhase Phase { get; }
}
}

Loading
Loading