快速上手

目标:5 分钟起一个可运行的 Loom 微服务——从实体、端点、校验到 EF SQLite 持久化; 其余面按需查“按面参考”。

1. 一条命令脚手架

dotnet new install KernLab.Loom.Templates
dotnet new loom-service -n MyService
cd MyService
dotnet run --urls http://127.0.0.1:5088

默认生成 WebApplication + AddLoomEf(SQLite)+ AddLoomEndpoints + AddLoomUow + Validation, 纯 PackageReference 消费者形态(无 ProjectReference 到 src/),与 samples/MinimalService 同源。

选项 作用
--client 加 [HttpApi] 声明式客户端 + AddLoomHttpClient,并生成 /client-check 真 HTTP 往返端点
--query 在实体字段上 [Filterable],GET /orders?Filter=Qty gt 1 走 DSL 过滤
--aot PublishAot + LoomAotMode 骨架(部署前用 DDL/迁移 bundle 替代 EnsureCreated)
--framework net10.0 EF10 腿(缺省 net8.0 = EF8 腿)
--loom-version <版本> 固定包版本(本地开发可配合本地 feed 的 NuGet.config)

2. 最小可运行服务(模板同源)

完整可运行源码:samples/MinimalService。

2.1 包引用(只教消费者形态)

<PackageReference Include="KernLab.Loom.Abstractions" Version="1.0.0-rc.2" />
<PackageReference Include="KernLab.Loom.Ef" Version="1.0.0-rc.2" />
<PackageReference Include="KernLab.Loom.Ef.Runtime" Version="1.0.0-rc.2" />
<PackageReference Include="KernLab.Loom.Endpoints" Version="1.0.0-rc.2" />
<PackageReference Include="KernLab.Loom.Validation" Version="1.0.0-rc.2" />
<PackageReference Include="Microsoft.EntityFrameworkCore.Sqlite" Version="8.0.11" />
  • 不要 ProjectReference 到 src/;PackageReference 时生成器包自动落 analyzers/ 并自动 Import build/ props。
  • 本地开发:先 dotnet pack 到本地 feed,再用固定版本(见 sample 的 NuGet.config);正式部署用 nuget.org 固定版本。

2.2 工程属性

<PropertyGroup>
  <TargetFramework>net8.0</TargetFramework>
  <!-- EF handler 注入 scoped DbContext 时必须 Scoped;缺省 Singleton 会 captive -->
  <LoomEndpointsServiceLifetime>Scoped</LoomEndpointsServiceLifetime>
</PropertyGroup>

2.3 完整最小服务

using System.ComponentModel.DataAnnotations;
using KernLab.Loom.Ef;
using KernLab.Loom.Ef.Runtime;
using KernLab.Loom.Ef.Runtime.Uow;
using KernLab.Loom.Endpoints;
using Loom.Generated;                       // AddLoomEndpoints / MapLoomEndpoints 在这里
using Microsoft.EntityFrameworkCore;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddLoomEf<AppDbContext>(o => o.UseSqlite("Data Source=min.db"));
builder.Services.AddLoomUow(o => o.Engage<AppDbContext>());
builder.Services.AddLoomEndpoints();

var app = builder.Build();
using (var scope = app.Services.CreateScope())
{
    // demo:EnsureCreated;生产改迁移/DDL(AOT 边界见持久化主线)
    scope.ServiceProvider.GetRequiredService<AppDbContext>().Database.EnsureCreated();
}

app.MapLoomEndpoints();
app.Run();

[EfEntity(typeof(AppDbContext), Key = EfKeyStrategy.Identity)]
public sealed class Order
{
    public long Id { get; set; }
    public string Sku { get; set; } = "";
    public int Qty { get; set; }
}

// 上下文必须 partial;生成器会发 DbSet(手写会 CS0102)
public sealed partial class AppDbContext(DbContextOptions<AppDbContext> options)
    : LoomDbContext(options), ILoomUowParticipant;

public sealed record OrderView(long Id, string Sku, int Qty);

[EndpointCommand("orders")]
public sealed record CreateOrder : IEndpointCommand<OrderView>
{
    [Required, StringLength(40, MinimumLength = 2)] public string Sku { get; init; } = "";
    [Range(1, 100)] public int Qty { get; init; }
}

[EndpointQuery("orders/{id}")]
public sealed record GetOrder(long Id) : IEndpointQuery<OrderView>;

public sealed class OrderEndpoints(AppDbContext db)
{
    public async Task<OrderView> CreateAsync(CreateOrder cmd, CancellationToken ct)
    {
        var order = new Order { Sku = cmd.Sku, Qty = cmd.Qty };
        db.Orders.Add(order);
        await db.SaveChangesAsync(ct);
        return new OrderView(order.Id, order.Sku, order.Qty);
    }

    public async Task<OrderView?> GetAsync(GetOrder query, CancellationToken ct)
    {
        var order = await db.Orders.AsNoTracking().FirstOrDefaultAsync(o => o.Id == query.Id, ct);
        return order is null ? null : new OrderView(order.Id, order.Sku, order.Qty);
    }
}

2.4 运行与输出

dotnet run --project samples/MinimalService --urls http://127.0.0.1:5088

curl -X POST http://127.0.0.1:5088/orders -H 'Content-Type: application/json' -d '{"sku":"SKU-1","qty":2}'
# 200 {"id":1,"sku":"SKU-1","qty":2}
curl http://127.0.0.1:5088/orders/1
# 200 {"id":1,"sku":"SKU-1","qty":2}
curl -X POST http://127.0.0.1:5088/orders -H 'Content-Type: application/json' -d '{"sku":"X","qty":0}'
# 400 application/problem+json(Sku/Qty 字段错误)

3. 按面参考

每个片段的完整可运行版本见对应 sample/文档;Quickstart 不再维护孤立占位片段。

面 入口 参考
Wire 线编码 [WireMessage] / [WireMessageTag] / [WireMember] Wire 文档 · sample samples/Wire
Layout 二进制布局 [BinaryLayout] + [StructLayout] Layout 文档 · sample samples/Layout
Endpoints 服务端 [EndpointCommand] / [EndpointQuery] / AddLoomEndpoints Endpoints 文档 · samples/MinimalService
HTTP 客户端 [HttpApi] / AddLoomHttp Http 文档 · sample samples/HttpClient
Di 装配 AddLoomServices()(生成入口,不是 AddLoomDi) Di 文档 · sample samples/Di
Ef 持久化 [EfEntity] / partial LoomDbContext EF 文档 · samples/Ef
Query 规则 [Filterable] / ToCatalog() / QueryDsl.Parse 查询规则
Validation DataAnnotations + 交叉字段/条件必填 端点校验
Display 枚举名 [EnumDisplay] Display 文档
Cli 命令 [CommandGroup] / [Command] Cli 文档

sample 目录随 M10 Samples 矩阵逐步落齐;未落地的面以对应面文档为准。

4. 数据面注意(必读)

  • 上下文必须 partial:生成器发射 DbSet/模型配置;手写 DbSet 会 CS0102(KLSG208)。
  • 建库:demo 用 EnsureCreated;生产用迁移/入仓 DDL。NativeAOT 下 EnsureCreated/迁移被 EF 上游拒绝 (见 持久化主线)。
  • 雪花键批量插入:Snowflake 键 ValueGeneratedNever——批量前必须预赋键 (LoomSnowflakeIdGenerator.BatchAssign),否则多行键 0 进入 EF 身份映射冲突。
  • UoW:多上下文/跨库编排用 AddLoomUow(o => o.Engage<T1>().Engage<T2>()); 单上下文直接注入 DbContext 即可。

5. 下一步