ASP.NET Core on 纪伟的个人博客

ASP.NET Core 学习笔记（五）：进阶与生产实践

Sun, 26 Apr 2026 10:00:00 +0800

写在前面

本文是 ASP.NET Core 系列收官篇，讲生产环境用得多的进阶能力：过滤器（AOP）、后台服务、健康检查、性能优化、部署。

一、过滤器（AOP 切面）

过滤器让你在请求管道的特定阶段插入逻辑，实现日志、缓存、权限、事务等横切关注点。

1.1 六种过滤器（执行顺序）

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


请求进来
 ↓
1. Authorization Filter 授权（最外层）
 ↓
2. Resource Filter 资源（缓存、短路）
 ↓
3. Action Filter 方法（前后）
 ↓
4. Exception Filter 异常
 ↓
5. Result Filter 结果（前后）
 ↓
响应出去

6. Always Run Filter 始终执行（Result 的变体，不被短路影响）

1.2 实现自定义过滤器

 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
30
31


// Action 过滤器（方法执行前后）
public class LoggingActionFilter : IAsyncActionFilter
{
 private readonly ILogger<LoggingActionFilter> _logger;
 public LoggingActionFilter(ILogger<LoggingActionFilter> logger) => _logger = logger;

 public async Task OnActionExecutionAsync(ActionExecutingContext context, ActionExecutionDelegate next)
 {
 _logger.LogInformation("执行 {Action}", context.ActionDescriptor.DisplayName);
 await next(); // 执行 Action
 _logger.LogInformation("执行完成");
 }
}

// 异常过滤器（捕获未处理异常）
public class ApiExceptionFilter : IExceptionFilter
{
 public void OnException(ExceptionContext context)
 {
 context.Result = new ObjectResult(new { message = context.Exception.Message })
 { StatusCode = 500 };
 context.ExceptionHandled = true;
 }
}

// 注册（全局）
builder.Services.AddControllers(o =>
{
 o.Filters.Add<LoggingActionFilter>();
 o.Filters.Add<ApiExceptionFilter>();
});

1.3 特性形式

1
2
3
4
5
6


// 用特性方式挂到控制器/方法
[ServiceFilter(typeof(LoggingActionFilter))] // 通过 DI 注入
public class UsersController : ControllerBase { ... }

// 或写一个既是特性又是过滤器的类（用于无需 DI 的简单场景）
public class ValidateAttribute : Attribute, IActionFilter { ... }

1
2
3


何时用过滤器 vs 中间件：
 中间件 — 管道层，对每个请求都跑（日志、异常、CORS）
 过滤器 — MVC 层，能感知控制器/Action（缓存、模型验证、特定授权）

二、后台服务（IHostedService）

需要在后台持续运行的任务（定时任务、消息消费、监控）。

2.1 BackgroundService（推荐基类）

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


public class OrderTimeoutService : BackgroundService // 继承 BackgroundService
{
 private readonly ILogger<OrderTimeoutService> _logger;

 public OrderTimeoutService(ILogger<OrderTimeoutService> logger) => _logger = logger;

 protected override async Task ExecuteAsync(CancellationToken stoppingToken)
 {
 _logger.LogInformation("订单超时服务启动");
 while (!stoppingToken.IsCancellationRequested)
 {
 try { await CancelExpiredOrders(); }
 catch (Exception ex) { _logger.LogError(ex, "处理异常"); }
 await Task.Delay(TimeSpan.FromMinutes(1), stoppingToken); // 每 1 分钟
 }
 }

 private async Task CancelExpiredOrders() { /* 业务 */ }
}

// 注册
builder.Services.AddHostedService<OrderTimeoutService>();

2.2 托管队列（IHostedService + Channel）

后台任务排队执行，结合 Channel：

 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
30


public class EmailQueueService : BackgroundService
{
 private readonly Channel<EmailMessage> _channel;
 public EmailQueueService(Channel<EmailMessage> channel) => _channel = channel;

 protected override async Task ExecuteAsync(CancellationToken ct)
 {
 await foreach (var email in _channel.Reader.ReadAllAsync(ct))
 {
 await SendEmailAsync(email);
 }
 }
}

// 注册 Channel + 服务
builder.Services.AddSingleton(Channel.CreateUnbounded<EmailMessage>());
builder.Services.AddHostedService<EmailQueueService>();

// 业务代码投递
public class OrderService
{
 private readonly Channel<EmailMessage> _channel;
 public OrderService(Channel<EmailMessage> channel) => _channel = channel;

 public async Task CreateAsync(Order order)
 {
 // ... 创建订单
 await _channel.Writer.WriteAsync(new EmailMessage(order.UserEmail, "下单成功"));
 }
}

2.3 Worker Service

独立的后台服务项目（无 Web）：

1

dotnet new worker -n MyWorker # 创建 Worker 项目

1
2


// 和 BackgroundService 一样的模型，适合纯后台任务
// 可部署为 Windows Service / systemd 服务

三、健康检查

生产环境必备——让负载均衡器、K8s 知道应用是否健康。

1
2
3
4
5
6
7


builder.Services.AddHealthChecks()
 .AddSqlServer(connectionString, name: "sql")
 .AddRedis(redisConnection, name: "redis")
 .AddUrlGroup(new Uri("https://api.github.com"), name: "github");

var app = builder.Build();
app.MapHealthChecks("/health"); // GET /health 返回 200（健康）或 503（不健康）

1
2
3
4
5
6
7
8


用途：
 - K8s liveness/readiness 探针
 - 负载均衡健康判断
 - 监控告警

 自定义健康检查：
 public class MyHealthCheck : IHealthCheck { ... }
 AddCheck<MyHealthCheck>("my-check")

四、性能优化

4.1 响应缓存

1
2
3
4
5
6


builder.Services.AddResponseCaching();
app.UseResponseCaching();

[ResponseCache(Duration = 60, Location = ResponseCacheLocation.Any)]
[HttpGet("list")]
public List<Item> GetList() { ... } // 60 秒内相同请求走缓存

4.2 输出缓存（.NET 7+）

服务端缓存，比 ResponseCache（浏览器侧）更强：

1
2
3
4
5
6
7
8
9


builder.Services.AddOutputCache();
app.UseOutputCache();

[OutputCache(Duration = 60)]
[HttpGet("hot")]
public async Task<List<Article>> Hot() { ... }

// 标记失效（数据变了主动清除缓存）
_cache EvictTagAsync("articles");

4.3 响应压缩

1
2
3
4
5
6
7


builder.Services.AddResponseCompression(opt =>
{
 opt.EnableForHttps = true;
 opt.Providers.Add<BrotliCompressionProvider>();
 opt.Providers.Add<GzipCompressionProvider>();
});
app.UseResponseCompression(); // 自动压缩 JSON/HTML 等

4.4 异步 + 性能要点

1
2
3
4
5
6
7


✓ 全异步（async/await），不阻塞线程
✓ 数据库用 EF Core 异步 + AsNoTracking（只读查询）
✓ 避免 N+1 查询（Include / 拆分查询）
✓ 连接池配置合理
✓ 减少 JSON 分配（System.Text.Json 高效、Utf8JsonWriter 流式）
✓ 大对象用 ArrayPool 复用
✓ 开 Server GC（多核服务器）

五、部署

5.1 发布

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# 框架依赖（需装运行时）
dotnet publish -c Release -o ./publish

# 独立部署（含运行时，目标机不用装 .NET）
dotnet publish -c Release -r linux-x64 --self-contained -o ./publish

# 单文件
dotnet publish -c Release -r linux-x64 --self-contained -p:PublishSingleFile=true

# AOT（启动极快、单文件、无运行时）
dotnet publish -c Release -r linux-x64 -p:PublishAot=true

5.2 systemd 服务（Linux）

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


# /etc/systemd/system/myapp.service
[Unit]
Description=My App
After=network.target

[Service]
WorkingDirectory=/var/www/myapp
ExecStart=/var/www/myapp/MyApp --urls http://0.0.0.0:5000
Restart=always
Environment=ASPNETCORE_ENVIRONMENT=Production
User=www-data

[Install]
WantedBy=multi-user.target

5.3 反向代理架构

1
2
3
4
5
6


客户端 → Nginx（80/443，HTTPS 终端）→ Kestrel（5000，HTTP）

 Nginx 负责：HTTPS、静态文件、限流、负载均衡
 Kestrel 负责：ASP.NET Core 应用

 配合 UseForwardedHeaders 让应用拿到真实 IP/协议

5.4 Docker 部署

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
WORKDIR /src
COPY . .
RUN dotnet publish -c Release -o /app

FROM mcr.microsoft.com/dotnet/aspnet:8.0
WORKDIR /app
COPY --from=build /app .
EXPOSE 80
ENTRYPOINT ["dotnet", "MyApp.dll"]

六、小结

过滤器：六种过滤器实现 AOP（日志、缓存、异常、授权）
后台服务：BackgroundService 做定时/消费任务，Worker Service 独立后台项目
健康检查：AddHealthChecks + MapHealthChecks，供 K8s/负载均衡探活
性能优化：ResponseCache/OutputCache、压缩、全异步、Server GC
部署：dotnet publish、systemd、Nginx 反代、Docker、AOT

系列总结

ASP.NET Core 五篇完结：

基础架构：中间件管道 + 依赖注入（两大支柱）
路由与控制器：路由、模型绑定、验证、Minimal API
认证与授权：JWT/Cookie、Claims、策略授权
API 设计：RESTful、Swagger、错误处理、版本控制、序列化
进阶与生产：过滤器、后台服务、健康检查、性能、部署

核心心法：理解中间件管道 + 依赖注入 + Claims 身份模型，ASP.NET Core 就彻底通了。 剩下的都是基于这些的组合应用。

ASP.NET Core 学习笔记（四）：API 设计与错误处理

Sat, 25 Apr 2026 10:00:00 +0800

写在前面

本文讲 API 工程化：RESTful 设计规范、Swagger 文档、统一错误处理、版本控制、序列化。这些是 API 从"能跑"到"专业"的关键。

一、RESTful API 设计

1.1 资源命名

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


✓ 用名词复数表示资源集合
 GET /api/users 获取列表
 POST /api/users 新建
 GET /api/users/123 获取单个
 PUT /api/users/123 全量更新
 PATCH /api/users/123 部分更新
 DELETE /api/users/123 删除

✗ 别用动词（RPC 风格）
 /api/getUser /api/createUser /api/deleteUserById

✓ 嵌套表达从属关系
 GET /api/users/123/orders 用户 123 的订单
 GET /api/orders/456 全局订单（订单也有独立资源）

✓ 查询参数做过滤/排序/分页
 GET /api/users?role=admin&sort=created&desc&page=2&size=20

1.2 HTTP 方法语义

1
2
3
4
5
6
7
8
9


GET 安全、幂等、无副作用 （查询）
POST 非幂等 （新建）
PUT 幂等（全量替换） （更新）
PATCH 非幂等（部分更新） （更新）
DELETE 幂等 （删除）

幂等性：多次执行结果相同
 GET/PUT/DELETE 幂等
 POST/PATCH 非幂等

1.3 状态码

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


2xx 成功
 200 OK 请求成功（有 body）
 201 Created 新建成功（带 Location 头）
 204 No Content 成功无 body（DELETE 常用）

4xx 客户端错误
 400 Bad Request 参数错误/验证失败
 401 Unauthorized 未认证（没登录）
 403 Forbidden 已认证但无权限
 404 Not Found 资源不存在
 409 Conflict 冲突（如重复创建）
 422 Unprocessable 语义错误
 429 Too Many 限流

5xx 服务端错误
 500 Internal Error 服务器异常
 502/503/504 网关/服务不可用/超时

1
2
3


401 vs 403 容易混：
 401 — 你是谁？（没登录/Token 失效）
 403 — 你没权限。（登录了，但权限不够）

二、Swagger / OpenAPI

2.1 基本接入

 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
30
31


// 安装 Swashbuckle
// dotnet add package Swashbuckle.AspNetCore

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen(c =>
{
 c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });

 // JWT 认证支持
 c.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
 {
 Description = "JWT Authorization header. 例：Bearer {token}",
 Name = "Authorization",
 In = ParameterLocation.Header,
 Type = SecuritySchemeType.Http,
 Scheme = "bearer"
 });
 c.AddSecurityRequirement(new OpenApiSecurityRequirement
 {
 { new OpenApiSecurityScheme { Reference = new OpenApiReference {
 Type = ReferenceType.SecurityScheme, Id = "Bearer" } }, Array.Empty<string>() }
 });
});

var app = builder.Build();
if (app.Environment.IsDevelopment())
{
 app.UseSwagger();
 app.UseSwaggerUI();
}
// 访问 /swagger 看交互式文档

2.2 XML 注释文档

1
2
3
4
5


<!-- .csproj 里启用 XML 文档 -->
<PropertyGroup>
 <GenerateDocumentationFile>true</GenerateDocumentationFile>
 <NoWarn>$(NoWarn);1591</NoWarn> <!-- 忽略缺少注释的警告 -->
</PropertyGroup>

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


// Program.cs
builder.Services.AddSwaggerGen(c =>
{
 var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
 var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
 c.IncludeXmlComments(xmlPath);
});

/// <summary>获取用户信息</summary>
/// <param name="id">用户 ID</param>
/// <returns>用户详情</returns>
/// <response code="200">返回用户</response>
/// <response code="404">用户不存在</response>
[HttpGet("{id}")]
[ProducesResponseType(typeof(User), 200)]
[ProducesResponseType(404)]
public ActionResult<User> Get(int id) { ... }

三、统一错误处理

3.1 异常处理中间件

 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
30


// 全局异常兜底（放管道最前面）
public class ExceptionMiddleware
{
 private readonly RequestDelegate _next;
 private readonly ILogger<ExceptionMiddleware> _logger;

 public ExceptionMiddleware(RequestDelegate next, ILogger<ExceptionMiddleware> logger)
 {
 _next = next;
 _logger = logger;
 }

 public async Task InvokeAsync(HttpContext context)
 {
 try { await _next(context); }
 catch (Exception ex)
 {
 _logger.LogError(ex, "未处理异常 {Path}", context.Request.Path);
 context.Response.StatusCode = 500;
 context.Response.ContentType = "application/json";
 await context.Response.WriteAsync(JsonSerializer.Serialize(new
 {
 code = 500,
 message = app.Environment.IsDevelopment() ? ex.Message : "服务器内部错误"
 }));
 }
 }
}

app.UseMiddleware<ExceptionMiddleware>(); // 注册（最前面）

3.2 ProblemDetails（标准错误格式）

ASP.NET Core 内置的标准化错误响应（RFC 7807）：

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


// [ApiController] 自带的验证错误就是 ProblemDetails 格式
// { "type": "...", "title": "Validation error", "status": 400, ... }

// 自定义返回
[HttpGet("{id}")]
public IActionResult Get(int id)
{
 var user = _service.Get(id);
 if (user == null)
 return NotFound(new ProblemDetails
 {
 Title = "用户不存在",
 Status = 404,
 Detail = $"ID 为 {id} 的用户不存在"
 });
 return Ok(user);
}

3.3 自定义异常 + 映射

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


// 业务异常
public class NotFoundException : Exception
{
 public NotFoundException(string msg) : base(msg) { }
}

// 异常→状态码映射中间件
catch (NotFoundException ex)
{
 context.Response.StatusCode = 404;
 // 返回 ProblemDetails
}

3.4 统一响应包装（可选）

有些团队喜欢所有响应统一格式：

1
2
3
4
5
6
7
8
9


public class ApiResponse<T>
{
 public int Code { get; set; }
 public string Message { get; set; }
 public T Data { get; set; }
}

// 但 RESTful 纯粹派认为：用 HTTP 状态码即可，不需要再包一层 code
// 两种风格都常见，团队统一即可

四、版本控制

API 演进时需要版本控制，避免破坏老客户端。

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


// 安装：Asp.Versioning.Mvc
builder.Services.AddApiVersioning(options =>
{
 options.DefaultApiVersion = new ApiVersion(1, 0);
 options.AssumeDefaultVersionWhenUnspecified = true;
 options.ReportApiVersions = true; // 响应头显示支持版本
 options.ApiVersionReader = new UrlSegmentApiVersionReader(); // URL 段
 // 也可：Query string / Header
});

// 控制器标版本
[ApiController]
[ApiVersion("1.0")]
[Route("api/v{version:apiVersion}/users")]
public class UsersV1Controller : ControllerBase { ... }

[ApiController]
[ApiVersion("2.0")]
[Route("api/v{version:apiVersion}/users")]
public class UsersV2Controller : ControllerBase { ... }

// /api/v1/users → V1
// /api/v2/users → V2

五、序列化（System.Text.Json）

5.1 配置

1
2
3
4
5
6
7
8
9


builder.Services.AddControllers()
 .AddJsonOptions(options =>
 {
 options.JsonSerializerOptions.PropertyNamingPolicy = JsonNamingPolicy.CamelCase;
 options.JsonSerializerOptions.WriteIndented = false;
 options.JsonSerializerOptions.DefaultIgnoreCondition =
 JsonIgnoreCondition.WhenWritingNull; // null 不输出
 options.JsonSerializerOptions.Converters.Add(new JsonStringEnumConverter()); // 枚举转字符串
 });

5.2 常用特性

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


public class User
{
 [JsonPropertyName("user_id")] // 自定义 JSON 字段名
 public int Id { get; set; }

 [JsonIgnore] // 不序列化
 public string Password { get; set; }

 [JsonPropertyOrder(1)] // 排序
 public string Name { get; set; }
}

// 循环引用（EF Core 导航属性常见）
[JsonReferenceHandler(ReferenceHandler.IgnoreCycles)]
public class Order { ... }

5.3 驼峰与中文

1
2
3
4
5
6
7


默认 PascalCase（C# 风格）序列化后还是 PascalCase？
 前端通常要 camelCase → 配 PropertyNamingPolicy = CamelCase
 C# 的 UserId → JSON 的 userId

中文转义问题：
 默认中文会被转义成 \uXXXX
 加 Encoder = JavaScriptEncoder.Create(UnicodeRanges.All) 保留中文

六、小结

RESTful：名词资源、HTTP 方法语义、正确状态码（401 vs 403）
Swagger：Swashbuckle 接入，XML 注释 + JWT 支持
错误处理：全局异常中间件 + ProblemDetails 标准格式
版本控制：URL 段 / Query / Header，ApiVersioning 库
序列化：System.Text.Json，camelCase、忽略 null、枚举字符串

下一篇讲进阶：过滤器、后台服务、健康检查、性能优化、部署。

ASP.NET Core 学习笔记（三）：认证与授权

Fri, 24 Apr 2026 10:00:00 +0800

写在前面

本文讲 ASP.NET Core 的安全核心：认证（Authentication）和授权（Authorization）。这两个词常被混用，但在框架里是两个明确分开的阶段。理解它们才能做好登录、JWT、权限控制。

一、认证 vs 授权

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


认证（Authentication）= 你是谁？
 验证用户身份（用户名密码、Token、证书）
 填充 HttpContext.User
 "张三登录成功"

授权（Authorization）= 你能干什么？
 基于已认证的身份，判断能否访问资源
 读取 HttpContext.User 做决策
 "张三是管理员，可以删用户"

执行顺序（中间件顺序）：
 UseAuthentication → UseAuthorization
 先认证（你是谁）→ 再授权（能干嘛）

二、Claims 模型（身份的核心）

ASP.NET Core 用 Claims 模型表示身份，理解它很关键。

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


// Claim = 一条身份信息（键值对）
new Claim(ClaimTypes.Name, "张三")
new Claim(ClaimTypes.Email, "zhang@test.com")
new Claim(ClaimTypes.Role, "Admin")

// ClaimsIdentity = 一组 Claim + 认证类型
var identity = new ClaimsIdentity(claims, "MyAuthScheme");

// ClaimsPrincipal = 一个用户（可含多个 Identity）
var principal = new ClaimsPrincipal(identity);

// 赋值给 HttpContext（认证完成）
HttpContext.User = principal;

1
2
3
4
5
6


层级关系：
 ClaimsPrincipal（用户）
 └── ClaimsIdentity（一种身份，如 JWT 身份）
 └── Claim（一条信息，如姓名、角色）

 用户的 Name、Role 都是从 Claim 读出来的

三、JWT 认证（最常用）

JSON Web Token，无状态、跨域、适合前后端分离和微服务。

3.1 配置

1
2
3
4
5
6
7
8
9


// appsettings.json
{
 "Jwt": {
 "Issuer": "jiwei.space",
 "Audience": "jiwei.space",
 "SigningKey": "this-is-a-very-long-secret-key-at-least-32-chars",
 "ExpiresMinutes": 120
 }
}

 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


// Program.cs
var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
 .AddJwtBearer(options =>
 {
 var jwt = builder.Configuration.GetSection("Jwt").Get<JwtOptions>()!;
 options.TokenValidationParameters = new TokenValidationParameters
 {
 ValidateIssuer = true,
 ValidIssuer = jwt.Issuer,
 ValidateAudience = true,
 ValidAudience = jwt.Audience,
 ValidateLifetime = true, // 验证过期
 ValidateIssuerSigningKey = true, // 验证签名
 IssuerSigningKey = new SymmetricSecurityKey(
 Encoding.UTF8.GetBytes(jwt.SigningKey)),
 ClockSkew = TimeSpan.Zero // 不允许时间偏差
 };
 });

builder.Services.AddAuthorization();

var app = builder.Build();
app.UseAuthentication(); // 先认证
app.UseAuthorization(); // 后授权

3.2 颁发 Token（登录）

 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
30
31
32
33
34
35
36
37


public class AuthService
{
 private readonly JwtOptions _jwt;
 public AuthService(IOptions<JwtOptions> opt) => _jwt = opt.Value;

 public string CreateToken(User user)
 {
 var claims = new List<Claim>
 {
 new(ClaimTypes.NameIdentifier, user.Id.ToString()),
 new(ClaimTypes.Name, user.Username),
 new(ClaimTypes.Role, user.Role)
 };

 var key = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(_jwt.SigningKey));
 var creds = new SigningCredentials(key, SecurityAlgorithms.HmacSha256);

 var token = new JwtSecurityToken(
 issuer: _jwt.Issuer,
 audience: _jwt.Audience,
 claims: claims,
 expires: DateTime.UtcNow.AddMinutes(_jwt.ExpiresMinutes),
 signingCredentials: creds);

 return new JwtSecurityTokenHandler().WriteToken(token);
 }
}

// 登录接口
[HttpPost("login")]
public ActionResult Login(LoginDto dto)
{
 var user = _userService.Verify(dto.Username, dto.Password);
 if (user == null) return Unauthorized();
 var token = _auth.CreateToken(user);
 return Ok(new { token });
}

3.3 客户端使用

1
2
3
4
5


客户端登录拿到 token → 存 localStorage/cookie → 后续请求带上：

 Authorization: Bearer eyJhbGciOi...

 框架自动验证 token，验证通过填充 HttpContext.User

3.4 JWT 结构

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


header.payload.signature（三段 Base64URL，用 . 分隔）

 header = 算法（HS256）和类型（JWT）
 payload = claims（用户信息、过期时间）
 signature = 用密钥对 header.payload 签名（防篡改）

特点：
 ✓ 无状态（服务端不存 session，靠签名验证）
 ✓ 可跨服务（微服务共享密钥即可验证）
 ✗ 无法主动失效（签发后到过期前一直有效，靠 Refresh Token / 黑名单缓解）

四、Cookie 认证（传统 Web）

适合 MVC/Razor Pages 这类服务端渲染、浏览器访问的场景。

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


builder.Services.AddAuthentication(CookieAuthenticationDefaults.AuthenticationScheme)
 .AddCookie(options =>
 {
 options.LoginPath = "/login"; // 未登录跳转
 options.LogoutPath = "/logout";
 options.ExpireTimeSpan = TimeSpan.FromDays(7);
 options.SlidingExpiration = true; // 滑动过期
 });

// 登录（创建 Cookie）
public async Task Login(string username, string password)
{
 var user = _userService.Verify(username, password);
 if (user == null) return;

 var claims = new[] { new Claim(ClaimTypes.Name, user.Username) };
 var identity = new ClaimsIdentity(claims, CookieAuthenticationDefaults.AuthenticationScheme);
 await HttpContext.SignInAsync(
 CookieAuthenticationDefaults.AuthenticationScheme,
 new ClaimsPrincipal(identity));
}

// 注销
await HttpContext.SignOutAsync(CookieAuthenticationDefaults.AuthenticationScheme);

1
2
3
4
5
6


JWT vs Cookie：
 JWT — 无状态、API/前后端分离、移动端、微服务
 Cookie — 有状态、浏览器、MVC、SSO

 前后端分离 → JWT
 传统 Web → Cookie

五、授权

认证解决"你是谁"，授权解决"能干什么"。

5.1 基础授权

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


[Authorize] // 必须登录
public class UsersController { ... }

[Authorize]
[HttpGet("profile")]
public UserProfile GetProfile() { ... }

[AllowAnonymous] // 允许匿名（覆盖 Authorize）
[HttpPost("register")]
public User Register() { ... }

5.2 角色授权

1
2
3
4
5
6


[Authorize(Roles = "Admin")]
[HttpDelete("{id}")]
public void Delete(int id) { ... } // 只有 Admin 角色能访问

[Authorize(Roles = "Admin,Manager")] // Admin 或 Manager
public void Manage() { ... }

1
2
3


角色怎么来：登录时把角色写进 Claim
 new Claim(ClaimTypes.Role, "Admin")
 授权时框架从 User.Claims 读角色比对

5.3 策略授权（推荐，最强大）

基于策略，比角色灵活——可以组合多个条件、自定义逻辑。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


// 1. 定义策略（包含要求 Requirement）
builder.Services.AddAuthorization(options =>
{
 options.AddPolicy("AtLeast18", policy =>
 policy.RequireClaim("Age").RequireAssertion(ctx =>
 int.Parse(ctx.User.FindFirst("Age")!.Value) >= 18));

 options.AddPolicy("AdminOnly", policy => policy.RequireRole("Admin"));

 // 组合策略
 options.AddPolicy("SeniorAdmin", policy =>
 policy.RequireRole("Admin").RequireClaim("Department", "IT"));
});

// 2. 使用
[Authorize(Policy = "AtLeast18")]
[HttpGet("adult-content")]
public Content GetAdult() { ... }

5.4 自定义授权要求

 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
30
31
32


// 1. 定义要求
public class MinimumAgeRequirement : IAuthorizationRequirement
{
 public int MinimumAge { get; }
 public MinimumAgeRequirement(int min) => MinimumAge = min;
}

// 2. 定义处理器（业务逻辑）
public class MinimumAgeHandler : AuthorizationHandler<MinimumAgeRequirement>
{
 protected override Task HandleRequirementAsync(
 AuthorizationHandlerContext context, MinimumAgeRequirement requirement)
 {
 var ageClaim = context.User.FindFirst("Age");
 if (ageClaim != null && int.Parse(ageClaim.Value) >= requirement.MinimumAge)
 {
 context.Succeed(requirement); // 满足
 }
 return Task.CompletedTask;
 }
}

// 3. 注册
builder.Services.AddSingleton<IAuthorizationHandler, MinimumAgeHandler>();
builder.Services.AddAuthorization(options =>
{
 options.AddPolicy("Over18", policy => policy.Requirements.Add(new MinimumAgeRequirement(18)));
});

// 4. 使用
[Authorize(Policy = "Over18")]
public IActionResult Drink() { ... }

5.5 基于资源的授权

授权决策依赖具体资源（如"只能编辑自己的文章"）：

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


public class ArticleOwnerHandler : AuthorizationHandler<ArticleOwnerRequirement, Article>
{
 protected override Task HandleRequirementAsync(
 AuthorizationHandlerContext context, ArticleOwnerRequirement req, Article article)
 {
 var userId = context.User.FindFirstValue(ClaimTypes.NameIdentifier);
 if (article.AuthorId == userId)
 context.Succeed(req);
 return Task.CompletedTask;
 }
}

// 使用（在 Action 里）
[HttpGet("{id}/edit")]
public async Task<IActionResult> Edit(int id)
{
 var article = _service.Get(id);
 var success = await _authorization.AuthorizeAsync(User, article, "OwnerPolicy");
 if (!success.Succeeded) return Forbid();
 return Ok(article);
}

六、安全最佳实践

1
2
3
4
5
6
7
8
9


✓ 密码用 BCrypt/PBKDF2/Argon2 哈希，绝不存明文
✓ JWT 密钥足够长（≥256bit），放配置/密钥库，不进代码
✓ HTTPS 强制（UseHttpsRedirection + HSTS）
✓ Cookie 设 HttpOnly、Secure、SameSite
✓ 防 CSRF（Cookie 场景用 AntiForgeryToken）
✓ 防 XSS（输出转义、CSP 头）
✓ 限流（防暴力破解登录）
✓ 敏感操作要二次验证
✓ 日志记录认证/授权事件

七、小结

认证 vs 授权：你是谁 / 能干什么，中间件顺序 UseAuthentication → UseAuthorization
Claims 模型：Principal → Identity → Claim，身份的核心表示
JWT：无状态、API 首选；Cookie：有状态、传统 Web
授权：[Authorize] → 角色授权 → 策略授权（最强大）→ 基于资源授权

下一篇讲 API 设计：RESTful 规范、Swagger 文档、统一错误处理、版本控制。

ASP.NET Core 学习笔记（二）：路由与控制器

Thu, 23 Apr 2026 10:00:00 +0800

写在前面

本文是 ASP.NET Core 系列第二篇，讲清楚三件事：URL 如何匹配到代码（路由）、请求数据如何变成参数（模型绑定）、参数如何校验（验证）。这是 API 开发每天用的东西。

一、路由

1.1 两种路由

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


// 特性路由（Attribute Routing）— API 推荐
[ApiController]
[Route("api/[controller]")] // [controller] 占位符替换为控制器名
public class UsersController : ControllerBase
{
 [HttpGet("{id}")] // GET /api/users/123
 public User Get(int id) => ...;

 [HttpPost] // POST /api/users
 public User Create([FromBody] User user) => ...;

 [HttpPut("{id}")] // PUT /api/users/123
 public void Update(int id, [FromBody] User user) => ...;

 [HttpDelete("{id}")] // DELETE /api/users/123
 public void Delete(int id) => ...;
}

// 约定路由（Convention Routing）— MVC/Razor Pages 用
app.MapControllerRoute(
 name: "default",
 pattern: "{controller=Home}/{action=Index}/{id?}");

1
2


API 用特性路由（清晰、灵活、RESTful）
传统 MVC 用约定路由

1.2 路由模板与约束

1
2
3
4
5


[HttpGet("users/{id:int}")] // 只匹配整数 id
[HttpGet("users/{id:int:min(1)}")] // id ≥ 1
[HttpGet("files/{name}.{ext}")] // /files/a.txt
[HttpGet("search/{*query}")] // * 是 catch-all，匹配剩余路径
[HttpGet("posts/{year:int}/{month:range(1,12)}")]

1
2
3
4
5
6
7


常用约束：
 :int :long :double :bool 类型
 :min() :max() :range() 范围
 :minlength() :maxlength() 长度
 :regex() 正则
 :alpha 字母
 :guid GUID

1.3 路由数据

1
2
3
4
5
6


// 路由参数自动绑定到方法参数（同名）
[HttpGet("{id}")]
public User Get(int id) { ... } // id 从路由 {id} 取

// 也可从 HttpContext 取路由值
var id = RouteData.Values["id"];

1.4 路由匹配原理

1
2
3
4
5


请求进来 → UseRouting 匹配端点 → UseAuthorization 检查权限 → 执行端点

 路由匹配在 UseRouting 阶段完成（端点路由 Endpoint Routing）
 匹配出"端点"（Endpoint）= 控制器 + Action 元信息
 后续中间件可以基于匹配到的端点做事（如授权检查）

二、控制器

2.1 API 控制器

1
2
3
4
5
6
7


[ApiController] // 启用 API 专属行为
[Route("api/[controller]")]
public class UsersController : ControllerBase // 注意是 ControllerBase 不是 Controller
{
 // ControllerBase 提供了 API 常用成员，不含 View 支持
 // Controller（MVC）才支持 View，API 不需要
}

1
2
3
4
5
6


[ApiController] 特性的作用（重要）：
 ✓ 自动 400 响应（模型验证失败直接返回 400，不用手动检查 ModelState）
 ✓ 推断绑定源（[FromBody] 等可省略）
 ✓ 多部分/form 绑定推断
 ✓ 问题详情（ProblemDetails）错误格式
 ✓ 必填路由参数检查

2.2 Action 返回类型

 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


// 简单返回（直接返回对象，自动序列化为 JSON）
[HttpGet("{id}")]
public User Get(int id) => _service.Get(id);

// ActionResult（可返回不同状态码）
[HttpPost]
public ActionResult<User> Create(User user)
{
 var created = _service.Create(user);
 return CreatedAtAction(nameof(Get), new { id = created.Id }, created);
 // 返回 201 + Location 头 + body
}

// IActionResult（最灵活）
[HttpGet("{id}")]
public IActionResult Get(int id)
{
 var user = _service.Get(id);
 if (user == null) return NotFound(); // 404
 return Ok(user); // 200
}

// ActionResult<T>（推荐，类型安全 + 灵活）
public ActionResult<User> Get(int id)
{
 var user = _service.Get(id);
 return user == null ? NotFound() : user;
}

2.3 常用返回辅助方法

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


Ok(obj) 200
Created(location,obj) 201（新建资源）
CreatedAtAction(...) 201 + Location
NoContent() 204（成功无内容）
NotFound() 404
BadRequest(obj) 400
Unauthorized() 401
Forbid() 403
Conflict(obj) 409
StatusCode(code,obj) 自定义状态码

三、Minimal API

.NET 6+ 引入的轻量写法，不用 Controller，直接在 Program.cs 写端点。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


var builder = WebApplication.CreateBuilder(args);
builder.Services.AddScoped<IUserService, UserService>();
var app = builder.Build();

// 一行定义一个端点
app.MapGet("/api/users/{id}", async (int id, IUserService svc) =>
{
 var user = await svc.GetAsync(id);
 return user is null ? Results.NotFound() : Results.Ok(user);
});

app.MapPost("/api/users", async (User user, IUserService svc) =>
{
 var created = await svc.CreateAsync(user);
 return Results.Created($"/api/users/{created.Id}", created);
});

app.Run();

1
2
3
4
5
6


Controller vs Minimal API：
 Controller — 适合大型项目、复杂业务、团队协作、AOP（过滤器）
 Minimal API — 适合小型项目、微服务、快速原型

 共同点：都跑在端点路由上，模型绑定、DI 都一样
 Minimal API 性能略好（少一层 Controller 激活）

四、模型绑定

把请求数据（body / query / route / header）转换成方法参数。

4.1 绑定来源

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


[HttpGet("{id}")]
public User Get([FromRoute] int id) { ... } // 路由参数

[HttpGet]
public List<User> Search([FromQuery] string name, [FromQuery] int age) { ... }
// GET /api/users?name=张三&age=25

[HttpPost]
public User Create([FromBody] User user) { ... } // 请求体（JSON）

[HttpGet]
public User Get([FromHeader] string token) { ... } // 请求头

public void Do([FromServices] IUserService svc) { ... } // 从 DI 容器

1
2


[ApiController] 启用后，复杂类型默认 FromBody，简单类型默认 FromQuery/Route
通常可省略特性，但显式写更清晰

4.2 复杂类型绑定

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


// Query 自动绑定到对象
// GET /api/users?name=张三&age=25
[HttpGet]
public List<User> Search([FromQuery] UserQuery query) { ... }

public class UserQuery
{
 public string Name { get; set; }
 public int Age { get; set; }
}

4.3 自定义绑定

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


// 自定义模型绑定器（复杂场景）
public class TrimModelBinder : IModelBinder
{
 public Task BindModelAsync(ModelBindingContext bindingContext)
 {
 var value = bindingContext.ValueProvider.GetValue(bindingContext.ModelName);
 if (value != ValueProviderResult.None)
 {
 bindingContext.Result = ModelBindingResult.Success(value.ToString().Trim());
 }
 return Task.CompletedTask;
 }
}

五、参数验证

5.1 DataAnnotations（内置）

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


public class CreateUserDto
{
 [Required] public string Username { get; set; }
 [Required][EmailAddress] public string Email { get; set; }
 [Required][StringLength(20, MinimumLength = 6)] public string Password { get; set; }
 [Range(0, 150)] public int Age { get; set; }
 [Url] public string Website { get; set; }
 [RegularExpression(@"^1\d{10}$")] public string Phone { get; set; }
}

[HttpPost]
public ActionResult<User> Create(CreateUserDto dto)
{
 // [ApiController] 会自动验证，失败直接 400，不用手动检查
 return _service.Create(dto);
}

1
2
3
4


常用验证特性：
 [Required] [StringLength] [Range] [MinLength] [MaxLength]
 [EmailAddress] [Url] [Phone] [RegularExpression]
 [Compare]（和另一属性比较，如密码确认）

5.2 手动检查 ModelState（非 ApiController 时）

1
2
3
4
5
6
7


[HttpPost]
public ActionResult Create(CreateUserDto dto)
{
 if (!ModelState.IsValid)
 return BadRequest(ModelState); // 返回验证错误详情
 // ...
}

5.3 FluentValidation（复杂验证）

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


// 安装：FluentValidation.AspNetCore
public class CreateUserDtoValidator : AbstractValidator<CreateUserDto>
{
 public CreateUserDtoValidator()
 {
 RuleFor(x => x.Username).NotEmpty().Length(3, 20);
 RuleFor(x => x.Email).NotEmpty().EmailAddress();
 RuleFor(x => x.Password).NotEmpty().MinimumLength(8)
 .Must(p => p.Any(char.IsDigit)).WithMessage("密码必须包含数字");
 RuleFor(x => x.Age).InclusiveBetween(0, 150);
 }
}
// 自动接入 ModelState，和 DataAnnotations 一样自动 400

1
2
3
4


DataAnnotations vs FluentValidation：
 DataAnnotations — 简单、内置、声明式、适合简单规则
 FluentValidation — 强大、流式、易测试、适合复杂业务规则
 大型项目推荐 FluentValidation

六、小结

路由：API 用特性路由（[Route] + [HttpGet]），支持模板和约束
控制器：API 继承 ControllerBase，加 [ApiController] 享便利（自动 400、推断绑定）
Minimal API：轻量端点写法，适合小项目/微服务
模型绑定：[FromRoute]/[FromQuery]/[FromBody]/[FromHeader]/[FromServices]
验证：DataAnnotations（简单）或 FluentValidation（复杂），自动 400

下一篇讲认证与授权：JWT、Cookie、基于策略的权限控制。

ASP.NET Core 学习笔记（一）：基础架构与启动流程

Wed, 22 Apr 2026 10:00:00 +0800

写在前面

本文是 ASP.NET Core 学习笔记系列的第一篇。ASP.NET Core 是 .NET 后端的核心框架，但它和老的 ASP.NET（Framework）差别极大——完全重写、跨平台、高性能、模块化。很多人用着用着会觉得"能跑但不清楚为什么这么设计"。

本系列从架构层面讲透 ASP.NET Core。第一篇聚焦最核心的两件事：中间件管道和依赖注入——理解了这两个，整个框架就通了。

版本说明：基于 .NET 8 LTS。从 .NET 6 起统一用 Program.cs（top-level statements），不再有 Startup.cs。

一、ASP.NET Core 是什么

1.1 定义

ASP.NET Core 是微软的开源、跨平台、高性能 Web 框架，用来构建 Web 应用、API、微服务、实时应用（SignalR）等。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


它能构建：
 - Web API（RESTful 后端，最常见）
 - Web 应用（MVC、Razor Pages、Blazor）
 - 实时应用（SignalR、WebSocket）
 - 后台服务（Worker Service）
 - gRPC 服务
 - 微服务

跨平台：
 Windows / Linux / macOS 都能跑
 部署到裸机、容器、K8s、云函数都行

1.2 和老 ASP.NET 的区别

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


 ASP.NET (Framework) ASP.NET Core
────────────────────────────────────────────────────────────────
平台 仅 Windows 跨平台
运行时 .NET Framework .NET Core / 5+
Web 服务器 IIS Kestrel（内置）+ 反向代理
配置 web.config 多源配置（json/env/命令行）
依赖注入 需第三方 内置（一等公民）
性能 一般 极高（TechEmpower 前列）
模块化 整体框架 按需引入 NuGet 包
开源 否 是（MIT）

1.3 设计哲学

ASP.NET Core 的所有设计围绕两个核心：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


1. 中间件管道（Middleware Pipeline）
 请求像流水线一样依次经过一个个中间件
 每个中间件处理一件事（认证、日志、路由、CORS...）
 组合优于继承，按需组装

2. 依赖注入（Dependency Injection）无处不在
 所有组件通过 DI 容器管理
 面向接口编程，解耦
 内置 DI 容器，无需第三方

 理解这两点 = 理解 ASP.NET Core 的一切

二、Program.cs 与启动流程

2.1 最简启动

.NET 6+ 之后，Program.cs 用 top-level statements，几行就能启动一个 API：

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


// Program.cs
var builder = WebApplication.CreateBuilder(args);

// 注册服务（DI）
builder.Services.AddControllers();

var app = builder.Build();

// 配置中间件管道
app.UseHttpsRedirection();
app.UseAuthorization();
app.MapControllers();

app.Run(); // 启动，开始监听

这五行做了非常多的事。拆开看。

2.2 启动流程详解

 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


1. WebApplication.CreateBuilder(args)
 创建 WebApplicationBuilder，预配置：
 - Kestrel（Web 服务器）
 - 配置系统（appsettings.json、环境变量、命令行）
 - 日志系统
 - 依赖注入容器
 - 泛型 Host
 → 返回 builder，你通过它继续配置

2. builder.Services.AddXxx()
 向 DI 容器注册服务
 这里注册的东西，后面能通过构造函数注入
 例：AddControllers、AddDbContext、AddSwagger、AddHttpClient

3. builder.Build()
 构建 WebApplication 实例
 此后不能再注册服务（容器已固化）
 转入"配置中间件"阶段

4. app.UseXxx() / app.MapXxx()
 组装中间件管道、映射端点
 顺序很重要！（后面详述）

5. app.Run()
 启动应用，开始监听 HTTP 请求
 阻塞主线程，直到应用停止

1
2
3
4
5


关键分水岭：builder.Build()
 Build 之前 → 注册阶段（配服务、配配置）
 Build 之后 → 运行阶段（配中间件、配管道）

 不能在 Build 后注册服务，不能在 Build 前加中间件

2.3 两个阶段的清晰对照

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


var builder = WebApplication.CreateBuilder(args);

// ========== 注册阶段（builder）==========
builder.Services.AddControllers();
builder.Services.AddDbContext<AppDb>(opt => opt.UseSqlServer("..."));
builder.Services.AddScoped<IUserService, UserService>();
builder.Logging.AddConsole();

var app = builder.Build(); // ← 分水岭

// ========== 管道阶段（app）==========
app.UseExceptionHandler();
app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseRouting();
app.UseAuthentication();
app.UseAuthorization();
app.MapControllers();

app.Run(); // ← 启动

三、中间件管道（核心）

中间件管道是 ASP.NET Core 处理请求的主干道。每个请求依次穿过所有中间件，响应再原路返回。

3.1 管道模型

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


请求 → [中间件1] → [中间件2] → [中间件3] → [端点处理] → 返回
 │ │ │ │
 │ │ │ │
响应 ← [中间件1] ← [中间件2] ← [中间件3] ←─────┘

 每个中间件：
 - 处理请求（进）→ 调用下一个 → 处理响应（出）
 - 可以决定是否调用下一个（短路）

 像洋葱模型：层层进入，层层出来

3.2 三种写法

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


// 写法一：app.Use —— 最通用，可以调用下一个
app.Use(async (context, next) =>
{
 // 进：处理请求（before）
 Console.WriteLine("请求进来");
 await next(); // 调用下一个中间件
 // 出：处理响应（after）
 Console.WriteLine("响应出去");
});

// 写法二：app.Run —— 终结中间件，不调用下一个（管道终点）
app.Run(async context =>
{
 await context.Response.WriteAsync("Hello");
});

// 写法三：app.Map —— 按路径分支
app.Map("/api", apiApp =>
{
 apiApp.Run(async ctx => await ctx.Response.WriteAsync("API"));
});

3.3 顺序非常重要

中间件的注册顺序决定执行顺序，错了会导致功能异常：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


// ✅ 正确顺序（官方推荐）
app.UseExceptionHandler(); // 1. 异常处理（最外层，兜底）
app.UseHsts(); // 2. HSTS
app.UseHttpsRedirection(); // 3. HTTP→HTTPS
app.UseStaticFiles(); // 4. 静态文件
app.UseRouting(); // 5. 路由匹配
app.UseCors(); // 6. CORS
app.UseAuthentication(); // 7. 认证（谁是谁）
app.UseAuthorization(); // 8. 授权（能干什么）
app.UseSession(); // 9. Session（按需）
app.MapControllers(); // 10. 端点执行

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


为什么顺序重要：
 UseRouting 必须在 UseAuthorization 之前
 → 先匹配出端点，才能对端点做授权检查

 UseAuthentication 必须在 UseAuthorization 之前
 → 先认证身份（填充 User），才能判断权限

 UseExceptionHandler 必须在最前面
 → 任何中间件抛异常都能被它兜住

 记忆：异常 → 协议 → 静态 → 路由 → CORS → 认证 → 授权 → 端点

3.4 自定义中间件

复杂中间件建议封装成类，而不是内联 lambda：

 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
30
31
32
33
34
35
36
37
38
39


// 自定义中间件类（约定：有 InvokeAsync 方法）
public class RequestTimingMiddleware
{
 private readonly RequestDelegate _next;
 private readonly ILogger<RequestTimingMiddleware> _logger;

 public RequestTimingMiddleware(RequestDelegate next, ILogger<RequestTimingMiddleware> logger)
 {
 _next = next;
 _logger = logger;
 }

 public async Task InvokeAsync(HttpContext context)
 {
 var sw = Stopwatch.StartNew();
 try
 {
 await _next(context); // 调下一个
 }
 finally
 {
 sw.Stop();
 _logger.LogInformation("{Method} {Path} 耗时 {Ms}ms",
 context.Request.Method, context.Request.Path, sw.ElapsedMilliseconds);
 }
 }
}

// 扩展方法（优雅注册）
public static class RequestTimingExtensions
{
 public static IApplicationBuilder UseRequestTiming(this IApplicationBuilder app)
 {
 return app.UseMiddleware<RequestTimingMiddleware>();
 }
}

// Program.cs 里用
app.UseRequestTiming();

四、依赖注入（核心）

ASP.NET Core 的 DI 是一等公民——所有组件都通过 DI 管理。理解 DI 是写出松耦合、可测试代码的关键。

4.1 三种生命周期

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


// 1. Transient —— 每次请求都新建（最轻量，最常用）
builder.Services.AddTransient<IEmailSender, SmtpEmailSender>();
// 每次注入都拿新实例

// 2. Scoped —— 每个 HTTP 请求一个（请求内共享）
builder.Services.AddScoped<IUserService, UserService>();
// 同一个 HTTP 请求内拿到同一个实例，请求结束释放
// EF Core 的 DbContext 默认是 Scoped

// 3. Singleton —— 全局唯一（应用生命周期）
builder.Services.AddSingleton<IClock, SystemClock>();
// 所有请求共享一个实例，应用停止才释放

1
2
3
4
5
6
7
8


生命周期选择：
 Transient → 轻量、无状态的服务
 Scoped → 需要在一次请求内共享（DbContext、当前用户上下文）
 Singleton → 全局共享、线程安全、重资源（缓存、配置、连接池）

 ⚠️ 陷阱：
 Singleton 不能依赖 Scoped 服务（Scoped 在请求间释放，Singleton 持有会出错）
 反过来可以：Scoped 可以依赖 Singleton/Transient

4.2 注册方式

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


// 接口到实现
builder.Services.AddScoped<IUserService, UserService>();

// 多实现（注入时用 IEnumerable<IUserService> 拿全部）
builder.Services.AddScoped<INotifier, EmailNotifier>();
builder.Services.AddScoped<INotifier, SmsNotifier>();

// 工厂注册（需要复杂构造）
builder.Services.AddScoped<IConnectionFactory>(sp =>
{
 var config = sp.GetRequiredService<IConfiguration>();
 return new ConnectionFactory(config.GetConnectionString("Db"));
});

// 自身注册（不需要接口）
builder.Services.AddScoped<UserService>();

// TryAdd（不存在才注册，避免覆盖）
builder.Services.TryAddScoped<IUserService, UserService>();

4.3 注入方式

 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 UserController : ControllerBase
{
 private readonly IUserService _userService;
 private readonly ILogger<UserController> _logger;

 public UserController(IUserService userService, ILogger<UserController> logger)
 {
 _userService = userService;
 _logger = logger;
 }
}

// [FromServices] 注入（Minimal API、单个方法用）
app.MapGet("/users", ([FromServices] IUserService svc) => svc.GetAll());

// IServiceProvider 手动解析（少用，需要时）
public class Worker
{
 private readonly IServiceProvider _sp;
 public Worker(IServiceProvider sp) => _sp = sp;

 public void DoWork()
 {
 using var scope = _sp.CreateScope(); // 手动创建 Scope
 var svc = scope.ServiceProvider.GetRequiredService<IUserService>();
 svc.DoSomething();
 }
}

4.4 一个完整示例

 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
30
31
32
33
34
35
36


// 接口
public interface IUserService
{
 Task<User> GetUserAsync(int id);
}

// 实现
public class UserService : IUserService
{
 private readonly AppDbContext _db; // Scoped
 private readonly ICache _cache; // Singleton
 private readonly ILogger<UserService> _logger;

 // 构造函数注入三个依赖
 public UserService(AppDbContext db, ICache cache, ILogger<UserService> logger)
 {
 _db = db; _cache = cache; _logger = logger;
 }

 public async Task<User> GetUserAsync(int id) => await _db.Users.FindAsync(id);
}

// 注册
builder.Services.AddDbContext<AppDbContext>(); // Scoped
builder.Services.AddSingleton<ICache, MemoryCache>(); // Singleton
builder.Services.AddScoped<IUserService, UserService>(); // Scoped

// 使用
public class UserController : ControllerBase
{
 private readonly IUserService _userService;
 public UserController(IUserService userService) => _userService = userService;

 [HttpGet("{id}")]
 public async Task<User> Get(int id) => await _userService.GetUserAsync(id);
}

五、配置系统

ASP.NET Core 的配置非常强大——多源、分层、强类型。

5.1 配置源

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


// 默认按顺序读取（后者覆盖前者）：
// 1. appsettings.json
// 2. appsettings.{Environment}.json （如 appsettings.Production.json）
// 3. 用户机密（开发环境，secrets.json）
// 4. 环境变量
// 5. 命令行参数

// 读取配置
var connStr = builder.Configuration.GetConnectionString("DefaultConnection");
var name = builder.Configuration["AppName"];

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


// appsettings.json
{
 "AppName": "MyBlog",
 "ConnectionStrings": {
 "DefaultConnection": "Server=...;Database=...;"
 },
 "Jwt": {
 "Issuer": "jiwei.space",
 "ExpiresMinutes": 60,
 "Secret": "..."
 }
}

5.2 强类型选项（Options 模式）

不要到处用字符串 key 读配置，用强类型 Options：

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


// 1. 定义配置类
public class JwtOptions
{
 public string Issuer { get; set; }
 public int ExpiresMinutes { get; set; }
 public string Secret { get; set; }
}

// 2. 绑定
builder.Services.Configure<JwtOptions>(builder.Configuration.GetSection("Jwt"));

// 3. 注入使用
public class TokenService
{
 private readonly JwtOptions _jwt;
 public TokenService(IOptions<JwtOptions> options) => _jwt = options.Value;

 public string CreateToken()
 {
 // _jwt.Issuer / _jwt.ExpiresMinutes / _jwt.Secret
 }
}

1
2
3
4
5


IOptions<T> — 单例，启动时绑定，值固定
IOptionsSnapshot<T> — 每个请求重新绑定（配置热更新生效）
IOptionsMonitor<T> — 单例，但能监听变化

 需要配置热更新 → 用 IOptionsSnapshot

六、日志

6.1 基本用法

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


public class UserService
{
 private readonly ILogger<UserService> _logger;

 public UserService(ILogger<UserService> logger) => _logger = logger;

 public void Login(string username)
 {
 _logger.LogInformation("用户 {Username} 登录", username);
 _logger.LogWarning("用户 {Username} 登录失败次数过多", username);
 _logger.LogError(ex, "登录异常 {Username}", username);
 }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


日志级别（从低到高）：
 Trace < Debug < Information < Warning < Error < Critical

 生产通常设 Information 或 Warning（过滤掉 Debug/Trace）

结构化日志（重要）：
 ✅ _logger.LogInformation("用户 {Username} 登录", username);
 → 占位符 {Username} 是结构化字段，日志系统能按字段检索
 
 ❌ _logger.LogInformation($"用户 {username} 登录");
 → 字符串插值，丢失结构化信息，无法按字段查询

6.2 配置

1
2
3
4
5
6
7
8
9


// appsettings.json
{
 "Logging": {
 "LogLevel": {
 "Default": "Information",
 "Microsoft.AspNetCore": "Warning"
 }
 }
}

1
2
3
4


// Program.cs 加日志提供程序
builder.Logging.AddConsole();
builder.Logging.AddDebug();
builder.Logging.AddSeq(); // Serlog Seq 等

七、Host 与 Kestrel

7.1 泛型 Host

ASP.NET Core 跑在泛型 Host 之上，统一管理：

1
2
3
4
5
6
7
8
9


Host 管理的东西：
 - 依赖注入容器
 - 配置
 - 日志
 - 生命周期（启动、停止）
 - 后台服务（IHostedService）

 WebApplication.CreateBuilder 自动配好了一个带 Web 功能的 Host
 Worker Service 用纯 Host（无 Web）

7.2 Kestrel（内置 Web 服务器）

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


Kestrel 是 ASP.NET Core 自带的跨平台 Web 服务器：
 ✓ 跨平台（Windows/Linux/macOS）
 ✓ 极高性能（基于 Pipelines、异步全链路）
 ✓ 内置，不需要 IIS/Nginx 也能跑

生产部署架构：
 客户端 → Nginx（反向代理，HTTPS）→ Kestrel（HTTP）

 为什么前面要 Nginx：
 - HTTPS 终端（Kestrel 处理 HTTP）
 - 静态文件、缓存、限流
 - 更成熟的安全防护
 （详见本站 Nginx 系列）

1
2
3
4
5
6


// 配置 Kestrel
builder.WebHost.ConfigureKestrel(options =>
{
 options.Limits.MaxConcurrentConnections = 10000;
 options.Limits.MaxRequestBodySize = 10 * 1024 * 1024; // 10MB
});

八、环境与配置

8.1 环境标识

1
2
3
4
5
6
7
8


通过环境变量 ASPNETCORE_ENVIRONMENT 设置：
 Development — 开发（本地）
 Staging — 预发布
 Production — 生产

 不同环境加载不同配置文件：
 Development → appsettings.json + appsettings.Development.json
 Production → appsettings.json + appsettings.Production.json

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


// 代码里判断环境
var env = builder.Environment;

if (env.IsDevelopment())
{
 app.UseSwagger();
 app.UseDeveloperExceptionPage(); // 开发显示详细错误
}
else
{
 app.UseExceptionHandler("/error"); // 生产用友好错误页
 app.UseHsts();
}

8.2 启动配置

1
2
3
4
5
6
7
8


# 设置环境
export ASPNETCORE_ENVIRONMENT=Production

# 设置监听端口
export ASPNETCORE_URLS=http://0.0.0.0:5000

# 启动
dotnet run

九、小结

本文是 ASP.NET Core 系列的开篇，建立了整体认知：

定位：跨平台、高性能、模块化的现代 Web 框架
两大支柱：中间件管道（处理请求）+ 依赖注入（管理组件）
启动流程：CreateBuilder → 注册服务 → Build → 配置中间件 → Run
中间件管道：请求像洋葱层层穿过，顺序非常重要
依赖注入：三种生命周期（Transient/Scoped/Singleton），构造函数注入
配置：多源 + 强类型 Options 模式
日志：ILogger 结构化日志
Host/Kestrel：泛型 Host 管理生命周期，Kestrel 是高性能内置服务器

核心心法：理解了中间件管道和依赖注入，ASP.NET Core 就理解了一半。 后续所有功能（路由、认证、EF Core）都是建立在这两个基础上的。

下一篇将讲路由与控制器：URL 如何匹配到代码、数据如何绑定、请求如何验证。