企业官网建设流程全解析

简介：这是一份面向C#初学者与Web后端开发入门者的ASP.NET WebAPI实战示例代码包，聚焦RESTful服务构建与SQL Server数据交互核心能力。资源提供一个已搭建完成的基础WebAPI项目，涵盖控制器设计、模型定义、Entity Framework或ADO.NET数据访问层实现、标准路由配置及JSON/XML响应处理等关键环节，但暂未集成用户认证与缓存机制，便于学习者理解底层逻辑并逐步扩展。压缩包为ZIP格式，大小172.56MB，虽文件总数未提供，但根据描述可推知包含Controllers、Models、DAL、Global.asax.cs等典型WebAPI项目结构文件，覆盖从HTTP动词映射到数据库CRUD的完整链路。目前已有293人学习下载，适合用于课堂实验、自学复现或作为企业级API开发的起点模板，帮助开发者快速掌握WebAPI工程化落地的关键模块与常见实践模式。

1. 这不是“Hello World”式 WebAPI：一个能连 SQL Server、带完整 CRUD 和 JWT 鉴权的 C# WebAPI 实战模板

你手头正赶一个内部系统接口，要求三天内交付基础用户管理模块——增删改查要稳，数据库得是 SQL Server，前端要能用 Axios 调通，还得防未授权访问。这时候点开 GitHub 搜 “c# webapi demo”，满屏是只返回{"message":"ok"}的空壳项目，或者硬编码连接字符串、没迁移脚本、JWT 秘钥写死在appsettings.json里的“教学玩具”。这个资源不是那样。它是一个我在线上跑过 11 个月、支撑过 3 个模拟项目X 的 C# WebAPI 骨架：基于 .NET 6（兼容 .NET 7/8），用 Entity Framework Core 7 操作 SQL Server，含 Code-First 迁移脚本、分层结构（Controllers / Services / Repositories / DTOs）、JWT Bearer 鉴权闭环、以及关键路径的单元测试桩。它不教你怎么装 Visual Studio，但保证你dotnet restore && dotnet run后，用 Postman 发一条带 token 的GET /api/users就能拿到真实数据——前提是你的本地 SQL Server 实例开着，且你改对了连接字符串。适合刚脱离 ASP.NET Core 教程、正面对第一个真实后端任务的开发者，也适合需要快速搭出合规骨架、再往里填业务逻辑的某公司后端工程师。

2. 从零启动：环境准备、项目结构与核心依赖解析

2.1 环境清单与最低可行配置

这个模板严格遵循 .NET 官方 LTS 版本策略，目标框架为net6.0。这意味着你不需要最新预览版 SDK，但必须避开已淘汰的 .NET 5 或更早版本。实测通过的最小环境组合如下：

提示：不要用dotnet new webapi命令生成新项目再往里塞代码。这个模板的目录结构是刻意设计的——Data/下放ApplicationDbContext.cs和迁移文件夹，Models/仅存领域实体（如User.cs），DTOs/存传输对象（如UserDto.cs），Services/不直接操作 DbContext，而是通过 Repository 接口。这种分层不是炫技，是为后续加缓存、换数据库、写集成测试留出扩展缝。

2.2 项目结构深度拆解：为什么这样组织？

打开解压后的根目录，你会看到标准的.sln文件和WebApiDemo.csproj。重点看这五个文件夹：

• Data/：EF Core 的心脏。ApplicationDbContext.cs继承自Microsoft.EntityFrameworkCore.DbContext，重写了OnModelCreating方法，用 Fluent API 配置User实体的主键、索引和关系（例如builder.Entity<User>().HasIndex(u => u.Email).IsUnique()）。Migrations/文件夹下有20230515082233_InitialCreate.cs——这是首次运行dotnet ef migrations add InitialCreate生成的快照，包含建表 SQL。关键点：迁移文件名中的时间戳是精确到秒的，避免多人协作时命名冲突；Up(MigrationBuilder migrationBuilder, ...)方法里没有手写 SQL，全部由 EF Core 自动翻译，保证跨数据库可移植性（虽然本项目锁定 SQL Server）。

• Models/：纯 C# 类，无属性装饰。User.cs只有public int Id { get; set; }、public string Email { get; set; }等字段，不加[Required]或[StringLength]。验证逻辑下沉到 DTO 层，模型层保持“干净”，方便未来做 DDD 聚合根演进。

• DTOs/：UserDto.cs和UserCreateDto.cs分离读写契约。前者用于 GET 响应（含Id,Email,CreatedAt），后者用于 POST 请求体（不含Id，Email标记[EmailAddress]）。这种分离避免了PATCH更新时意外覆盖只读字段，也防止前端传入恶意字段（如IsAdmin = true）。

• Repositories/：IUserRepository.cs定义Task<User?> GetByIdAsync(int id)等方法，UserRepository.cs实现它。注意：实现类构造函数接收ApplicationDbContext，但所有查询都用await context.Users.FindAsync(id)而非context.Users.FirstOrDefaultAsync(u => u.Id == id)——因为FindAsync会先查 Change Tracker 缓存，性能更好；且FindAsync对主键查询是 EF Core 推荐的“黄金路径”。

• Services/：IUserService.cs定义业务契约（如Task<bool> CreateUserAsync(UserCreateDto dto)），UserService.cs实现它。这里做密码哈希（用PasswordHasher<T>）、邮箱唯一性校验（调用IUserRepository.ExistsByEmailAsync(dto.Email)）、事务包装（using var transaction = await context.Database.BeginTransactionAsync()）。血泪经验：所有 Service 方法必须是async Task，绝不能用.Result或.Wait()，否则在高并发下线程池饥饿，API 响应延迟飙升。

2.3 核心 NuGet 包作用与版本锁定逻辑

WebApiDemo.csproj中引用了 7 个关键包，版本号均经线上压测验证：

<PackageReference Include="Microsoft.EntityFrameworkCore.SqlServer" Version="7.0.11" /> <PackageReference Include="Microsoft.EntityFrameworkCore.Tools" Version="7.0.11" /> <PackageReference Include="Microsoft.AspNetCore.Authentication.JwtBearer" Version="6.0.22" /> <PackageReference Include="System.IdentityModel.Tokens.Jwt" Version="6.32.1" /> <PackageReference Include="Microsoft.AspNetCore.Mvc.NewtonsoftJson" Version="6.0.22" /> <PackageReference Include="Microsoft.Extensions.DependencyInjection.Abstractions" Version="6.0.0" /> <PackageReference Include="Microsoft.Data.SqlClient" Version="5.1.1" />

• Microsoft.EntityFrameworkCore.SqlServer 7.0.11：EF Core 7 的 SQL Server 提供程序。选 7.x 而非 8.x 是因 8.0 初期存在DateTimeOffset在某些时区下的精度丢失 Bug，该 Bug 在 7.0.11 中已修复。
• Microsoft.AspNetCore.Authentication.JwtBearer 6.0.22：.NET 6 的 JWT 鉴权中间件。必须与项目目标框架一致，若升级到 .NET 7，此包需同步升至7.0.11，否则AddJwtBearer扩展方法找不到。
• System.IdentityModel.Tokens.Jwt 6.32.1：JWT 令牌解析核心库。版本 6.32.1 修复了 HS256 算法在高并发下偶发签名验证失败的问题（现象是 0.3% 请求返回 401）。
• Microsoft.Data.SqlClient 5.1.1：取代旧版System.Data.SqlClient。支持 Always Encrypted、Azure AD 认证，且内存占用比旧版低 18%（实测 10K 并发时 GC 压力下降明显）。

注意：所有包版本号在csproj中显式锁定，禁用floating versions（如7.0.*）。这是生产环境铁律——自动升级可能引入不兼容变更，比如Microsoft.Data.SqlClient 5.2.0移除了SqlConnection.ConnectionStringBuilder的某些属性，导致旧迁移脚本报错。

3. 数据库落地：SQL Server 连接、迁移执行与初始数据注入

3.1 连接字符串配置与安全实践

模板的appsettings.Development.json中，ConnectionStrings节点定义如下：

{ "ConnectionStrings": { "DefaultConnection": "Server=(localdb)\\mssqllocaldb;Database=WebApiDemoDb;Trusted_Connection=true;MultipleActiveResultSets=true;" } }

• (localdb)\\mssqllocaldb是 SQL Server Express LocalDB 的默认实例名，无需手动启动服务，首次连接时自动激活。
• Database=WebApiDemoDb指定数据库名，EF Core 迁移命令会自动创建该库（如果不存在）。
• Trusted_Connection=true表示 Windows 集成认证，开发阶段最安全——无需明文密码，且权限可控（LocalDB 默认只允许当前 Windows 用户访问）。
• MultipleActiveResultSets=true（MARS）启用多活动结果集，允许单个连接上并行执行多个查询（如foreach循环中嵌套await repository.GetOrdersAsync(userId)），避免InvalidOperationException: There is already an open DataReader。

重要提醒：生产环境绝不可用Trusted_Connection=true。必须切换为 SQL Server 账户认证，并将连接字符串存入 Azure Key Vault 或 Kubernetes Secret。模板中appsettings.Production.json已预留占位符："DefaultConnection": "Server=prod-sql;Database=WebApiDemoProd;User Id=webapi_user;Password=***;"，***需由运维团队注入。

3.2 执行 EF Core 迁移：三步走稳流程

迁移不是“一键生成”，而是分三步精准控制，避免线上库结构混乱：

步骤 1：生成迁移快照（开发机执行）

在项目根目录（含WebApiDemo.csproj的文件夹）打开终端，运行：

dotnet ef migrations add InitialCreate --project WebApiDemo.csproj --startup-project WebApiDemo.csproj --output-dir Data/Migrations --context ApplicationDbContext

• --project指定.csproj文件，--startup-project指定启动项目（确保Program.cs被加载，以读取appsettings.json）。
• --output-dir Data/Migrations强制迁移文件生成到指定目录，避免默认生成到Migrations/下造成路径混乱。
• --context ApplicationDbContext明确指定 DbContext 类名，当项目中有多个 DbContext 时必填。

执行后，Data/Migrations/下新增两个文件：20230515082233_InitialCreate.cs（含Up/Down方法）和20230515082233_InitialCreate.Designer.cs（设计器文件，由 EF Core 自动生成，勿手动修改）。

步骤 2：审查迁移内容（人工必做）

打开InitialCreate.cs，检查Up方法中是否包含预期的建表语句：

migrationBuilder.CreateTable( name: "Users", columns: table => new { Id = table.Column<int>(type: "int", nullable: false) .Annotation("SqlServer:Identity", "1, 1"), Email = table.Column<string>(type: "nvarchar(256)", maxLength: 256, nullable: false), PasswordHash = table.Column<string>(type: "nvarchar(max)", nullable: false), CreatedAt = table.Column<DateTimeOffset>(type: "datetimeoffset", nullable: false) }, constraints: table => { table.PrimaryKey("PK_Users", x => x.Id); table.HasIndex(x => x.Email).IsUnique(); // 关键：邮箱唯一索引 });

• nvarchar(256)是邮箱字段的合理长度（RFC 5321 规定最大 254 字符，加 2 字节余量）。
• IsUnique()确保数据库级唯一约束，比应用层校验更可靠（防止并发注册时漏判）。

步骤 3：应用迁移到数据库（开发/测试环境）

dotnet ef database update --project WebApiDemo.csproj --startup-project WebApiDemo.csproj --context ApplicationDbContext

执行后，LocalDB 自动创建WebApiDemoDb库，并建好Users表及索引。验证方式：用 SSMS 连接(localdb)\mssqllocaldb，展开数据库列表，确认WebApiDemoDb存在且Users表结构正确。

玄学时刻：若执行database update报错A network-related or instance-specific error occurred...，90% 是 LocalDB 未激活。解决方案：运行sqllocaldb start mssqllocaldb（Windows），或重启机器（LocalDB 有时需冷启动）。

3.3 注入初始种子数据：让 API 启动就有可用用户

模板在Program.cs的WebApplication.CreateBuilder后插入了种子逻辑：

var app = builder.Build(); // ... 中间件配置 if (app.Environment.IsDevelopment()) { using (var scope = app.Services.CreateScope()) { var context = scope.ServiceProvider.GetRequiredService<ApplicationDbContext>(); await context.Database.EnsureCreatedAsync(); // 确保库存在 await SeedData.InitializeAsync(context); // 执行种子 } }

SeedData.InitializeAsync方法位于Data/SeedData.cs，核心逻辑：

public static async Task InitializeAsync(ApplicationDbContext context) { if (await context.Users.AnyAsync()) return; // 已有数据则跳过 var hasher = new PasswordHasher<User>(); var users = new List<User> { new User { Email = "admin@example.com", PasswordHash = hasher.HashPassword(null, "P@ssw0rd123"), CreatedAt = DateTimeOffset.UtcNow } }; await context.Users.AddRangeAsync(users); await context.SaveChangesAsync(); }

• EnsureCreatedAsync()是轻量级库初始化，比MigrateAsync()更快（不查迁移历史表），适合开发环境。
• PasswordHasher<User>使用 PBKDF2 算法，盐值随机生成，哈希值存入PasswordHash字段。绝不用 MD5 或 SHA256 明文哈希——那是密码学灾难。

4. RESTful 接口实现：从 Controller 到 Service 的完整链路与参数校验

4.1 UserController 设计：遵循 REST 规范的七个动作

Controllers/UserController.cs实现标准 REST 动作，每个 Action 方法都有明确职责：

关键细节：CreateAsync返回CreatedAtAction而非OkObjectResult：

return CreatedAtAction(nameof(GetByIdAsync), new { id = user.Id }, userDto);

这会在响应头中自动添加Location: /api/users/123，符合 REST 最佳实践，让客户端知道新资源的 URI。

4.2 模型绑定与自动验证：DTO 上的[Required]如何生效

UserCreateDto.cs定义如下：

public class UserCreateDto { [Required(ErrorMessage = "邮箱不能为空")] [EmailAddress(ErrorMessage = "邮箱格式不正确")] [StringLength(256, ErrorMessage = "邮箱长度不能超过 256 字符")] public string Email { get; set; } = string.Empty; [Required(ErrorMessage = "密码不能为空")] [StringLength(100, MinimumLength = 8, ErrorMessage = "密码长度必须在 8-100 字符之间")] public string Password { get; set; } = string.Empty; }

验证生效依赖Program.cs中的全局配置：

builder.Services.AddControllers() .AddJsonOptions(options => { options.JsonSerializerOptions.PropertyNamingPolicy = JsonNamingPolicy.CamelCase; }) .ConfigureApiBehaviorOptions(options => { options.InvalidModelStateResponseFactory = context => { var errors = context.ModelState .Where(e => e.Value.Errors.Count > 0) .SelectMany(e => e.Value.Errors) .Select(e => e.ErrorMessage) .ToArray(); return new BadRequestObjectResult(new { errors }); }; });

• InvalidModelStateResponseFactory重写验证失败响应：返回400 Bad Request，Body 为{ "errors": ["邮箱不能为空", "密码长度必须在 8-100 字符之间"] }，前端可直接遍历errors数组展示。
• JsonSerializerOptions.PropertyNamingPolicy = JsonNamingPolicy.CamelCase确保 JSON 字段名小驼峰（emailAddress），而非 C# 属性名大驼峰（EmailAddress），避免前端反复mapKeys。

4.3 UserService 业务逻辑：事务、异常与幂等性处理

UserService.CreateAsync方法是业务核心，代码精简但覆盖关键场景：

public async Task<UserDto> CreateAsync(UserCreateDto dto) { // 1. 邮箱唯一性校验（数据库级 + 应用级双重保险） if (await _userRepository.ExistsByEmailAsync(dto.Email)) throw new InvalidOperationException($"邮箱 {dto.Email} 已被注册"); // 2. 创建用户实体 var user = new User { Email = dto.Email, PasswordHash = _passwordHasher.HashPassword(null, dto.Password), CreatedAt = DateTimeOffset.UtcNow }; // 3. 事务包装，确保原子性 using var transaction = await _context.Database.BeginTransactionAsync(); try { await _userRepository.AddAsync(user); await _context.SaveChangesAsync(); await transaction.CommitAsync(); return _mapper.Map<UserDto>(user); // AutoMapper 转 DTO } catch { await transaction.RollbackAsync(); throw; // 重新抛出，由全局异常过滤器捕获 } }

• ExistsByEmailAsync查询前先检查缓存（如有），再查数据库，避免高并发下重复注册。
• BeginTransactionAsync显式开启事务，即使_userRepository.AddAsync内部有其他 DB 操作（如日志表写入），也能保证回滚。
• throw;而非throw ex;，保留原始堆栈跟踪，便于定位问题。

避坑 / 常见问题 / 排查

现象 1：POST/api/users返回 500，日志显示SqlException: Cannot insert duplicate key row in object 'Users' with unique index 'IX_Users_Email'
原因：ExistsByEmailAsync和AddAsync之间存在微小时间窗口，两个并发请求同时通过校验，然后都尝试插入相同邮箱。
解决：在User实体的OnModelCreating中，为Email字段添加IsUnique()索引（模板已做），并捕获SqlException.Number == 2601（唯一键冲突），转换为友好的 400 错误：“邮箱已被注册”。

现象 2：PUT/api/users/1更新成功，但UpdatedAt字段未更新
原因：User实体类中未定义UpdatedAt属性，或UpdateAsync方法中未手动赋值user.UpdatedAt = DateTimeOffset.UtcNow。
解决：在User.cs中添加public DateTimeOffset? UpdatedAt { get; set; }，并在UpdateAsync的 Service 方法中设置user.UpdatedAt = DateTimeOffset.UtcNow。

现象 3：调用/api/auth/login返回 200，但响应体为空 JSON{}
原因：LoginAsyncAction 中return Ok(token)的token是字符串，但AddJsonOptions设置了CamelCase，导致字符串被序列化为null。
解决：返回Ok(new { token })，包装成对象，或在LoginAsync中使用JsonConvert.SerializeObject(token)手动序列化。

现象 4：Swagger UI 中/api/users的GET请求，点击Try it out后返回401 Unauthorized，但 Postman 调用正常
原因：Swagger 未配置 JWT Bearer 认证按钮，未在请求头中自动添加Authorization: Bearer <token>。
解决：在Program.cs的AddEndpointsApiExplorer后添加 Swagger JWT 支持：

builder.Services.AddEndpointsApiExplorer(); builder.Services.AddSwaggerGen(c => { c.SwaggerDoc("v1", new OpenApiInfo { Title = "WebApiDemo", Version = "v1" }); c.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme { Description = "JWT Authorization header using the Bearer scheme", Name = "Authorization", In = ParameterLocation.Header, Type = SecuritySchemeType.ApiKey, Scheme = "Bearer" }); c.AddSecurityRequirement(new OpenApiSecurityRequirement { { new OpenApiSecurityScheme { Reference = new OpenApiReference { Type = ReferenceType.SecurityScheme, Id = "Bearer" } }, new string[] {} } }); });

现象 5：部署到 IIS 后，所有 API 返回500.19 Internal Server Error，事件查看器提示Could not load file or assembly 'Microsoft.EntityFrameworkCore.SqlServer'
原因：IIS 应用程序池的 .NET CLR 版本设置为No Managed Code或v4.0，而非v6.0。
解决：在 IIS 管理器中，右键应用程序池 → “高级设置” → 将.NET CLR 版本改为No Managed Code（.NET Core 应用实际不依赖 CLR 版本，但 IIS 需此设置）→ 重启应用池。

5. JWT 鉴权闭环：密钥管理、Token 签发与中间件拦截

5.1 密钥安全存储与配置注入

JWT 的安全性完全依赖SecretKey不泄露。模板采用分层配置：

• appsettings.Development.json中：

  "JwtSettings": { "SecretKey": "dev-secret-key-change-in-production-1234567890", "Issuer": "WebApiDemo", "Audience": "WebApiDemoClient", "ExpiryMinutes": 60 }

• appsettings.Production.json中，SecretKey必须为空或占位符：

  "JwtSettings": { "SecretKey": "***REDACTED***", "Issuer": "WebApiDemo", "Audience": "WebApiDemoClient", "ExpiryMinutes": 30 }

Program.cs中通过IConfiguration注入并验证：

var jwtSettings = builder.Configuration.GetSection("JwtSettings"); var secretKey = jwtSettings["SecretKey"]; if (string.IsNullOrWhiteSpace(secretKey) || secretKey.Length < 32) throw new InvalidOperationException("JWT SecretKey must be at least 32 characters in production."); var key = Encoding.ASCII.GetBytes(secretKey); builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme) .AddJwtBearer(options => { options.TokenValidationParameters = new TokenValidationParameters { ValidateIssuerSigningKey = true, IssuerSigningKey = new SymmetricSecurityKey(key), ValidateIssuer = true, ValidIssuer = jwtSettings["Issuer"], ValidateAudience = true, ValidAudience = jwtSettings["Audience"], ValidateLifetime = true, ClockSkew = TimeSpan.Zero // 严格校验过期时间 }; });

• ClockSkew = TimeSpan.Zero关闭 5 分钟默认宽容期，防止时钟不同步导致的鉴权漂移。
• ValidateIssuerSigningKey = true强制校验签名密钥，禁用none算法攻击。

5.2 Login 接口实现：从凭据验证到 Token 生成

AuthController.LoginAsync是鉴权入口：

[HttpPost("login")] [AllowAnonymous] public async Task<ActionResult<AuthResponse>> LoginAsync([FromBody] LoginDto loginDto) { // 1. 邮箱查找用户 var user = await _userRepository.FindByEmailAsync(loginDto.Email); if (user == null) return Unauthorized(new { message = "邮箱或密码错误" }); // 2. 密码验证（使用 PasswordHasher） var result = _passwordHasher.VerifyHashedPassword(user, user.PasswordHash, loginDto.Password); if (result == PasswordVerificationResult.Failed) return Unauthorized(new { message = "邮箱或密码错误" }); // 3. 生成 JWT Token var token = _jwtService.GenerateToken(user); return Ok(new AuthResponse { Token = token, ExpiresIn = TimeSpan.FromMinutes(_jwtSettings.ExpiryMinutes).TotalSeconds }); }

_jwtService.GenerateToken方法（Services/JwtService.cs）：

public string GenerateToken(User user) { var tokenHandler = new JwtSecurityTokenHandler(); var key = Encoding.ASCII.GetBytes(_jwtSettings.SecretKey); var tokenDescriptor = new SecurityTokenDescriptor { Subject = new ClaimsIdentity(new[] { new Claim(ClaimTypes.NameIdentifier, user.Id.ToString()), new Claim(ClaimTypes.Email, user.Email), new Claim("role", "user") // 可扩展为 admin/reader 等 }), Expires = DateTime.UtcNow.AddMinutes(_jwtSettings.ExpiryMinutes), Issuer = _jwtSettings.Issuer, Audience = _jwtSettings.Audience, SigningCredentials = new SigningCredentials( new SymmetricSecurityKey(key), SecurityAlgorithms.HmacSha256Signature) }; var token = tokenHandler.CreateToken(tokenDescriptor); return tokenHandler.WriteToken(token); }

• ClaimTypes.NameIdentifier是标准声明，HttpContext.User.Identity.Name会自动映射为该值，方便后续User.Identity.Name获取用户 ID。
• new Claim("role", "user")为 RBAC（基于角色的访问控制）预留扩展点，[Authorize(Roles = "admin")]即可启用。

5.3 授权策略与细粒度控制：[Authorize]的三种用法

模板中UserController的[Authorize]特性有三层用法：

• 全局保护：在Program.cs中注册控制器路由前，添加：

  app.UseAuthentication(); app.UseAuthorization();

  此后所有[ApiController]默认需认证（除非显式标记[AllowAnonymous]）。

• 控制器级：[Authorize]加在UserController类上，表示所有 Action 需登录。

  [ApiController] [Route("api/[controller]")] [Authorize] // ← 全局要求 public class UserController : ControllerBase { ... }

• Action 级：[Authorize(Roles = "admin")]加在特定方法上，如DeleteAsync：

  [HttpDelete("{id}")] [Authorize(Roles = "admin")] // ← 仅管理员可删 public async Task<IActionResult> DeleteAsync(int id) { ... }

• 策略级：在Program.cs中定义自定义策略：

  builder.Services.AddAuthorization(options => { options.AddPolicy("RequireAdminRole", policy => policy.RequireRole("admin")); options.AddPolicy("RequireSameUserOrAdmin", policy => policy.RequireAssertion(context => context.User.IsInRole("admin") || context.User.FindFirst(ClaimTypes.NameIdentifier)?.Value == context.Resource?.ToString())); });

  然后在 Action 上用[Authorize(Policy = "RequireSameUserOrAdmin")]，实现“只能删自己的数据或管理员可删所有”。

避坑 / 常见问题 / 排查

现象 1：调用/api/users/me返回401 Unauthorized，但Authorization请求头已正确设置Bearer <token>
原因：JWT Token 中的exp（过期时间）已过，或服务器时间比客户端快，导致DateTime.UtcNow计算的Expires已失效。
解决：检查服务器系统时间是否准确（w32tm /query /status），或临时将ClockSkew设为TimeSpan.FromMinutes(5)调试。

现象 2：Swagger UI 中点击Authorize按钮输入 Token 后，所有请求头仍无Authorization
原因：Swagger 的Authorize按钮只影响当前浏览器会话，且需在AddSwaggerGen配置中正确设置AddSecurityDefinition和AddSecurityRequirement（见 4.3 节解决方法）。
解决：确认AddSwaggerGen配置代码已添加，重启应用，刷新 Swagger 页面，重新点击Authorize。

现象 3：HttpContext.User.Identity.IsAuthenticated始终为false，即使 Token 有效
原因：UseAuthentication()中间件位置错误，放在UseAuthorization()之后，或未在UseRouting()之后、UseEndpoints()之前调用。
解决：严格按顺序排列中间件：

app.UseRouting(); app.UseAuthentication(); // ← 必须在 UseAuthorization 之前 app.UseAuthorization(); app.UseEndpoints(endpoints => { ... });

现象 4：生成的 Token 在 JWT.io 解析时，Header中alg显示HS256，但Payload中无iss、aud字段
原因：SecurityTokenDescriptor中未设置Issuer和Audience属性，或ValidateIssuer/ValidateAudience设为false。
解决：确保tokenDescriptor.Issuer和tokenDescriptor.Audience已赋值，且TokenValidationParameters中ValidateIssuer = true、ValidateAudience = true。

现象 5：部署到 Linux 服务器后，GenerateToken抛出System.Security.Cryptography.CryptographicException: The requested cryptographic algorithm is not supported on this platform.
原因：Linux 系统缺少libssl或libicu依赖，导致HmacSha256Signature不可用。
解决：在 Ubuntu/Debian 上运行sudo apt-get install libssl-dev libicu-dev，或改用RSA算法（需生成 RSA 密钥对，复杂度上升）。

6. 生产就绪技巧：日志埋点、健康检查与部署验证清单

6.1 结构化日志：用 Serilog 替代 ConsoleLogger

模板已集成 Serilog，替代默认的ConsoleLogger。Program.cs中：

// 替换默认日志提供程序 builder.Host.UseSerilog((context, services, configuration) => configuration .ReadFrom.Configuration(context.Configuration) .WriteTo.Console() .WriteTo.File("logs/webapi-.txt", rollingInterval: RollingInterval.Day) .Enrich.FromLogContext() .Enrich.WithMachineName() .Enrich.WithProcessId() .Enrich.WithThreadId());

appsettings.json中配置日志级别：

"Serilog": { "MinimumLevel": { "Default": "Information", "Override": { "Microsoft": "Warning", "System": "Warning" } } }

关键日志埋点在UserService.CreateAsync：

_logger.LogInformation("User creation started for email: {Email}", dto.Email); // ... 业务逻辑 _logger.LogInformation("User created successfully. UserId: {UserId}", user.Id);

• {Email}和{UserId}是结构化日志占位符，日志文件中会生成 JSON 格式，方便 ELK 或 Seq 搜索（如Email: "test@example.com"）。
• Enrich.WithMachineName()添加服务器主机名，多实例部署时可区分日志来源。

6.

本文还有配套的精品资源，点击获取