在 .NET 应用中按功能垂直切片组织代码：用特性文件夹…

适用于 .NET 应用需要按功能而非按层组织代码、减少跨功能耦合、并在 Mediator/Wolverine/原生 handler 间选择垂直切片实现时。

适用场景

解决思路

1. 按功能而非按层组织代码：每个功能是一个自包含的垂直切片，包含 endpoint、handler、request/response 类型和 validation；不要放在 Controllers/、Services/、Repositories/ 文件夹之间跳转。
2. 最小化跨功能耦合：功能之间不要直接互相引用；共享关注点放到 Common/ 或 Shared/ 目录。
3. 一个功能一个文件也可以：简单 CRUD endpoint 不需要分散在 5 个分层文件里；先把所有内容放在一个文件，只在复杂度需要时抽取。
4. 把 handler 当作工作单元：每个 handler 只做一件事；不要创建带 20 个方法的 god-service。
5. 按 Feature Folder Structure 组织：src/MyApp.Api/Features/Orders/CreateOrder.cs 等每个操作一个文件；Orders/Shared/ 放 Orders 功能内共享代码；Products/ 放产品功能；Common/Behaviors/ 放跨切面 Mediator pipeline behavior；Common/Persistence/ 放 AppDbContext；Common/Extensions/ 放 ServiceCollectionExtensions；Program.cs 在根目录。
6. Pattern A（推荐默认）：使用 source-generated mediator，MIT licensed、无反射、Native AOT 兼容；使用 IRequest<T> / IRequestHandler<TRequest, TResponse> 和 pipeline behaviors；API 与 MediatR 几乎相同但更快且免费；包为 Mediator.Abstractions + Mediator.SourceGenerator。
7. Pattern A 实现：在 Features/Orders/CreateOrder.cs 中定义 public static class CreateOrder，包含 record Command(...) : IRequest<Result<OrderResponse>>、record OrderItemDto(...)、record OrderResponse(...)；定义 Validator : AbstractValidator<Command>，规则为 CustomerId NotEmpty、Items NotEmpty、每个 item 的 ProductId NotEmpty、Quantity GreaterThan(0)；定义 internal sealed class Handler(AppDbContext db, TimeProvider clock) : IRequestHandler<Command, Result<OrderResponse>>，在 Handle 中创建 Order、db.Orders.Add、SaveChangesAsync、返回 Result.Success。
8. Pattern A 注册：在 Program.cs 或模块 DI 中调用 builder.Services.AddMediator()。
9. Pattern A 端点分组：创建 public sealed class OrderEndpoints : IEndpointGroup，在 Map 中调用 app.MapGroup(`/api/orders`).WithTags(`Orders`)；再用 group.MapPost(`/`, async (CreateOrder.Command command, ISender sender, CancellationToken ct) => { var result = await sender.Send(command, ct); return result.IsSuccess ? TypedResults.Created($`/api/orders/{result.Value.Id}`, result.Value) : result.ToProblemDetails(); }).WithName(`CreateOrder`).Produces<CreateOrder.OrderResponse>(201).ProducesValidationProblem().AddEndpointFilter<ValidationFilter<CreateOrder.Command>>()。
10. Pattern B：Wolverine handlers 基于约定，无接口实现；Wolverine 按方法签名发现 handler。在 static class CreateOrder 中定义 Command、OrderItemDto、OrderResponse；定义 public static async Task<Result<OrderResponse>> Handle(Command command, AppDbContext db, TimeProvider clock, CancellationToken ct) 直接实现逻辑，Wolverine 按 static Handle 方法约定发现。
11. Pattern C：Raw handler classes 无外部依赖，适合小项目或想完全控制的团队。在 static class CreateOrder 中定义 Command、OrderItemDto、OrderResponse；定义 internal class Handler(AppDbContext db, TimeProvider clock)，其中有 ExecuteAsync(Command command, CancellationToken ct) 实现逻辑。
12. Pattern C 端点接线：group.MapPost(`/`, async (CreateOrder.Command command, CreateOrder.Handler handler, CancellationToken ct) => { var result = await handler.ExecuteAsync(command, ct); return result.IsSuccess ? TypedResults.Created($`/api/orders/{result.Value.Id}`, result.Value) : result.ToProblemDetails(); })；将 Result 映射到 HTTP 响应。
13. 可选添加模块边界：对增长到超出单项目的大型应用引入模块边界；每个模块是单独的 class library，拥有自己的 features 和 DbContext。
14. 模块结构：MyApp.Api 作为宿主，包含 Program.cs 和 Modules/ModuleExtensions.cs（app.MapOrderModule()、app.MapCatalogModule()）；MyApp.Orders 模块包含 Features/CreateOrder.cs、Persistence/OrdersDbContext.cs、OrdersModule.cs（IServiceCollection + IEndpointRouteBuilder 扩展）；MyApp.Catalog 模块类似。
15. 模块通信：优先使用 Integration events（通过 Wolverine 或 MassTransit 异步解耦）；其次使用 Shared contracts（MyApp.Contracts 项目含 DTOs/interfaces，谨慎使用）。
16. 共享关注点放在功能文件夹外：例如 Common/Behaviors/ValidationBehavior.cs 作为 Mediator pipeline，实现 ValidationBehavior<TRequest, TResponse> : IPipelineBehavior<TRequest, TResponse> where TRequest : IMessage；在 Handle 中创建 ValidationContext<TRequest>，执行所有 validators，收集 failures，若有失败抛 ValidationException，否则 await next(request, ct)。
17. 不要在一个 slice 内创建分层抽象：BAD 是 Features/Orders/ 下同时有 CreateOrder.cs、IOrderService.cs、OrderService.cs、IOrderRepository.cs、OrderRepository.cs；GOOD 是 handler 直接使用 AppDbContext。
18. 不要直接交叉引用功能：BAD 是 CreateOrder 直接调用 GetProduct handler；GOOD 是直接查询数据库或使用共享读模型。
19. 不要把一切放进一个 God Feature 文件：BAD 是 500 行文件含 CRUD + 业务逻辑 + 映射；GOOD 是每个操作一个文件，如 Features/Orders/CreateOrder.cs、GetOrder.cs、CancelOrder.cs。
20. 决策：新项目默认选择 Pattern A — Mediator（source-generated、MIT、快）。
21. 决策：需要 mediator + messaging 在一个库时选择 Pattern B — Wolverine（也处理 events/queues）。
22. 决策：想完全控制且无依赖时选择 Pattern C — Raw handler classes。
23. 决策：现有 MediatR 代码库有 license 时保留 MediatR；否则迁移到 Mediator（API 几乎相同）。
24. 决策：单体增长复杂时添加模块边界，并在每个模块内保持 VSA。
25. 决策：简单 CRUD 功能用单文件：request + handler + endpoint。
26. 决策：复杂功能（saga、events）在功能文件夹中多文件，但仍 colocated。
27. 决策：在功能之间共享逻辑时抽取到 Common/，不要放到另一个功能。

适用边界 · 注意事项

• 团队强制严格分层架构（Controllers/Services/Repositories）且不允许按功能文件夹组织时，不适用。
• 功能之间必须大量直接同步调用且无法用 Common/、共享读模型或集成事件解耦时，不适用。
• 只是简单 CRUD 或小脚本且不想引入 mediator/Wolverine 等库时，可只用 Pattern C 或不采用完整 VSA 模式。