后端架构实战（八）：落地——用 ASP.NET Core 搭一个微服务骨架

Thu, 04 Jun 2026 10:00:00 +0800

写在前面

前七篇全是道理：权衡、单体、拆分、分布式税、一致性、通信、可观测性。这一篇把理论落成代码——用 ASP.NET Core 搭一个最小可用的微服务骨架。

它不会是一个完整生产系统，但会覆盖微服务的"承重墙"：项目结构、依赖注入、API 网关、健康检查、弹性（Polly）、可观测性（OpenTelemetry）。每一处都对应前面某一篇讲过的道理。

前置：本篇假设你读过我的《ASP.NET Core 学习笔记》系列（中间件管道、DI、认证授权）。基于 .NET 8 LTS。

一、整体结构

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


一个最小微服务系统（4 个工程）：

 Gateway/ API 网关（YARP，统一入口、路由、鉴权）
 OrderService/ 订单服务（业务 A）
 InventoryService/ 库存服务（业务 A 的依赖）
 Shared/ 共享内核（契约、公共类型）

 对应前文：
 拆分（第三篇）→ 按领域切 Order / Inventory
 通信（第六篇）→ 网关 + 服务间 HTTP
 分布式税（第四篇）→ 健康检查、Polly 弹性
 可观测性（第七篇）→ OpenTelemetry 串联

1
2
3
4
5
6
7
8


工程依赖方向（单向，严禁循环）：
 Gateway ──→ Shared
 OrderService ──→ Shared
 InventoryService ──→ Shared
 OrderService ──调用──→ InventoryService（运行时 HTTP，非编译依赖）

 关键：服务间运行时依赖走网络，编译期互不引用
 → 这样才能独立编译、独立部署。

二、每个服务的内部分层

单个服务内部，按职责分层（不是按"被拆成服务"的技术层——区别于第三篇的反模式）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


OrderService/
├── OrderService.Api/ 表现层（Controller / 最小 API）
│ └── 引用 Application、Domain
├── OrderService.Application/ 应用层（用例、编排、接口定义）
│ └── 引用 Domain
├── OrderService.Domain/ 领域层（实体、领域服务、规则）
│ └── 不依赖任何人（依赖倒置的核心）
└── OrderService.Infrastructure/ 基础设施（DB、外部调用、实现）
 └── 引用 Application（实现接口）

 依赖方向永远向内，Domain 在最中心、不依赖任何层。
 这是"整洁架构/洋葱架构"的思路，保证领域逻辑纯净。

三、依赖注入：组装一切

ASP.NET Core 的 DI 是一等公民（见我的 ASP.NET Core 笔记一）。微服务里，所有跨层依赖都通过 DI 注入，这样才好测试、好替换。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


// OrderService.Application/Dependencies.cs
public static class Dependencies
{
 public static IServiceCollection AddOrderServices(this IServiceCollection services)
 {
 // 应用层服务
 services.AddScoped<IOrderService, OrderService>();
 // 端口适配器：接口在 Application，实现在 Infrastructure
 services.AddScoped<IInventoryClient, InventoryClient>();
 services.AddScoped<IOrderRepository, OrderRepository>();
 return services;
 }
}

// OrderService.Api/Program.cs
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddOrderServices(); // 业务服务
builder.Services.AddControllers();
builder.Services.AddHealthChecks(); // 健康检查（第五节）
builder.Services.AddHttpClientPolicies(); // Polly 弹性（第六节）

var app = builder.Build();
app.MapControllers();
app.MapHealthChecks("/health"); // 暴露健康检查端点
app.Run();

单元测试里可以替换 IInventoryClient 为 mock，这就是第四篇《.NET 单元测试：依赖注入与可测试性》的价值。

四、API 网关：YARP 统一入口

对外不直连各服务，用网关收口（第六篇）。.NET 生态用 YARP（Yet Another Reverse Proxy，微软出品，比 Ocelot 更现代）。

1
2
3
4
5
6
7
8


// Gateway/Program.cs
var builder = WebApplication.CreateBuilder();
builder.Services.AddReverseProxy()
 .LoadFromConfig(builder.Configuration.GetSection("ReverseProxy")); // 路由放配置

var app = builder.Build();
app.MapReverseProxy(); // 网关入口
app.Run();

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


// Gateway/appsettings.json —— 路由配置
{
 "ReverseProxy": {
 "Routes": {
 "order-route": {
 "ClusterId": "order-cluster",
 "Match": { "Path": "/api/orders/{**catch-all}" }
 },
 "inventory-route": {
 "ClusterId": "inventory-cluster",
 "Match": { "Path": "/api/inventory/{**catch-all}" }
 }
 },
 "Clusters": {
 "order-cluster": {
 "Destinations": {
 "d1": { "Address": "http://order-service:8080/" }
 }
 },
 "inventory-cluster": {
 "Destinations": {
 "d1": { "Address": "http://inventory-service:8080/" }
 }
 }
 }
 }
}

1
2
3
4
5
6


网关集中处理（不在每个服务里重复）：
 - 路由（/api/orders → 订单服务）
 - 鉴权（统一验 token）
 - 限流、熔断
 - 协议转换
 生产环境再配多实例 + 负载均衡，保证网关本身高可用。

五、健康检查：编排的基础

K8s 和负载均衡器靠健康检查决定"流量往哪打"（第四篇分布式税）。ASP.NET Core 内置 HealthCheck。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29


// 自定义健康检查：探测下游依赖
public class InventoryHealthCheck : IHealthCheck
{
 private readonly IInventoryClient _client;
 public InventoryHealthCheck(IInventoryClient client) => _client = client;

 public async Task<HealthCheckResult> CheckHealthAsync(
 HealthCheckContext context, CancellationToken ct = default)
 {
 try
 {
 var ok = await _client.PingAsync(ct);
 return ok ? HealthCheckResult.Healthy("inventory reachable")
 : HealthCheckResult.Degraded("inventory slow");
 }
 catch
 {
 return HealthCheckResult.Unhealthy("inventory down");
 }
 }
}

// 注册
builder.Services.AddHealthChecks()
 .AddCheck<InventoryHealthCheck>("inventory", failureStatus: HealthStatus.Unhealthy);

// 分别暴露存活探针 / 就绪探针（K8s 标准用法）
app.MapHealthChecks("/health/live", new() { Predicate = _ => false }); // 进程活着
app.MapHealthChecks("/health/ready", new() { Predicate = r => r.Tags.Contains("ready") });

1
2
3
4
5


K8s 里：
 livenessProbe → /health/live （进程活着吗）
 readinessProbe → /health/ready （依赖就绪、能接流量吗）
 就绪探针失败 → K8s 把该实例摘出流量，但不重启；
 存活探针失败 → K8s 重启容器。

六、弹性：Polly 应对分布式税

跨网络调用必加弹性（第四篇的超时/重试/熔断）。.NET 用 Polly，配合 HttpClientFactory。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


// 订单服务调用库存服务，加满弹性策略
builder.Services.AddHttpClient<IInventoryClient, InventoryClient>(client =>
{
 client.BaseAddress = new("http://inventory-service:8080/");
 client.Timeout = TimeSpan.FromSeconds(3); // ① 超时
})
.AddTransientHttpErrorPolicy(p => // ② 重试（仅对临时错误）
 p.WaitAndRetryAsync(3, i => TimeSpan.FromMilliseconds(200 * Math.Pow(2, i))))
.AddTransientHttpErrorPolicy(p => // ③ 熔断
 p.CircuitBreakerAsync(5, TimeSpan.FromSeconds(30)));
// AddTransientHttpErrorPolicy 默认对 5xx、408、网络错误生效

1
2
3
4
5


这几行代码对应第四篇的整笔账：
 超时 → 别傻等慢服务
 重试 → 应对网络抖动（配合幂等，库存扣减接口必须幂等）
 熔断 → 库存服务挂了，订单服务直接快速失败，不耗尽自己的线程池
 → 切断雪崩的放大效应

七、可观测性：OpenTelemetry 串联

第七篇的链路追踪，几行代码接入。

1
2
3
4
5
6
7
8
9


// 各服务统一接入 OpenTelemetry
builder.Services.AddOpenTelemetry()
 .WithTracing(tp => tp
 .AddAspNetCoreInstrumentation() // 自动追踪 HTTP 入站
 .AddHttpClientInstrumentation() // 自动追踪 HttpClient 出站
 .AddSqlClientInstrumentation() // 自动追踪 DB 调用
 .AddOtlpExporter()); // 导出到 OTel Collector

builder.Logging.AddOpenTelemetry(); // 日志自动带 traceId

1
2
3
4
5


效果：一次"下单"请求
 网关(span) → 订单服务(span) → 库存服务(span) → DB(span)
 自动连成一条完整 trace，traceId 自动透传、日志自动关联。
 Jaeger 里一眼看到哪一段慢。
 → 这就是第七篇说的"微服务神经系统"，接入成本极低。

八、配置与外部化

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


每个服务的配置分环境（开发/测试/生产）外置：
 appsettings.json —— 默认值
 appsettings.Production —— 生产覆盖
 环境变量 / K8s ConfigMap / Secret —— 敏感和环境相关

 builder.Configuration
 .AddJsonFile("appsettings.json")
 .AddJsonFile($"appsettings.{env}.json", optional: true)
 .AddEnvironmentVariables(); // 环境变量优先级最高，适合容器

 分布式税里的"配置中心"（Nacos/Apollo）在规模上来后再引入，
 小系统先用环境变量 + ConfigMap 足够。

九、把前七篇串起来

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


这个骨架里，每一处都对应前面某一篇：

 工程结构、依赖方向 ← 第三篇：按领域切，单向依赖
 DI 注入一切 ← 可测试性（ASP.NET Core 笔记四）
 YARP 网关 ← 第六篇：统一入口、路由、鉴权
 健康检查 ← 第四篇：编排基础（K8s 探针）
 Polly 超时/重试/熔断 ← 第四篇：弹性，防雪崩
 OpenTelemetry ← 第七篇：可观测性神经系统
 服务间 HTTP + 幂等 ← 第五、六篇：一致性 + 通信
 配置外置 ← 第四篇：分布式税中的配置

 这就是一个"承重墙齐全"的微服务起点。
 业务往上长，基础设施已就位。

十、回到第一篇：要不要这么做

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


最后，回到系列第一篇的"权衡"：

 这个骨架是"当你要做微服务时"的标准起手式。
 但你要不要做微服务，回到那几个问题：

 - 团队是不是大到需要拆分协作？
 - 是不是有独立扩容 / 独立发布 / 故障隔离的真实需求？
 - 有没有 K8s + CI/CD + 可观测性的运维能力？

 如果没有 → 第二篇的"模块化单体"才是你的答案。
 把这套骨架的"DI + 分层 + 健康检查 + 可观测性"
 用在单体内部，一样成立，还省了网络和分布式税。

 记住：技术选型服务于问题和约束，不是反过来。

十一、系列小结

八篇下来，一条主线：

（一）架构是权衡：没有银弹，一切看约束
（二）单体被低估：模块化单体是大多数团队的起点
（三）拆分看领域：按业务切，不按技术层切
（四）分布式要收税：网络、一致性、可观测、运维，样样要自建
（五）一致性靠模式：核心收敛强一致，周边用最终一致 + Saga + Outbox
（六）通信看同步异步：REST/gRPC 与消息队列各擅其场
（七）可观测性是神经：日志 + 指标 + 链路，traceId 串联
（八）落地 ASP.NET Core：把理论变成可跑的代码

架构没有终点。系统会演进，约束会变化，今天的最优解是明天的技术债。保持权衡的思维、演进的视角、记录决策的习惯——这才是这套系列想留给你的，比任何具体技术都重要的东西。

Polly on 纪伟的个人博客