AstraFlow README

项目的 README,来自 github.com/seifmoustafa/AstraFlow。合并为一个 markdown 文件:README.md。

AstraFlow

AstraFlow — Engineered Clarity

A modular .NET suite of 16 focused packages for explicit request dispatch, object mapping, query projections, compile-time analyzers, source generators, diagnostics, observability, and test workflows. Install only the packages your application needs and keep optional integrations isolated.

Getting Started · Package Selection · Version & Upgrade Guide · Compatibility · Changelog · Branding

Release status & support policy: The 2.4.x line includes the standalone AstraFlow.Assertions package, expanded compile-time mapping generation, and read-only CLI assertion migration analysis. The 2.4.1 patch fixed the package README image on NuGet.org; 2.4.2 through 2.4.4 add compile-tested assertion migration compatibility, with 2.4.4 extending formatted failure reasons and case-insensitive string containment checks. Check NuGet.org for the latest package version before pinning it. All 1.x packages are deprecated — use the 2.x line.


Packages (16)

Category Package Targets Role
Core AstraFlow netstandard2.0, net8.0, net9.0, net10.0 Convenience umbrella for AstraFlow.Contracts, AstraFlow.Mediator, and AstraFlow.Mapper
Core AstraFlow.Contracts netstandard2.0, net8.0, net9.0, net10.0 Lightweight mediator abstractions (IRequest, INotification, streams, pipelines) with zero runtime dependencies
Core AstraFlow.Mediator netstandard2.0, net8.0, net9.0, net10.0 Request/command/stream dispatch, notifications, pipeline behaviors, processors, scanning, and handler coverage validation
Core AstraFlow.Mapper netstandard2.0, net8.0, net9.0, net10.0 Explicit object mapping catalogs, startup validation, named projections, and secure ID abstractions
Core AstraFlow.Mapper.Conventions netstandard2.0, net8.0, net9.0, net10.0 Opt-in convention mapping with deterministic plans, strict validation, and sensitive-field safeguards
Core AstraFlow.Security netstandard2.0, net8.0, net9.0, net10.0 Shared sensitive-name classification and redaction policy primitives
Core AstraFlow.Diagnostics netstandard2.0, net8.0, net9.0, net10.0 Framework-neutral JSON and Markdown registration and validation reports
Tooling AstraFlow.Analyzers netstandard2.0 (analyzer) Build-time Roslyn diagnostics for mediator, mapper, and projection contracts
Tooling AstraFlow.Generators netstandard2.0 (generator) Compile-time mediator/mapper metadata plus opt-in typed mapping generation ([AstraGenerateMapping])
Tooling AstraFlow.Cli net10.0 (.NET tool) CLI inspect, validate, report, diff, Mermaid/Canvas graphs, and read-only assertion migration scan (expanded in 2.4.0)
Integrations AstraFlow.AspNetCore net10.0 Minimal APIs, controllers, problem details, diagnostics endpoints, and health summaries
Integrations AstraFlow.FluentValidation net8.0, net9.0, net10.0 Validation pipeline behaviors (fail-fast and aggregate errors), localization hooks, and diagnostics
Integrations AstraFlow.OpenTelemetry net8.0, net9.0, net10.0 Production-safe ActivitySource tracing and Meter metrics with default redaction
Integrations AstraFlow.Mapper.EntityFrameworkCore net10.0 Optional EF Core queryable projection translation validation
Testing AstraFlow.Testing netstandard2.0, net8.0, net9.0, net10.0 Framework-neutral test fakes, recording harnesses, and flow test helpers
Testing AstraFlow.Assertions netstandard2.0, net8.0, net9.0, net10.0 Standalone, runner-neutral general-purpose assertions with zero production package dependencies

See the Package Selection Guide for boundary rules and dependency isolation guarantees (AstraFlow.Mapper never pulls EF Core; AstraFlow.Mediator never pulls FluentValidation or OpenTelemetry).


Install AstraFlow

Install the umbrella convenience package when a project uses both mediator and explicit mapping:

dotnet add package AstraFlow

For cleaner layer boundaries, reference only what each assembly needs:

# Shared domain/API contracts library (no runtime dependency)
dotnet add package AstraFlow.Contracts

# Application layer packages
dotnet add package AstraFlow.Mediator
dotnet add package AstraFlow.Mapper

AstraFlow.Assertions ships as a standalone package starting in 2.4.0. Add it to test projects that need general-purpose assertions; it is not included by the AstraFlow convenience package.


Dispatch a request

Register the assembly containing your handlers, resolve ISender, and dispatch typed requests with explicit cancellation flow:

using System;
using System.Threading;
using System.Threading.Tasks;
using AstraFlow;
using AstraFlow.Mediator;
using Microsoft.Extensions.DependencyInjection;

var services = new ServiceCollection();
services.AddAstraFlow(assemblyMarkerTypes: typeof(CreateOrderHandler));

await using var serviceProvider = services.BuildServiceProvider();
var sender = serviceProvider.GetRequiredService<ISender>();
using var cancellationTokenSource = new CancellationTokenSource();

OrderCreated result = await sender.Send(
    new CreateOrder("ORD-1042"),
    cancellationTokenSource.Token);

public sealed record CreateOrder(string Number) : IRequest<OrderCreated>;

public sealed record OrderCreated(Guid Id, string Number);

public sealed class CreateOrderHandler : IRequestHandler<CreateOrder, OrderCreated>
{
    public Task<OrderCreated> Handle(
        CreateOrder request,
        CancellationToken cancellationToken)
    {
        return Task.FromResult(new OrderCreated(Guid.NewGuid(), request.Number));
    }
}

Use ISender, IPublisher, or IStreamSender when a consumer needs only one slice of the mediator contract. Missing or duplicate request handlers fail explicitly during startup validation.

See Getting Started, the Mediator Guide, and Mediator Scenarios.


Mapping, projections, and source generation

See the Mapper Guide, Projection Guide, Convention Mapping Guide, Generators Guide, and Analyzers Guide.


Testing and assertions

AstraFlow.Testing ships test fakes and harnesses for mediator pipelines, mapping catalogs, projections, diagnostics, and secure ID codecs on 2.3.0.

AstraFlow.Assertions (targeting 2.4.0) adds a zero-dependency, test-runner-neutral assertion package covering:

using AstraFlow.Assertions; // Available in 2.4.0

response.StatusCode.Should().Be(201);
items.Should().ContainSingle(item => item.Id == expectedId);

Func<Task> save = () => service.SaveAsync();
await save.Should().NotThrowAsync();

See the Testing Guide and Assertions Guide for full signatures, target matrix, and caveats.


Upgrading and 1.x deprecation policy

See the Version and Upgrade Guide, Migration Cookbook, and Changelog.


Target frameworks

Check Compatibility before installing integration packages into multi-targeted libraries.


Documentation map

Topic Guides
Onboarding & Packages Getting Started · Package Selection · Architecture · API Reference · Compatibility
Mediator & Integrations Mediator · Mediator Scenarios · ASP.NET Core · FluentValidation · OpenTelemetry
Mapper, Generators & CLI Mapper · Mapper Scenarios · Projections · Projection Scenarios · Conventions · EF Core · Generators · Analyzers · CLI
Diagnostics, Security & Tests Diagnostics · Endpoint Safety · Security · Testing · Assertions (2.4.0) · Benchmarks
Upgrades & Troubleshooting Version & Upgrade Guide · Migration Cookbook · Troubleshooting · Branding
Roadmap & Governance Roadmap · Decision Log · API Governance · Security & Supply Chain · Security Policy · Contributing · Support · MIT License

Build, test, and pack from source

dotnet build AstraFlow.slnx --configuration Release
dotnet test AstraFlow.slnx --configuration Release --no-build
.\scripts\pack.ps1

For release verification, SourceLink, reproducibility, and NuGet publishing rules, see the Release Checklist, Publishing Guide, and Community Release Guide. Note that NuGet package READMEs require absolute raw GitHub URLs matching the target release tag/branch before packing for NuGet.org.

AstraFlow (seifmoustafa/AstraFlow)

正在搜索数据库…

这是什么?AstraFlow 是一套模块化的 .NET 工具集,包含 16 个功能单一的包,用于显式的请求分发、对象映射、查询投影、编译时分析器、源代码生成器、诊断、可观测性和测试工作流。
它是框架还是库?它是一组 NuGet 库,而不是单一框架。你只需安装应用所需的包,并将可选集成隔离开来。
它支持哪些 .NET 版本?核心包面向 netstandard2.0 以及 net8.0 至 net10.0。ASP.NET Core 和 EF Core 集成需要 net10.0,CLI 是一个面向 net10.0 的 .NET 工具。
1.x 版本还能用吗?不能。所有 1.x 包在 NuGet.org 上均已弃用,因此新项目和现有项目都应使用 2.x 版本线。在固定版本之前,请到 NuGet.org 查看最新的 2.x 版本。
编译时生成器究竟会生成什么?选择启用的 [AstraGenerateMapping] 方法会在编译时生成带类型的映射。2.4.0 版本将其扩展到继承的公共属性、Guid 与时间相关的标量类型、位置记录(positional records)、主构造函数 DTO 以及仅初始化(init-only)的初始化器。
AstraFlow CLI 能做什么?AstraFlow.Cli .NET 工具可以检查、验证、报告和比较注册项,并导出 Mermaid 或 Canvas 图表。它还能运行只读扫描,用于断言迁移。
2.4.x 版本线有哪些新内容?2.4.x 版本线新增了独立的 AstraFlow.Assertions 包、扩展的编译时映射生成功能,以及只读的 CLI 断言迁移分析。
大小
42.8 MB
星标
664
时长
6个月
提交 · 90 天