快速上手
目标: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/并自动 Importbuild/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即可。