Galosys.Foundation.Core 26.8.18.1

Galosys.Foundation.Core

成熟度: 🟢 稳定 — 生产可用，测试充分，活跃维护

Galosys.Foundation 核心库，提供统一响应模型、DDD 实体基类、扩展方法、安全加密、消息总线、模块化机制等基础能力。

特性一览

领域	功能
统一响应	UnifiedResponse 成功/失败/异常/处理中
DDD 实体	Entity / FullEntity / TenantEntity / AppEntity + 领域事件
ID 生成	Snowflake、LocalGenerator、Nanoid、Ulid、Uuid
分页	PageOutput、PageQuery 分页查询基类
消息	事件订阅/发布、IMessageBus + Outbox 引擎
COLA 架构	Executor 模板方法、ExtensionPoint 扩展点、PluginRegistry
Resilience 弹性	重试/熔断/超时/隔离/限流/降级（Polly 实现）
State Machine	三泛型状态机 + Builder DSL + 持久化
Rules Engine	规则引擎 + 构建器 + 回退链
分布式锁	IDistributedLock 抽象 + 内存实现
分布式幂等	IDistributedIdempotence 接口
告警	IAlarmer 告警日志基础设施
AI 集成	通义千问 Embedding
Excel 操作	IXlsHelper 流式读/写/模板填充
数据结构	BloomFilter、WorkerPool、ChannelTemplate、责任链
工具类	Env、ServiceLocator、Poco、Tree、ITimeProvider、数据脱敏、签名等
模块化	编译时 SourceGen + 运行时双模式模块发现
DI 上下文	ITenantContext / IAppContext / IUserContext

---

1. 统一响应模型

// 成功响应
var response = UnifiedResponse.Succeed(data, "操作成功");

// 失败响应
var response = UnifiedResponse.Fail("ERROR_CODE", "操作失败");

// 异常响应
var response = UnifiedResponse.Error("ERROR_CODE", exception);

// 处理中
var response = UnifiedResponse.Processing("PROCESSING_CODE");

---

2. 实体与 DDD 模式

// 完整实体（含创建者、修改者、软删除）
public class User : FullEntity<long>
{
    public string Name { get; set; }
}

// 基础实体
public class Entity
{
    public IReadOnlyCollection<ApplicationMessage> DomainEvents { get; }
    protected void AddEvent(ApplicationMessage @event) { }
}

实体基类矩阵

Entity (abstract, 领域事件)
  └── Entity<TID> (abstract, [Key, SnowflakeId] Id)
       ├── FullEntity<TID> (abstract, IDeletable + ICreator + ILastModifier)
       │    ├── TenantEntity<TID>      : FullEntity<TID>, IMultiTenancy
       │    ├── AppEntity<TID>         : FullEntity<TID>, IMultiApplication
       │    └── TenantAppEntity<TID>   : FullEntity<TID>, IMultiTenancy, IMultiApplication

基类	适用场景	示例
FullEntity<TID>	全局基础数据，不分租户和应用	地区、字典、系统配置
TenantEntity<TID>	仅分租户	用户、角色、权限
AppEntity<TID>	仅分应用	菜单、API 接口
TenantAppEntity<TID>	租户 + 应用	租户应用配置

实体可混入 IConcurrency 实现乐观并发控制：

public class SysUser : TenantEntity<long>, IConcurrency
{
    [Timestamp]
    public byte[] RowVersion { get; protected set; } = null!;
}

---

3. ID 生成

// 雪花算法 ID
var id = SnowflakeIdGenerator.Instance.NextId();

// 本地 ID 发生器
var id = LocalGenerator.NextId();
var couponKey = LocalGenerator.NextCouponKey();
var seqKey = LocalGenerator.NextSeqKey();
var guid = LocalGenerator.NextGuid();

此外支持多种 ID 策略（通过特性标注实体字段）：

[Nanoid]      // Nanoid 字符串 ID
[Ulid]        // ULID 有序唯一标识
[Uuid]        // UUID 标识

---

4. 分页

var pageResult = PageOutput.Of(items, total, page, size);

---

5. 单例模式

// 线程安全的延迟初始化单例
var instance = Singleton<MyService>.GetInstance();

// 使用 Lazy<T> 的单例
var instance = LazySingleton<MyService>.Instance;

---

6. 消息订阅/发布

// 发布消息
await publisher.PublishAsync(new UserCreatedEvent(this));

// 订阅消息
public class UserCreatedListener : ApplicationListener<UserCreatedEvent>
{
    public override Task<bool> HandleAsync(UserCreatedEvent e)
    {
        return Task.FromResult(true);
    }
}

---

7. 扩展方法

// DateTime 扩展
var lastDay = dt.LastDayInMonth();
var firstDay = dt.FirstDayInMonth();
var isWeekend = dt.IsWeekend();
var workDate = dt.AddWorkDays(3);
var unixMs = dt.ToUnixTimeMilliseconds();
var unixSec = dt.ToUnixTimeSeconds();
var datetime = timestamp.ToDateTime();

// String 扩展
var compressed = "content".ToGZipCompress();
var decompressed = compressed.ToGZipDecompress();

// Object 扩展
var result = obj.GetAsyncResult<Task<string>>();

// IQueryable 扩展
queryable.WhereIf(condition, x => x.IsActive)
         .Page(pageIndex, pageSize);

// 集合扩展
list.Shuffle();
list.TopologicalSort(selector);
list.Slice(5);
list.BinaryInsertSort(item, comparer);

---

8. 安全加密

// MD5 加密
var hashed = SecurityTemplate.Md5Encrypt(original);

// DES 加解密
var encrypted = SecurityTemplate.DesEncrypt(original);
var decrypted = SecurityTemplate.DesDecrypt(encrypted);

// AES 加解密
var encrypted = SecurityTemplate.AesEncrypt(original, key);
var decrypted = SecurityTemplate.AesDecrypt(encrypted, key);

// RSA 加解密
var encrypted = SecurityTemplate.RSAEncrypt(original, publicKey);
var decrypted = SecurityTemplate.RSADecrypt(encrypted, privateKey);

// 许可证生成与验证
var license = SecurityTemplate.GenerateLicense(info);
var valid = SecurityTemplate.ValidateLicense(license);

---

9. 动态代理

class HttpProxy : ServiceProxy
{
    protected override void Proceed(InvocationContext context)
    {
        var http = context.ServiceProvider.GetRequiredService<IHttpClientFactory>().CreateClient();
        context.SetReturnValue(http.GetStringAsync("/posts/1"));
    }
}

var instance = ServiceProxyFactory.CreateProxy(typeof(ITypicodeClient), typeof(HttpProxy), sp) as ITypicodeClient;

---

10. 进程管理

// 启动进程
var p = new Process().Start("cmd.exe", runAsAdministrator: true);

// 打开浏览器
p = new Process().Browser("https://example.com");

// 打开资源管理器
p = new Process().Explore("c://");

// 执行脚本
p = new Process().Script("dotnet.exe", "info");

---

11. HTTP 客户端

services.AddHttpClient<IPlaceholderGateway, PlaceholderGateway>(http =>
{
    http.BaseAddress = new Uri("https://jsonplaceholder");
}).AddServiceDiscovery()
  .AddStandardHedgingHandler();

---

12. 验证码生成

var code = Random.Shared.GenerateCaptcha();   // 验证码
var sms = Random.Shared.GenerateSms();         // 短信验证码

---

13. 应用程序启动器

public class MyRunner : IApplicationRunner
{
    public int Order => 0;
    public async Task RunAsync(ApplicationArguments args) { }
}

---

14. PluginRegistry（插件注册表）

基于策略路由模式的基础设施，根据请求自动匹配对应插件实现。适用于短信网关、支付渠道、物流商等多 provider 场景。

public interface ISmsPlugin : Plugin<SmsRequest>
{
    Task SendAsync(SmsRequest request);
}

internal class AliyunSmsPlugin : ISmsPlugin
{
    public bool Supports(SmsRequest request) => request.Provider == "aliyun";
    public Task SendAsync(SmsRequest request) { /* ... */ }
}

// DI 注册
services.AddTransient<ISmsPlugin, AliyunSmsPlugin>();

// 使用
var registry = serviceProvider.GetRequiredService<PluginRegistry<ISmsPlugin, SmsRequest>>();
var plugin = registry.GetPluginFor(request);
await plugin.SendAsync(request);

模式	行为
GetPluginFor	单匹配 — 返回第一个匹配插件
GetAllPluginsFor	多匹配 — 返回所有匹配插件（广播场景）
PluginResolutionMode.Scoped	默认，创建新 DI Scope
PluginResolutionMode.Singleton	从根容器直接获取

---

15. Executor 模板方法

提供命令执行管道，按顺序执行：前置钩子 → 参数校验 → 业务逻辑 → 后置钩子，统一返回 UnifiedResponse。

// 注册
services.AddCola();

// 定义命令
public class OrderCreateCmd : CommandBase
{
    public string OrderNo { get; set; }
    public override ValidationResult Validate() { /* ... */ }
}

// 实现 Executor
public class OrderCreateExecutor : ExecutorBase<OrderCreateCmd>
{
    protected override UnifiedResponse DoExecute(OrderCreateCmd command)
    {
        return UnifiedResponse.Succeed(new { OrderId = Guid.NewGuid() });
    }
}

阶段	方法	说明
前置钩子	OnBeforeExecute	记录日志，可重写
参数校验	command.Validate()	失败返回 VALIDATION_ERROR
业务逻辑	DoExecute / DoExecuteAsync	子类必须实现
后置钩子	OnAfterExecute	记录日志，可重写
业务异常	HandleBusinessException	捕获 BizException
系统异常	HandleSystemException	返回 SYSTEM_ERROR

---

16. ExtensionPoint（扩展点机制）

基于 COLA 架构的扩展点模式，通过 BizScenario（业务身份）路由到不同的扩展点实现。

public interface IPaymentStrategy : IExtensionPoint
{
    Task<PaymentResult> PayAsync(PaymentRequest request);
}

[Extension(BizId = "default", UseCase = "default", Scenario = "wechat")]
public class WechatPaymentStrategy : IPaymentStrategy { /* ... */ }

// 使用
var scenario = BizScenario.ValueOf("default", "default", paymentType);
var result = await executor.ExecuteAsync<IPaymentStrategy, PaymentResult>(
    scenario, svc => svc.PayAsync(request));

匹配降级策略：精确匹配 → 场景通配 → 用例通配 → 全局默认。

支持批量执行（ExecuteAll / ExecuteAllAsync）和归约（ReduceAsync）。

---

17. PageQuery（分页查询基类）

var query = new PageQuery
{
    PageIndex = 2,
    PageSize = 10,
};
query.SetOrderDirection("ASC");
int offset = query.Offset; // 10

属性	说明	默认
PageIndex	页码（最小1）	1
PageSize	每页大小（最小1）	10
Offset	偏移量（只读）	(PageIndex-1)*PageSize
OrderDirection	排序方向	"DESC"

---

18. MessageBus + Outbox 引擎

提供 IMessageBus 统一消息入口（Send + Publish），以及 Transactional Outbox 模式保证业务事务与消息发送的原子性。

// 进程内默认总线
await bus.PublishAsync("order.created", order);

// 实现消息处理器
public class OrderCreatedHandler : IMessageHandler<OrderCreatedEvent>
{
    public Task<bool> HandleAsync(OrderCreatedEvent msg) { /* ... */ }
}

// DI 注册
services.AddScoped<IMessageHandler<OrderCreatedEvent>, OrderCreatedHandler>();

Outbox 模式： PendingMsgCol 收集待发送消息，DbContext.DrainPendingOutbox() 在 SaveChanges 时同事务写入 base_outbox_msg 表（列名 snake_case），后台 OutboxRelay 轮询投递。

性能优化（Phase 2）： OutboxMessage 新增 Version 字段支持乐观锁，IOutboxStore 新增 TryAcquireBatchAsync / MarkManySentAsync / MarkManyFailedAsync 批量 API，OutboxRelay 改为 TryAcquireBatch → Parallel.ForEachAsync（DOP=4）→ MarkMany 流水线，吞吐目标 200-500/s。

services.AddRabbitMessageBus(options => {
    options.EnableOutbox = true;
    options.Outbox.DefaultMode = "Outboxed"; // 默认走 outbox
});
services.AddEfCoreOutboxStore<MyDbContext>();

配置项	默认值	说明
EnableOutbox	true	全局 outbox 开关
TableName	"base_outbox_msg"	发件箱表名（列名 snake_case）
SchemaName	"base"	数据库 schema
DefaultMode	"Outboxed"	路由默认策略："Outboxed"=走 outbox，"Direct"=直发
MaxRetryCount	3	最大重试次数（0=不限）
BatchSize	500	每次轮询拉取数
PollIntervalMs	500	轮询间隔（ms）
RetentionDays	7	已发送消息保留天数

组件	说明
IMessageBus	统一消息入口
PendingMsgCol	AsyncLocal 消息收集器
OutboxSaveChangesInterceptor	EF Core 保存拦截器
OutboxRelay	后台轮询投递服务
OrphanedCleanupService	孤儿消息清理
OutboxMeter	OpenTelemetry 指标（含 outbox.orphaned.total 未落库丢弃计数）

OutboxMeter 指标一览：

指标名	类型	说明
outbox.sent.total	Counter	累计发送成功数
outbox.failed.total	Counter	累计发送失败数
outbox.retry.exhausted	Counter	重试耗尽丢弃数
outbox.orphaned.total	Counter	累计未落库丢弃数 — PublishAsync 后未调 SaveChanges 导致消息丢失时递增
outbox.scan.duration	Histogram	单次轮询耗时（ms）
outbox.pending.count	ObservableGauge	待发送消息数

---

19. 上下文服务（DI）

框架内置 ITenantContext、IAppContext、IUserContext 三个 Singleton 上下文服务，基于 AsyncLocal<T> 实现请求级隔离。

public class MyService
{
    public MyService(ITenantContext tenant, IAppContext app, IUserContext user) { }
}

---

20. Resilience 弹性管道

Microsoft.Extensions.Resilience — 基于 Polly 的弹性管道，支持命名管道配置。

// 注册
services.AddResilience();

// 使用命名管道
var pipeline = provider.GetRequiredService<IResiliencePipelineProvider>()
    .GetPipeline("my-service");

await pipeline.ExecuteAsync(async ct =>
{
    return await httpClient.GetAsync("api/data", ct);
});

支持策略： Retry（重试）、CircuitBreaker（熔断）、Timeout（超时）、Bulkhead（隔离）、RateLimiter（限流）、Fallback（降级）。

{
  "Resilience": {
    "Pipelines": {
      "my-service": {
        "Retry": { "MaxRetryAttempts": 3, "BackoffType": "Exponential" },
        "CircuitBreaker": { "FailureThreshold": 0.5, "SamplingDuration": "00:01:00" },
        "Timeout": { "TimeoutInterval": "00:00:10" }
      }
    }
  }
}

类	说明
IResiliencePipeline	弹性管道接口
IResiliencePipelineBuilder	管道构建器（链式配置策略）
IResiliencePipelineProvider	命名管道提供者
PollyResiliencePipeline	Polly 实现

---

21. State Machine 状态机

Microsoft.Extensions.StateMachine — 三泛型 IStateMachine<S, E, C> 通用状态机，支持 Builder DSL、拦截器、监听器、持久化。

// 注册
services.AddStateMachine();

// 定义状态机
var machine = stateMachineFactory.Create<OrderState, OrderEvent, OrderContext>(builder =>
{
    builder.InitialState(OrderState.Pending)
        .From(OrderState.Pending)
            .On(OrderEvent.Submit).To(OrderState.Confirmed).Perform(ctx => HandleSubmit(ctx))
        .From(OrderState.Confirmed)
            .On(OrderEvent.Ship).To(OrderState.Shipped)
        .From(OrderState.Shipped)
            .On(OrderEvent.Deliver).To(OrderState.Completed);
});

// 触发转换
var result = await machine.FireAsync(OrderEvent.Submit, context);

类	说明
IStateMachine<S,E,C>	状态机接口
IStateMachineFactory	状态机工厂
IStateMachineInterceptor	状态转换拦截器
IStateMachineListener	状态转换监听器
IStateMachinePersister	状态持久化（默认内存）

---

22. Rules Engine 规则引擎

Microsoft.Extensions.Rules — 规则定义、构建、执行、事件监听与回退链。

// 注册
services.AddRules();

// 定义规则
[Rule(Name = "VipDiscount", Priority = 1)]
public class VipDiscountRule : IRuleEntity
{
    public RuleExecuteResult Execute(RuleDefinition rule, object context)
    {
        var order = (OrderContext)context;
        if (order.UserLevel == "VIP")
            return RuleExecuteResult.Success(new { Discount = 0.9 });
        return RuleExecuteResult.Skip();
    }
}

// 执行
var engine = provider.GetRequiredService<IRuleEngine>();
var result = await engine.ExecuteAsync("order.discount", orderContext);

类	说明
IRuleEngine	规则引擎接口
RuleBuilder	规则构建器
RuleDefinition	规则定义
FallbackChain	参数回退链
IRuleEventListener	规则事件监听器

---

23. Distributed Lock 分布式锁

Microsoft.Extensions.Locking.Distributed — 分布式锁抽象，内置内存实现。

// 注册
services.AddDistributedLock();

// 使用
var handle = await distributedLock.TryAcquireAsync("lock:order:123");
if (handle != null)
{
    try { /* 临界区 */ }
    finally { await handle.ReleaseAsync(); }
}

类	说明
IDistributedLock	分布式锁接口
IDistributedLockHandle	锁句柄
InMemoryDistributedLock	内存实现（用于开发和测试）

---

24. Distributed Idempotence 分布式幂等

Microsoft.Extensions.Idempotence — 分布式幂等性控制。

// 注册
services.AddIdempotence();

// 使用
var result = await idempotence.TryExecuteAsync("order:submit:123", async () =>
{
    return await orderService.SubmitAsync(order);
});

类	说明
IDistributedIdempotence	幂等性控制接口
InMemoryDistributedIdempotence	内存实现

---

25. Alarming 告警

Microsoft.Extensions.Alarming — 告警日志基础设施。

// 注册
services.AddAlarmer();

// 使用
alarmer.Alarm("数据库连接超时", new { Db = "OrderDb", Timeout = 30 });

类	说明
IAlarmer	告警器接口
Alarmer	告警器抽象基类
AlarmLogger	告警日志实现

---

26. AI 集成

Microsoft.Extensions.AI — 配置驱动的 AI 客户端 + RAG 能力。

26.1 注册

// 从 appsettings.json 读取 AI:Chat / AI:Embedding 配置
services.AddAI(configuration);

26.2 配置文件

"AI": {
  "Chat": {
    "Qwen":       { "Provider": "OpenAI",    "Endpoint": "", "ApiKey": "", "ModelId": "" },
    "DeepSeek":   { "Provider": "Anthropic",  "Endpoint": "", "ApiKey": "", "ModelId": "" },
    "Local":      { "Provider": "Ollama",     "Endpoint": "", "ApiKey": null, "ModelId": "" }
  },
  "Embedding": {
    "Qwen":       { "Provider": "Qwen",       "Endpoint": "", "ApiKey": "", "ModelId": "" },
    "OpenAI":     { "Provider": "OpenAI",     "Endpoint": "", "ApiKey": "", "ModelId": "" }
  }
}

26.3 Chat 调用

// 通过 key 获取对应 ChatClient
var qwen = services.GetRequiredKeyedService<IChatClient>("Qwen");

// 每次调用可设置不同 SystemPrompt
var response = await qwen.GetResponseAsync(
    [new(ChatRole.System, "你现在是一个英语翻译助手"),
     new(ChatRole.User, "你好")]);

26.4 Embedding 调用

var gen = services.GetRequiredKeyedService<IEmbeddingGenerator<string, Embedding<float>>>("Qwen");
var embeddings = await gen.GenerateAsync(["文本1", "文本2"]);

26.5 RAG（检索增强生成）

使用 UseRag() 前需先注册 VectorStore 实现（如 InMemory、Qdrant 等）：

// 注册 VectorStore（自行选择实现）
services.AddSingleton<VectorStore>(sp => new MyVectorStore(...));

// 通过管道注册全局 RAG
services.AddChatClient(builder => builder
    .UseRag(configure: o => { o.Mode = RagMode.Simple; o.TopK = 3; })
    .Use(new OpenAIClient(apiKey)).AsChatClient("gpt-4"));

// 调用时动态控制
var response = await chatClient.GetResponseAsync(
    [new(ChatRole.User, "公司的年度目标是什么？")],
    new ChatOptions
    {
        AdditionalProperties = new()
        {
            ["rag_collection"] = "company_docs"
        }
    });

26.6 使用支持的 Chat Client

Provider	说明	实现方式
OpenAI（Chat+Embedding）	OpenAI 兼容 API（含 Qwen/Azure）	meai.openai 官方包
Anthropic（Chat）	Anthropic Claude	AnthropicClient SDK 包装
Ollama（Chat，扩展包）	本地 Ollama	OllamaSharp
Qwen（Embedding）	通义千问 Embedding	内置 QwenEmbeddingGenerator

26.7 Chat 层中间件（护栏 / 压缩）

AddAI 为每个配置创建的 IChatClient 自动装配默认中间件管线，顺序为 UseOpenTelemetry → UseLogging → UseDistributedCache → UseCompaction → UseOutputGuardrail → [可选的 UseFunctionInvocation]。缺 DI 依赖（ILoggerFactory / IDistributedCache / 护栏 / 压缩服务）的中间件自动跳过。

开关位于 AIProviderOptions（Enable*，逐 provider 生效），默认值：EnableOpenTelemetry=true、EnableLogging=true、EnableDistributedCache=false（需应用注册 IDistributedCache）、EnableFunctionInvocation=false（防与 MAF agent 工具循环冲突）、EnableCompaction=true、EnableOutputGuardrail=true。

"AI": {
  "Chat": {
    "Qwen": { "Provider": "OpenAI", "Endpoint": "", "ApiKey": "", "ModelId": "",
              "EnableDistributedCache": true }
  }
}

也可在独立 IChatClient 上显式装配中间件（护栏/压缩原语位于 Microsoft.Extensions.AI 命名空间）：

// 护栏：注册评估器链（TryAdd 语义，可覆盖）
services.AddOutputGuardrail(o => o.BlockedKeywords = ["机密"]);
// 压缩：注册选项
services.AddCompaction(o => o.MaxMessages = 32);

// 在 ChatClientBuilder 上显式挂载
services.AddChatClient(builder => builder
    .UseCompaction(o => o.Strategy = CompactionStrategy.Truncate)
    .UseOutputGuardrail(sp)
    .Use(new OpenAIClient(apiKey)).AsChatClient("gpt-4"));

类型	说明
OutputGuardrailChatClient / UseOutputGuardrail	输出护栏中间件，命中敏感词抛 OutputGuardrailException
CompactionChatClient / UseCompaction / CompactionOptions	对话压缩中间件，超限截断或摘要
AddOutputGuardrail / AddCompaction	护栏 / 压缩 DI 注册
IOutputGuardrailEvaluator、RuleBasedOutputGuardrail、IPiiDetector、IPiiRedactor 等	护栏/PII 原语（自 Galosys.Foundation.Agents.AI 下沉，无 MAF 依赖）

---

27. Excel 操作

IXlsHelper — 流式读取、流式写入、模板填充，支持列映射和自定义转换。

// 注册
services.AddXlsHelper();

// 流式读取
var records = xlsHelper.ExtractAsync<OrderDto>(stream, options);

// 流式写入
await xlsHelper.WriteAsync(stream, orders, options);

// 模板填充
await xlsHelper.FillAsync(templateStream, outputStream, data, options);

类	说明
IXlsHelper	Excel 操作接口
IXlsWriter<T>	流式写入器
IXlsSheetWriter<T>	工作表写入器
XlsColumnAttribute	列映射特性
XlsSheetAttribute	工作表映射特性
AbstractXlsAppService	Excel 应用服务基类

---

28. Responsibility Chain 责任链

public class ValidationHandler : AbstractChainHandler<OrderContext>
{
    public override async Task HandleAsync(OrderContext context, Func<Task> next)
    {
        if (context.IsValid)
            await next();
    }
}

// 执行
await chainClient.ExecuteAsync(context);

---

29. 数据结构

BloomFilter

var filter = new BloomFilter<string>(expectedItems: 100000, falsePositiveRate: 0.01);
filter.Add("item1");
bool exists = filter.Contains("item1"); // true

WorkerPool

// 注册
services.AddWorkerPool();

// 使用
await workerPool.EnqueueAsync(async ct => { /* 工作任务 */ }, cancellationToken);

实现	说明
TaskWorkerPool	基于 Task 的工作池
ThreadWorkerPool	基于 Thread 的工作池

ChannelTemplate

var channel = new ChannelTemplate<string>(capacity: 100);
await channel.Writer.WriteAsync("data");
var item = await channel.Reader.ReadAsync();

---

30. 工具类

Env — 环境检测

Env.IsKubernetes;        // 是否在 K8s 中运行
Env.MachineIP;           // 本机 IP 地址
Env.MachineName;         // 主机名
Env.IsDevelopment();     // 是否开发环境

ServiceLocator — 服务定位器

var service = ServiceLocator.GetService<IMyService>();

Poco — DTO 基类

public class UserDto : Poco
{
    public string Name { get; set; }
}
var clone = original.Clone();

ITreeNode — 树形结构

var tree = TreeNodeHelper.BuildTree(nodes);
var flat = TreeNodeHelper.Flatten(tree);

ITimeProvider — 时间提供者

public class MyService
{
    public MyService(ITimeProvider time) { }
    // 测试时可注入 mock 时间
}

数据脱敏

public class UserDto
{
    [DataMask(MaskType.Partial)]
    public string Phone { get; set; } // 138****1234
}

API 签名

var signature = SignUtils.GenerateSign(parameters, secretKey);
var valid = SignUtils.VerifySign(parameters, secretKey, signature);

二倍均值算法（红包分配）

var amounts = Bma.Divide(totalAmount: 100, count: 5);

命名帮助

var queue = Naming.Queue("order");     // 队列命名
var topic = Naming.Topic("order");     // 主题命名
var key = Naming.Key("order:123");     // Key 命名

Enumeration — 智能枚举

public class OrderStatus : Enumeration<OrderStatus>
{
    public static readonly OrderStatus Pending = new(1, "待处理");
    public static readonly OrderStatus Completed = new(2, "已完成");
}

---

31. DI 服务注册

// 核心注册（模块化、消息总线、消息发布等）
// 幂等：模块路径（UseModularization）与显式路径共存时不重复注册
services.AddCore();

// COLA 架构
services.AddCola(typeof(MyCommand).Assembly);

// 消息总线 + Outbox
services.AddMessageBus();
services.AddOutbox();

// 弹性管道
services.AddResilience();

// 状态机
services.AddStateMachine();

// 规则引擎
services.AddRules();

// 分布式锁
services.AddDistributedLock();

// 分布式幂等
services.AddIdempotence();

// 告警
services.AddAlarmer();

// Excel 操作
services.AddXlsHelper();

// AI 集成（读取 appsettings.json 的 AI 节）
services.AddAI(configuration);

// 服务发现
services.AddServiceDiscovery();

// 健康检查（自动发现 [HealthCheck] 属性探针 + 内置 ResourceUtilization/Lifecycle）
services.AddHealthChecksAll();

// 自动扫描注册
// 排除依赖测试 SDK（xunit/NUnit/MSTest 等）的程序集，宿主与集成包照常扫描
services.AddScannable();

---

32. 目录结构

Galosys.Foundation.Core/
├── Galosys\Foundation\Core\
│   ├── ModuleDescriptor.cs
│   ├── Executor/                  # COLA Executor 模板方法
│   ├── ExtensionPoint/            # COLA ExtensionPoint 扩展点
│   └── Xls/                       # Excel 操作
├── Microsoft\Extensions\
│   ├── AI/                        # AI 集成（通义千问）
│   ├── Alarming/                  # 告警基础设施
│   ├── Configuration/             # 配置绑定扩展
│   ├── DependencyInjection/       # DI 注册 + 模块化系统
│   ├── Diagnostics/               # 诊断 + Metrics
│   ├── Hosting/                   # HostBuilder 扩展
│   ├── Idempotence/               # 分布式幂等
│   ├── Locking/Distributed/       # 分布式锁
│   ├── MessageBus/                # 消息总线 + Outbox 引擎 (renamed from Messaging)
│   ├── Options/                   # 配置选项类
│   ├── Resilience/                # 弹性管道
│   ├── Rules/                     # 规则引擎
│   ├── StateMachine/              # 状态机
│   └── MessageBus/                # 消息总线
├── System\
│   ├── BloomFilter.cs             # 布隆过滤器
│   ├── ChannelTemplate.cs         # Channel 消息管道模板
│   ├── DateTimeExtensions.cs
│   ├── Env.cs                     # 环境检测
│   ├── Enumeration.cs             # 智能枚举
│   ├── Naming.cs                  # 命名帮助
│   ├── Poco.cs                    # DTO 基类
│   ├── ServiceLocator.cs          # 服务定位器
│   ├── Security/Cryptography/     # 加密算法
│   ├── StringExtensions.cs
│   └── WorkerPool/                # 工作池
└── System\Text\Json\Serialization\
    └── DataMaskConverter.cs       # 数据脱敏

33. 测试

Outbox 测试覆盖

测试文件	组件	用例数
InMemoryOutboxStoreTests	InMemoryOutboxStore	14
OutboxRelayTests	OutboxRelay 后台轮询	6
MessageBusOutboxTests	MessageBus outbox 路径	4
PendingMsgColTests	PendingMsgCol AsyncLocal 收集器	3

# 运行 outbox 存储层测试
dotnet test framework/test/Galosys.Foundation.Core.Tests/ --filter "FullyQualifiedName~InMemoryOutboxStoreTests"

# 运行 outbox 服务层测试
dotnet test framework/test/Galosys.Foundation.Core.Tests/ --filter "FullyQualifiedName~OutboxRelay"
dotnet test framework/test/Galosys.Foundation.Core.Tests/ --filter "FullyQualifiedName~MessageBusOutbox"

---

34. 依赖

• Microsoft.Extensions.Caching.Abstractions / Memory
• Microsoft.Extensions.DependencyInjection
• Microsoft.Extensions.DependencyModel
• Microsoft.Extensions.Diagnostics.HealthChecks
• Microsoft.Extensions.Hosting
• Microsoft.Extensions.Http
• Microsoft.Extensions.ObjectPool
• Polly.Core
• System.Threading.RateLimiting

Outbox 引擎零新增依赖，复用已有 Microsoft.Extensions.Hosting / DI。