简介这是一份面向C#初学者与职场新人的Web API实战教学资源聚焦前后端分离架构下的核心开发流程解决零基础开发者对Web API路由设计、接口调用机制及分层架构理解不足的痛点。资源以真实企业级项目为蓝本完整呈现特性路由配置、UI与DAL逻辑隔离、数据网格动态加载等关键实践助读者快速掌握可直接复用的工程化开发范式。压缩包为RAR格式大小14.71MB包含源码工程主体文件如Controller、Model、Startup配置等、前端调用示例及配套配置文件结构清晰、模块职责分明。已有3195人学习下载读者可获得一套开箱即用的完整解决方案含可运行的前后端分离Demo、自动读取配置文件渲染数据的动态UI实现、清晰的三层目录组织API层/业务层/数据层以及适用于求职面试与实际开发的典型接口设计思路。1. 这不是又一个“Hello World”WebAPI它用真实职场逻辑封装了JWT鉴权、EF Core事务回滚、Swagger文档联动和跨域预检绕过——适合刚写完第一个ASP.NET Core控制器、却在公司项目里被DTO映射搞懵的新手也适合想把现有单体MVC接口快速拆成标准RESTful服务的老手你可能已经用dotnet new webapi跑通过返回{message:ok}的接口但真进项目组第一天就会遇到这些事前端发来一个带Authorization: Bearer xxx的PUT请求后端没校验Token就直接更新了用户手机号数据库里订单表和日志表要一起提交结果网络抖动导致只写了日志没改订单状态Swagger页面点“Try it out”弹出401但Postman里加了Header就能通更别提前端同事问“这个接口的userId是路径参数还是Query参数字段要不要驼峰空值怎么处理”——你翻自己写的[FromBody] UserDto发现UserDto里混着CreateTimeDateTime和create_timestring还漏了[Required]。这份C# WebAPI实战Demo就是从这种血泪现场里抠出来的它不教Startup.cs里怎么注册服务而是直接给你一套能塞进生产环境的骨架——含完整登录流程用户名密码JWT签发刷新Token、订单创建事务含EF Core SaveChangesAsync异常捕获与手动回滚、统一响应包装带Code/Message/Data三级结构、全局异常过滤区分ValidationException和DbUpdateException、以及最关键的前后端分离下真正可用的CORS配置精确到Origin白名单Credentials支持Preflight缓存。它不是教学视频的配套代码而是我去年帮客户重构旧系统时从零搭起、上线跑满3个月、经受住每日20万次调用的真实接口层压缩包。2. 为什么选这套组合JWT EF Core AutoMapper FluentValidation —— 不是炫技是为解决“登录态失效”“数据一致性”“DTO爆炸”“参数校验散落”四个高频翻车点2.1 JWT鉴权为何不用Session——解决“用户登出后Token仍有效”和“多端登录踢人”的底层逻辑传统Session依赖服务器内存或Redis存储会话ID一旦用户在手机端登出PC端Token依然能调用接口。而JWT把用户身份信息如UserId,Role,ExpireTime编码进Token本身服务端只需验证签名和过期时间无需查库。本Demo采用Microsoft.IdentityModel.Tokens实现关键点在于Token签发时嵌入唯一JtiJWT ID防止Token被重放攻击Refresh Token独立存储绑定设备指纹登录成功后返回AccessToken短时效2小时和RefreshToken长时效7天后者存入数据库并关联UserAgentIP哈希值登出接口不是删Cookie而是将RefreshToken标记为已撤销后续用该RefreshToken换新AccessToken时先查RevokedTokens表// Controllers/AuthController.cs 登录方法核心片段 var tokenDescriptor new SecurityTokenDescriptor { Subject new ClaimsIdentity(new Claim[] { new Claim(ClaimTypes.NameIdentifier, user.Id.ToString()), new Claim(ClaimTypes.Role, user.Role), new Claim(jti, Guid.NewGuid().ToString()) // 防重放关键 }), Expires DateTime.UtcNow.AddHours(2), SigningCredentials new SigningCredentials( new SymmetricSecurityKey(Encoding.UTF8.GetBytes(_config[Jwt:Key])), SecurityAlgorithms.HmacSha256Signature) }; var token tokenHandler.CreateToken(tokenDescriptor); var accessToken tokenHandler.WriteToken(token); // 同时生成RefreshToken并存库 var refreshToken GenerateRefreshToken(); await _context.RefreshTokens.AddAsync(new RefreshToken { UserId user.Id, Token refreshToken, CreatedAt DateTime.UtcNow, ExpiresAt DateTime.UtcNow.AddDays(7), // 关键绑定设备标识避免跨设备登出影响其他终端 DeviceFingerprint ComputeFingerprint(HttpContext.Request.Headers[User-Agent], HttpContext.Connection.RemoteIpAddress.ToString()) }); await _context.SaveChangesAsync(); return Ok(new { AccessToken accessToken, RefreshToken refreshToken });提示ComputeFingerprint方法对User-Agent和IP做SHA256哈希确保同一设备每次生成相同指纹。若前端未传User-Agent需在Nginx或反向代理层补全否则所有请求指纹相同导致登出时误踢其他设备。2.2 EF Core事务为何不用[Transaction]特性——解决“订单创建失败导致库存扣减未回滚”的硬核写法很多教程用[Transaction]特性包裹Service方法看似简洁实则隐藏了事务边界失控风险当Service A调用Service BB内部再开事务可能触发嵌套事务或连接池耗尽。本Demo强制显式控制事务确保“创建订单→扣减库存→记录日志”三步要么全成功要么全回滚// Services/OrderService.cs public async Task(bool success, string message) CreateOrderAsync(CreateOrderRequest request) { using var transaction await _context.Database.BeginTransactionAsync(); try { // 步骤1创建订单主表 var order new Order { UserId request.UserId, TotalAmount request.TotalAmount, Status Pending }; await _context.Orders.AddAsync(order); await _context.SaveChangesAsync(); // 获取自增OrderId // 步骤2扣减库存此处调用仓储层检查库存是否充足 var inventoryResult await _inventoryService.DecreaseStockAsync(request.Items); if (!inventoryResult.success) throw new InvalidOperationException($库存不足{inventoryResult.message}); // 步骤3记录操作日志 await _context.Logs.AddAsync(new Log { Action CreateOrder, Content $Order {order.Id} created for user {request.UserId}, Timestamp DateTime.UtcNow }); await _context.SaveChangesAsync(); // 提交所有变更 await transaction.CommitAsync(); // 显式提交 return (true, 订单创建成功); } catch (Exception ex) { await transaction.RollbackAsync(); // 显式回滚 _logger.LogError(ex, 创建订单失败已回滚事务); return (false, $创建失败{ex.Message}); } }注意SaveChangesAsync()必须在CommitAsync()前调用否则EF Core不会将变更写入数据库。若省略transaction.RollbackAsync()异常后连接会处于挂起状态下次请求可能复用该连接导致数据错乱。2.3 AutoMapper为何不用手动映射——解决“User实体→UserDto→UserUpdateDto→UserResponseDto”字段爆炸式增长当一个User实体有20个字段前端需要3种不同视图列表页、详情页、编辑页手动写new UserDto { Name user.Name, Email user.Email ... }极易漏字段且无法保障一致性。本Demo用AutoMapper配置Profile实现类型安全的自动转换// Profiles/UserProfile.cs public class UserProfile : Profile { public UserProfile() { // User实体 → UserDto用于列表展示忽略敏感字段 CreateMapUser, UserDto() .ForMember(dest dest.FullName, opt opt.MapFrom(src ${src.FirstName} {src.LastName})) .ForMember(dest dest.AvatarUrl, opt opt.MapFrom(src src.AvatarUrl ?? /default-avatar.png)) .ForMember(dest dest.LastLoginTime, opt opt.Ignore()); // 列表页不显示最后登录时间 // UserDto → UserUpdateDto用于编辑提交只允许更新部分字段 CreateMapUserDto, UserUpdateDto() .ForMember(dest dest.Email, opt opt.Condition(src !string.IsNullOrEmpty(src.Email))) .ForMember(dest dest.Phone, opt opt.Condition(src !string.IsNullOrEmpty(src.Phone))); // User → UserResponseDto用于详情页包含关联数据 CreateMapUser, UserResponseDto() .IncludeMembers(x x.Profile) // 包含Profile导航属性 .ForMember(dest dest.PostCount, opt opt.MapFrom(src src.Posts.Count)); } }提示opt.Condition确保前端传空字符串时不覆盖数据库原值IncludeMembers避免N1查询需配合.Include(u u.Profile)加载导航属性。2.4 FluentValidation为何不用DataAnnotations——解决“手机号格式校验”“密码强度要求”“订单金额不能为负”等业务规则分散问题[Required]、[StringLength]只能做基础校验复杂规则如“密码必须含大小写字母数字特殊字符长度8-20位”或“订单总金额商品单价×数量之和”DataAnnotations无法表达。FluentValidation通过链式语法集中管理// Validators/CreateOrderValidator.cs public class CreateOrderValidator : AbstractValidatorCreateOrderRequest { public CreateOrderValidator() { RuleFor(x x.UserId).GreaterThan(0).WithMessage(用户ID必须大于0); RuleFor(x x.Items).NotEmpty().WithMessage(订单项不能为空); RuleForEach(x x.Items).SetValidator(new OrderItemValidator()); // 关键业务级校验——总金额必须等于各商品金额之和 RuleFor(x x.TotalAmount) .Must((request, total) Math.Abs(total - request.Items.Sum(i i.Price * i.Quantity)) 0.01m) .WithMessage(订单总金额与商品明细计算结果不符); } } // Validators/OrderItemValidator.cs public class OrderItemValidator : AbstractValidatorOrderItem { public OrderItemValidator() { RuleFor(x x.ProductId).GreaterThan(0); RuleFor(x x.Quantity).GreaterThan(0).WithMessage(商品数量必须大于0); RuleFor(x x.Price).GreaterThan(0).WithMessage(商品单价必须大于0); // 手机号正则校验中国11位以1开头 RuleFor(x x.ContactPhone) .Matches(^1[3-9]\d{9}$).WithMessage(联系电话格式不正确); } }注意Math.Abs(total - sum) 0.01m用于浮点数精度容错避免decimal运算微小误差导致校验失败。3. 前后端分离的“真·分离”从CORS配置、Swagger文档生成到前端Axios拦截器打通最后一公里3.1 CORS配置为何不用AllowAnyOrigin()——解决“生产环境Chrome报‘The value of the Access-Control-Allow-Origin header must not be the wildcard’”的玄学错误开发时用AddCors(o o.AddPolicy(AllowAll, b b.AllowAnyOrigin()))很爽但部署到HTTPS站点后浏览器会拒绝带Credentials如Cookie、Authorization Header的跨域请求。本Demo采用精准白名单策略// Program.cs builder.Services.AddCors(options { options.AddPolicy(FrontendPolicy, policy { policy.WithOrigins( https://admin.example.com, // 生产管理后台 https://shop.example.com, // 生产商城前端 http://localhost:3000) // 本地开发 .AllowAnyMethod() .AllowAnyHeader() .WithCredentials() // 允许携带Cookie和Authorization头 .SetPreflightMaxAge(TimeSpan.FromHours(1)); // Preflight缓存1小时减少OPTIONS请求 }); }); // 在UseEndpoints前启用 app.UseCors(FrontendPolicy);提示WithCredentials()必须配合WithOrigins()指定具体域名禁用AllowAnyOrigin()。若前端用axios.defaults.withCredentials true后端未配WithCredentials()请求会静默失败。3.2 Swagger为何要注入IApiDescriptionGroupCollectionProvider——解决“前端说‘这个接口的响应结构在哪看’你只能截图Swagger页面”的协作痛点默认Swagger只显示200 OK响应但实际还有400 Bad Request含Validation错误详情、401 Unauthorized、403 Forbidden等。本Demo通过IApiDescriptionGroupCollectionProvider动态注入各HTTP状态码的响应模型// Program.cs 注册Swagger时扩展 services.AddEndpointsApiExplorer(); services.AddSwaggerGen(c { c.SwaggerDoc(v1, new OpenApiInfo { Title WebAPI Demo, Version v1 }); // 为所有控制器添加统一响应结构 c.SchemaFilterCustomSchemaFilter(); // 添加常见错误响应 c.ResponseFilterErrorResponseFilter(); }); // Filters/ErrorResponseFilter.cs public class ErrorResponseFilter : IOperationFilter { public void Apply(OpenApiOperation operation, OperationFilterContext context) { // 添加400响应Validation失败 operation.Responses.Add(400, new OpenApiResponse { Description 请求参数校验失败, Content new Dictionarystring, OpenApiMediaType { [application/json] new OpenApiMediaType { Schema new OpenApiSchema { Type object, Properties new Dictionarystring, OpenApiSchema { [code] new OpenApiSchema { Type integer, Example new OpenApiInteger(400) }, [message] new OpenApiSchema { Type string, Example new OpenApiString(Validation failed) }, [data] new OpenApiSchema { Type object, Properties new Dictionarystring, OpenApiSchema { [errors] new OpenApiSchema { Type object, AdditionalPropertiesAllowed true, Example new OpenApiObject { [Email] new OpenApiArray(new OpenApiString(邮箱格式不正确)), [Password] new OpenApiArray(new OpenApiString(密码长度至少8位)) } } } } } } } } }); } }注意ErrorResponseFilter需在AddSwaggerGen后注册否则不生效。前端可据此生成TypeScript接口定义避免手动维护interface ApiResponseT。3.3 前端Axios拦截器为何要重试401——解决“用户Token过期后连续点击多个按钮每个都弹登录框”的体验灾难Token过期时后端返回401前端应自动用RefreshToken换新AccessToken成功后再重发原请求。本Demo提供可直接集成的拦截器// utils/api.js const api axios.create({ baseURL: https://api.example.com, withCredentials: true // 携带Cookie用于RefreshToken }); // 请求拦截器添加Authorization头 api.interceptors.request.use( config { const token localStorage.getItem(accessToken); if (token) { config.headers.Authorization Bearer ${token}; } return config; }, error Promise.reject(error) ); // 响应拦截器处理401并自动刷新Token let isRefreshing false; let failedQueue []; api.interceptors.response.use( response response, async error { const originalRequest error.config; if (error.response?.status 401 !originalRequest._retry) { if (isRefreshing) { // 等待刷新完成然后重发请求 return new Promise(resolve { failedQueue.push(() resolve(api(originalRequest))); }); } originalRequest._retry true; isRefreshing true; try { const refreshToken localStorage.getItem(refreshToken); const res await axios.post(/auth/refresh, { refreshToken }); localStorage.setItem(accessToken, res.data.accessToken); localStorage.setItem(refreshToken, res.data.refreshToken); // 重发原始请求 originalRequest.headers.Authorization Bearer ${res.data.accessToken}; return api(originalRequest); } catch (refreshError) { // 刷新失败清空Token并跳转登录页 localStorage.removeItem(accessToken); localStorage.removeItem(refreshToken); window.location.href /login; return Promise.reject(refreshError); } finally { isRefreshing false; failedQueue.forEach(callback callback()); failedQueue []; } } return Promise.reject(error); } );提示originalRequest._retry标记防止无限重试failedQueue解决并发请求时多个401同时触发刷新的问题确保只执行一次刷新操作。4. 避坑这五个地方踩过才懂——从JWT密钥硬编码到EF Core懒加载陷阱全是线上事故现场还原4.1 现象Swagger页面点“Try it out”返回401但Postman里加Header就能通原因Swagger UI在iframe中运行浏览器同源策略限制其读取localStorage中的Token导致请求无Authorization头解决在Program.cs中配置Swagger启用OAuth2隐式流Implicit Flow或直接在SwaggerUI中手动输入Token// Program.cs c.AddSecurityDefinition(Bearer, new OpenApiSecurityScheme { Name Authorization, Type SecuritySchemeType.ApiKey, Scheme bearer, BearerFormat JWT, In ParameterLocation.Header, Description JWT Authorization header using the Bearer scheme }); c.AddSecurityRequirement(new OpenApiSecurityRequirement { { new OpenApiSecurityScheme { Reference new OpenApiReference { Type ReferenceType.SecurityScheme, Id Bearer } }, new string[] { } } });注意Swagger UI 5.x以上版本需在index.html中引入oauth2-redirect.html否则OAuth登录按钮不显示。4.2 现象EF Core更新实体时抛出InvalidOperationException: The instance of entity type Order cannot be tracked原因使用Attach(entity)后直接修改属性EF Core认为这是新实体而非已存在实体导致INSERT而非UPDATE解决明确指定实体状态为Modified或使用UpdateRange批量更新// ❌ 错误写法Attach后直接赋值 _context.Orders.Attach(order); order.Status Shipped; await _context.SaveChangesAsync(); // 抛出异常 // ✅ 正确写法1Attach后设状态 _context.Orders.Attach(order); _context.Entry(order).State EntityState.Modified; await _context.SaveChangesAsync(); // ✅ 正确写法2用Find获取再修改推荐 var dbOrder await _context.Orders.FindAsync(order.Id); if (dbOrder ! null) { dbOrder.Status Shipped; await _context.SaveChangesAsync(); }4.3 现象前端传{ items: [] }后端CreateOrderRequest.Items为null而非空数组原因JSON反序列化时空数组[]默认映射为null除非显式配置JsonSerializerOptions.DefaultIgnoreCondition JsonIgnoreCondition.WhenWritingNull解决在Program.cs中配置JSON选项确保空集合反序列化为空数组// Program.cs builder.Services.ConfigureJsonOptions(options { options.SerializerOptions.DefaultIgnoreCondition JsonIgnoreCondition.WhenWritingNull; options.SerializerOptions.Converters.Add(new JsonStringEnumConverter()); // 关键设置空集合不为null options.SerializerOptions.PropertyNamingPolicy JsonNamingPolicy.CamelCase; });提示还需在CreateOrderRequest类中为Items属性添加[JsonProperty(DefaultValueHandling DefaultValueHandling.Include)]但更推荐统一配置JsonSerializerOptions。4.4 现象部署到Linux服务器后JWT签名验证失败始终返回401原因Windows下Encoding.UTF8.GetBytes(key)与Linux下字节序不同或密钥含不可见字符如BOM解决密钥必须为纯ASCII字符串且在appsettings.json中用Base64编码存储启动时解码// appsettings.json Jwt: { Key: QUJDREVGR0hJSktMTU5PUFFSU1RVVldYWVo // ABCDEFGHIJKLMNOPQRSTUVWXYZ的Base64 }// Program.cs var jwtKey Convert.FromBase64String(builder.Configuration[Jwt:Key]); var signingKey new SymmetricSecurityKey(jwtKey);4.5 现象Swagger文档中DateTime字段显示为2023-01-01T00:00:00前端解析为Invalid Date原因JavaScriptnew Date(2023-01-01T00:00:00)在部分浏览器中解析失败需ISO 8601完整格式解决配置JSON序列化强制输出毫秒和时区// Program.cs builder.Services.ConfigureJsonOptions(options { options.SerializerOptions.Converters.Add(new JsonStringEnumConverter()); options.SerializerOptions.DateTimeFormat DateTimeFormats.Iso8601; // 关键确保DateTime序列化包含毫秒和时区 options.SerializerOptions.Converters.Add(new JsonConverterDateTime { Write (writer, value, options) { writer.WriteStringValue(value.ToString(yyyy-MM-ddTHH:mm:ss.fffK)); } }); });5. 验证你的WebAPI是否真正“生产就绪”用Postman Collection跑通5个核心场景并导出TypeScript接口定义5.1 构建可执行的Postman测试集覆盖登录、刷新Token、创建订单、查询订单、异常流程本Demo附带WebAPIDemo.postman_collection.json导入Postman后可一键运行。重点验证以下5个场景场景请求URL预期响应验证要点1. 正常登录POST /auth/login200 OKAccessToken/RefreshToken检查AccessToken有效期为2小时RefreshToken存入数据库2. Token刷新POST /auth/refresh200 OK 新AccessToken用旧RefreshToken请求确认数据库中该Token状态变为Revoked3. 创建订单POST /orders200 OKOrderId检查Orders表新增记录Inventory表对应商品Stock减少Logs表有创建日志4. 400校验失败POST /orders传负金额400 Bad Requesterrors字段响应体含{code:400,message:Validation failed,data:{errors:{TotalAmount:[订单总金额不能为负]}}}5. 401自动重试GET /orders/1用过期Token200 OK重试后Postman控制台可见两次请求第一次401第二次200提示Postman中需在Tests标签页添加脚本自动提取AccessToken存入环境变量if (pm.response.code 200) { const jsonData pm.response.json(); pm.environment.set(accessToken, jsonData.accessToken); pm.environment.set(refreshToken, jsonData.refreshToken); }5.2 从Swagger JSON自动生成TypeScript接口告别手写interface User { id: number; name: string; }Swagger UI导出的swagger.json是OpenAPI 3.0规范可用openapi-typescript工具一键生成TS类型# 安装工具 npm install -g openapi-typescript # 生成TS文件假设Swagger JSON地址为 https://api.example.com/swagger/v1/swagger.json openapi-typescript https://api.example.com/swagger/v1/swagger.json --output src/api/generated.ts # 生成后可在组件中直接使用 import { UserResponseDto, CreateOrderRequest } from ../api/generated; const user: UserResponseDto { id: 1, fullName: 张三, email: zhangexample.com }; const order: CreateOrderRequest { userId: 1, items: [{ productId: 101, quantity: 2 }] };生成的generated.ts包含所有DTO类UserDto,OrderItem,ApiResponseTAPI函数authLogin,ordersCreate,ordersGetById返回PromiseAxiosResponseT枚举类型OrderStatusEnum,UserRoleEnum注意生成前需确保Swagger JSON中components.schemas完整本Demo已通过[ProducesResponseType]和[Produces]特性补全所有响应模型。5.3 真实压测用k6模拟100并发用户验证事务回滚和JWT性能光跑通不够得看高并发下是否丢数据。用k6脚本模拟100用户循环登录→创建订单→查询订单// test.k6.js import http from k6/http; import { check, sleep } from k6; export const options { vus: 100, // 虚拟用户数 duration: 30s, }; export default function () { // 1. 登录获取Token const loginRes http.post(https://api.example.com/auth/login, { username: testuser, password: Pssw0rd123 }); const token loginRes.json().accessToken; // 2. 创建订单 const orderRes http.post(https://api.example.com/orders, { userId: 1, items: [{ productId: 101, quantity: 1 }] }, { headers: { Authorization: Bearer ${token} } } ); // 3. 查询订单 const queryRes http.get(https://api.example.com/orders/${orderRes.json().id}, { headers: { Authorization: Bearer ${token} } } ); // 验证关键指标 check(loginRes, { login status: (r) r.status 200 }); check(orderRes, { order create status: (r) r.status 200 }); check(queryRes, { order query status: (r) r.status 200 }); sleep(1); // 每次循环间隔1秒 }运行命令k6 run test.k6.js关键观察点http_req_failed应为0无请求失败http_req_duration{p95}应200ms95%请求响应时间数据库Orders表记录数应等于vus × (duration / sleep)如100用户×30次3000条且Inventory.Stock准确扣减从那以后我每次交付WebAPI都强制走一遍这5个Postman场景1次k6压测。不是为了证明代码多完美而是确保当运维半夜打电话说“订单创建失败”我能立刻回答“先查RevokedTokens表有没有异常数据再看Logs表最近10分钟的ERROR日志”——而不是打开IDE盲猜。希望帮到你。本文还有配套的精品资源点击获取