简介面向需要快速掌握WebAPI开发的C#/.NET学习者这是一份可直接运行的实战Demo演示基于HTTP协议构建跨平台调用接口的完整流程。项目内含Movie模型及GetMovie等典型接口覆盖路由配置、参数绑定、JSON格式化、HTTP状态码处理等核心知识点便于理解WebAPI在移动端、网页端等异构客户端场景下的工作方式。压缩包共402个文件大小27.17MB以dll、xml、cs、cshtml、config等为主cs源码承载控制器与业务逻辑cshtml用于服务端页面展示config包含Web.config等环境配置nupkg/nuspec记录NuGet依赖配套sln/csproj工程文件可直接用Visual Studio打开运行。另有txt文本和png图片可辅助查阅说明与界面效果。目前已有3558人学习下载。借助该Demo能快速搭建自己的WebAPI项目并可从AtTheMovies示例中学习如何设计REST风格接口、组织项目结构作为入门参考或二次开发脚手架都很合适。1. 与其读十遍教程不如拆一个 C# WebApi Demo很多 C# 工程师第一次接触 WebApi 不是从文档开始的而是从同事丢过来的一个 Demo 项目开始的。打开解决方案看到 Controllers 文件夹里十几个类第一反应往往是接口地址在哪里定义为什么我按 F5 启动后访问一个路径就能看到 JSON这个疑问背后是 HTTP 协议、路由映射、模型绑定和依赖注入四套知识在同时运作。这里说的 WebApi Demo就是把这几套东西压缩到一个可运行项目里让你从“能跑”到“知道为什么能跑”。对刚入门 ASP.NET Core 的人来说这类实战项目能省去大量搜索时间对写过几年业务系统的熟手来说把路由约束、生命周期、统一返回格式这些细节重新过一遍也能在接手旧项目时少踩坑。接下来的内容会从建一个最小 Controller 开始逐步走到分页查询、Swagger 调试、IIS 发布最后给一个可以复用到 C# 上位机项目的 API 调用技巧。2. 搭建 C# WebApi 项目骨架从空模板跑到第一个接口在 .NET 8 中执行dotnet new webapi时会得到一个 Minimal API 项目它把路由和业务逻辑都写在Program.cs里对学习接口底层来说反而缺少分层。要还原经典的 Controller 形态需要显式加上--use-controllers参数。掌握这个创建方式后再看社区里那些带 Controllers、Models、Dtos 三件套的 WebApi Demo就不会被目录结构劝退。2.1 Program.cs、Startup 与 Controller 的分工打开一个典型的 Controller 版 WebApi 项目核心文件并不多。Program.cs负责两件事构建服务容器和组装 HTTP 请求管道Controller负责把 HTTP 动词映射到 C# 方法。在 .NET 6 之前这两件事被拆在Startup.ConfigureServices和Startup.Configure中现在都合并到了同一个Program.cs里。学习时只要在脑海中把builder.Services.AddControllers()这句话理解为“向容器注册接口控制器”把app.MapControllers()理解为“让路由系统开始扫描 Controller”整个项目就能顺着视线读通。2.2 用 dotnet CLI 创建与启动项目以 .NET 8 环境为例打开终端执行下面四条命令dotnet --version dotnet new webapi --use-controllers -n EasyDemo.Api cd EasyDemo.Api dotnet run--use-controllers是这里的关键参数它让模板生成 Controllers 目录而非 Minimal API 的裸Program.cs。项目运行后默认监听https://localhost:5001和http://localhost:5000控制台会打印 Swagger 和 API 地址。如果你习惯 Visual Studio新建项目时选择“ASP.NET Core Web API”并在创建向导里勾选“使用控制器”效果相同。2.3 第一个 GET 接口状态码与 async/await直接用模板自带的 WeatherForecast 也能跑但为了后续扩展这里写一个简单的 Todo 接口体会ActionResultT如何同时表达数据和状态码using Microsoft.AspNetCore.Mvc; namespace EasyDemo.Api.Controllers; [ApiController] [Route(api/[controller])] public class TodoController : ControllerBase { private static readonly ListTodoItem Items []; private static int _nextId 1; [HttpGet] public async TaskActionResultIEnumerableTodoItem GetAll() { await Task.Delay(10); // 模拟异步 IO生产环境请替换为 EF Core 的 ToListAsync return Ok(Items); } [HttpGet({id:int})] public async TaskActionResultTodoItem GetById(int id) { await Task.Delay(10); var item Items.FirstOrDefault(x x.Id id); if (item null) { return NotFound(); } return Ok(item); } }这段代码里有三个值得关注的点。第一[ApiController]会自动启动模型验证当id无法解析成 int 时框架直接返回 400 而不是进入方法体。第二ActionResultT允许Ok(item)返回 200也可以用NotFound()返回 404调用端只需要看到 HTTP 状态码和 JSON 响应方法签名不暴露具体类型时 Swagger 也能正确推断。第三async Task在 WebApi 中不是装饰await Task.Delay出让了当前线程高并发场景下能明显减少线程池压力。TodoItem可以是一个简单的记录类型public record TodoItem(int Id, string Name, bool IsDone);放在 Models 文件夹即可。下表是 HTTP 动词与 C# 特性、常见用途的对应关系写接口前先对着这张表选动词比临场记[HttpGet]少很多返工HTTP 方法C# 特性常见用途GET[HttpGet]查询单个或列表POST[HttpPost]新增资源PUT[HttpPut]整体更新PATCH[HttpPatch]部分更新DELETE[HttpDelete]删除资源3. 路由与模型绑定请求怎么变成方法参数很多 WebApi 初学者的困惑是明明没有看到任何 URL 字符串为什么访问/api/Todo/3就会进入GetById(int id)答案是路由和模型绑定在背后做了两件事路由决定“这个地址交给哪个方法”模型绑定决定“URL 里的值怎么填进参数”。这两个机制分开理解写接口才能不靠猜。3.1 属性路由把地址和动作写在一起Controller 版 WebApi 支持约定路由和属性路由约定路由在Program.cs里用MapControllerRoute定义了{controller}/{action}/{id?}的通用模式属性路由则直接在控制器或动作上写完整地址。两者共存时以属性路由优先实际项目里我一般只在集成测试或老系统中保留约定路由新接口全部用属性路由。[Route(api/[controller])]中的[controller]是控制器名的占位符TodoController会被替换成Todo所以类名改动后路由自动跟着变。推荐在控制器上写固定名字比如[Route(api/todo)]这样前端和 WinForms 测试端不会因为类名重构而悄悄失效。3.2 五种绑定来源Query、Route、Header、Body、Form模型绑定按参数的来源可以分成五种显式标注后代码的可读性和稳定性都会提升绑定来源写法典型场景URL 路径[FromRoute] int idRESTful 主键查询字符串[FromQuery] int pageIndex分页、筛选请求头[FromHeader] string tokenToken、版本号JSON 请求体[FromBody] CreateTodoRequest reqPOST/PUT 载荷表单[FromForm] IFormFile file文件上传如果你拿不准什么时候写[FromQuery]、什么时候写[FromBody]记住这条规则简单类型int、string、bool默认从 Query 或 Route 绑定复杂类型默认从 Body 绑定。也就是说int pageIndex不写特性也能拿到 query 参数但自定义类EmployeeQuery query不写[FromQuery]时会被当作 JSON Body 来解析接口看似正常却取不到值。另外一个动作里最多只能有一个[FromBody]参数这是 JSON 请求体的天然限制。3.3 实例一个带分页和关键词过滤的员工接口下面这个动作集中演示了 Query、Route 和默认参数的配合。假设控制器叫EmployeeController路由前缀是api/employee[HttpGet(page)] public async TaskActionResultPagedResultEmployee GetPage( [FromQuery] int pageIndex 1, [FromQuery] int pageSize 20, [FromQuery] string? keyword null) { await Task.Delay(5); // 当前仅作演示真实环境用异步仓储方法 var query EmployeeDb.AsQueryable(); if (!string.IsNullOrWhiteSpace(keyword)) { query query.Where(e e.Name.Contains(keyword) || e.Department.Contains(keyword)); } var total query.Count(); var data query .OrderBy(e e.Id) .Skip((pageIndex - 1) * pageSize) .Take(pageSize) .ToList(); return Ok(new PagedResultEmployee { Total total, PageIndex pageIndex, PageSize pageSize, Items data }); }这里[FromQuery]让三个参数都从查询字符串读取URL 调用的样子是/api/employee/page?pageIndex2pageSize10keyword张。给pageIndex和pageSize默认值是为了避免调用方漏传参数时直接得到 400keyword可空则让筛选条件缺失时走全量查询。Skip((pageIndex - 1) * pageSize)是分页计算的标准写法第一页从 0 开始跳pageIndex 小于 1 时只会查出空集而不是报错具体项目可以在前端先把 pageIndex 校验成大于等于 1。PagedResultEmployee是一个简单的包装类定义成Total/PageIndex/PageSize/Items四个属性即可。它比直接返回裸ListEmployee多给了前端总条数分页控件才知道总共该渲染多少页。4. 依赖注入与 EF Core给 Demo 一个真实数据流前面的接口都在内存列表上工作纯粹为了演示路由和绑定。实战项目不可能这样写数据要从数据库来查询要能被事务管理连接要能释放而这一切都靠 ASP.NET Core 的依赖注入容器串联起来。这一章的目标是把 Demo 升级成三层结构Controller 调仓储仓储操作 DbContextDbContext 由容器注入。4.1 为什么接口里不该到处 new最简单的反面写法是在 Controller 的方法里var repo new EmployeeRepository()。初看没问题但每请求创建一个新仓储仓储内部的 DbContext 也会重复创建。DbContext 是工作单元模式的核心对象每次请求只应该有一个实例来追踪实体状态重复创建会让两个上下文各自缓存一份数据后续更新时出现“另一个实例正在跟踪实体”的异常。构造函数注入的写法是构造参数里直接写需要的服务类型容器负责把实例传进来。Controller 的构造函数只声明依赖不负责真正创建对象这样单元测试时可以注入一个假的仓储不用连接真实数据库。4.2 注册 DbContext 与仓储服务先给项目添加 EF Core SQL Server 包dotnet add package Microsoft.EntityFrameworkCore.SqlServer然后在appsettings.json中放入连接字符串{ ConnectionStrings: { Default: Server.;DatabaseEasyDemoDb;Trusted_ConnectionTrue;TrustServerCertificateTrue; } }Server.表示本机 SQL Server 默认实例TrustServerCertificateTrue是在本地开发时跳过证书校验生产环境请换回受信任的证书。最后在Program.cs中注册服务builder.Services.AddDbContextAppDbContext(options options.UseSqlServer(builder.Configuration.GetConnectionString(Default))); builder.Services.AddScopedIEmployeeRepository, EmployeeRepository();AddDbContext默认把 DbContext 注册为 Scoped和请求生命周期对齐AddScoped让每次 HTTP 请求共享同一个仓储实例。这样同一请求里无论 Controller 还是某个服务拿到的都是同一个EmployeeRepository和同一个AppDbContext事务一致性才有保证。仓储实现类本身不做任何服务端渲染只暴露查询和数据变更方法public class EmployeeRepository : IEmployeeRepository { private readonly AppDbContext _db; public EmployeeRepository(AppDbContext db) { _db db; } public async TaskPagedResultEmployee GetPageAsync(int pageIndex, int pageSize, string? keyword) { var query _db.Employees.AsNoTracking(); if (!string.IsNullOrWhiteSpace(keyword)) { query query.Where(e e.Name.Contains(keyword) || e.Department.Contains(keyword)); } var total await query.CountAsync(); var items await query .OrderBy(e e.Id) .Skip((pageIndex - 1) * pageSize) .Take(pageSize) .ToListAsync(); return new PagedResultEmployee { Total total, Items items }; } }这里的AsNoTracking()对只读查询很关键它告诉 EF Core 不需要跟踪实体状态查询速度更快内存占用也更小。Controller 侧只需要一行var repo _employeeRepo.GetPageAsync(...)业务代码不会出现 SQL。4.3 生命周期选型与 HttpClient 的“伪单例”陷阱注册服务时最常犯的错误是把所有服务都注册成 Singleton。生命周期选型没有一个万能表但可以按下面的默认值起步生命周期创建时机推荐场景AddTransient每次解析都创建轻量无状态的工具类AddScoped每个 HTTP 请求内共享DbContext、仓储、业务服务AddSingleton进程内全局唯一配置读取、内存缓存、日志提供器AddSingleton看起来很诱人但碰上 DbContext 会立即炸掉DbContext 不是线程安全的多个请求并发共享一个实例时EF Core 会抛出各种奇怪的并发异常。同类问题还出现在手动写的HttpClient静态单例上。如果 Demo 需要调用第三方 API正确做法是用IHttpClientFactorybuilder.Services.AddHttpClient(pay, client { client.BaseAddress new Uri(https://api.example.com/); client.Timeout TimeSpan.FromSeconds(10); });AddHttpClient会为每个请求生成新的HttpMessageHandler并自动处理底层连接的复用和回收。而直接在类里写static readonly HttpClient _http new()表面上是单例实际上每次修改 BaseAddress 或调用GetAsync都会让连接池出现问题高并发下会看到 Socket 端口耗尽。判断依赖注入选型是否正确最简单的方法是看这个服务有没有状态有数据库上下文依赖通常选 Scoped无状态且不持有外部资源再考虑 Singleton。5. 测试、日志与发布把一个 Demo 工程变成可上线接口接口写完不经过工具验证就部署遇到问题只能盲猜。C# WebApi 的常规做法是先用 Swagger 做交互测试再用日志确认执行过程最后发布成文件夹并在 IIS 或进程托管下运行。熟练这套流程后任何 WebApi Demo 都能在两分钟内变成可演示、可交付的接口服务。5.1 用 Swagger 生成可点击的接口文档Controller 版 WebApi 项目里集成 Swagger 只需要两步第一步注册服务builder.Services.AddEndpointsApiExplorer(); builder.Services.AddSwaggerGen(options { options.SwaggerDoc(v1, new OpenApiInfo { Title EasyDemo.Api, Version v1 }); });第二步在管道中启用中间件建议只在开发环境开启if (app.Environment.IsDevelopment()) { app.UseSwagger(); app.UseSwaggerUI(); }运行时访问/swagger就能看到所有控制器动作的列表。Swagger 不只是文档生成器它实际调用的是接口路由点一下Try it out直接发送 HTTP 请求返回值、状态码、响应时间都会可视化展示。学习 WebApi 时遇到“接口通了但返回值不对”的情况先看 Swagger 页面比反复用 Postman 手拼参数快得多。5.2 日志从 ILogger 到结构化字段在 Controller 里注入ILoggerT然后用_logger.LogInformation记录业务关键路径[HttpGet] public async TaskActionResultIEnumerableTodoItem GetAll() { _logger.LogInformation(开始查询 Todo 列表当前数量{Count}, Items.Count); var data await _todoService.GetAllAsync(); return Ok(data); }LogInformation的{Count}是结构化日志占位符不是字符串拼接。JSON 日志会把这个字段提取成独立的Count属性日志系统可以按字段过滤如果用$当前数量{Items.Count}日志平台无法直接对该字段做查询和告警。业务日志的级别建议在appsettings.json的Logging:LogLevel节点调整生产环境把 Microsoft 前缀的日志调到 Warning只保留自己命名空间下的 Information避免刷屏。5.3 发布 WebApi 项目文件夹模式与 IIS 托管在项目根目录执行dotnet publish -c Release -o ./publish这条命令把编译后的 DLL、wwwroot 静态文件、web.config 一起输出到publish文件夹。如果目标机器装了 .NET Runtime直接dotnet EasyDemo.Api.dll就能启动如果部署到 IIS需要先安装 .NET Core Hosting Bundle并在 IIS 中新建站点物理路径指向 publish 文件夹应用程序池设置为“无托管代码”。提示发布产物里的 web.config 会包含AspNetCoreModuleV2配置这是 IIS 反向代理到 Kestrel 的桥接模块。IIS 500.30 错误多发生在后端运行时版本与部署机器 Hosting Bundle 不一致先检查dotnet --list-runtimes。5.4 用 WinForms 写一个最小接口测试客户端WinForms 里测试 WebApi 是 C# 上位机研发的常规操作只需要一个按钮和一个 DataGridViewprivate async void btnLoad_Click(object sender, EventArgs e) { using var http new HttpClient(); http.BaseAddress new Uri(http://localhost:5000); http.Timeout TimeSpan.FromSeconds(10); var json await http.GetStringAsync(/api/employee/page?pageIndex1pageSize10); var page JsonSerializer.DeserializePagedResultEmployee(json, new JsonSerializerOptions { PropertyNameCaseInsensitive true }); dataGridView1.DataSource page?.Items; }这段代码里有两个细节。PropertyNameCaseInsensitive true解决了后端返回 camelCase、客户端反序列化默认大小写不匹配的问题async void仅用于 WinForms 事件处理器普通方法请改成async Task否则异常会直接抛到 UI 线程。测试时如果接口还没发布启动 Visual Studio 的调试模式后监听地址总是localhost:5000之类的随机端口把 BaseAddress 改成对应端口即可。WinForms 客户端不像浏览器有同源策略不受跨域限制但如果是 Web 前端页面调用不同端口的 WebApi还需要在服务端配置 CORS。6. 再进一步用 ApiResult 和泛型方法统一 Demo 的接口调用前面所有接口的返回值要么是裸ListT要么是分页对象调用方只能从 HTTP 状态码判断成败。真实项目里业务失败与 HTTP 错误经常同时存在比如“用户不存在”是业务失败但 HTTP 200此时需要一个包含Success/Code/Message/Data的统一返回结构把业务状态放在消息体里而不是让调用方通过字符串解析来判断。这个技巧同时适用于服务端和 WinForms 或上位机客户端是提升 Demo 工程质量最快的一步。6.1 服务端定义一个通用的 ApiResultpublic class ApiResultT { public bool Success { get; set; } public int Code { get; set; } public string Message { get; set; } ; public T? Data { get; set; } }在动作方法里不再直接返回Ok(data)而是包一层[HttpGet] public async TaskActionResultApiResultListTodoItem GetAll() { var data await _todoService.GetAllAsync(); return Ok(ApiResultListTodoItem.Ok(data)); }Ok(data)是一个静态工厂方法把Success置为true、Code置为0调用方看到Code 0就可以放心使用Data。如果业务出现异常再通过Fail方法给出非零错误码前端直接读取Message弹窗提示不需要解析 HTTP 状态码。6.2 客户端用一个泛型方法吞掉反序列化服务端统一返回格式后客户端不需要每次手动Deserialize把公共逻辑收进一个 HttpClient 扩展方法public static class HttpClientExtensions { private static readonly JsonSerializerOptions JsonOpts new(JsonSerializerDefaults.Web); public static async TaskApiResultT GetApiResultAsyncT( this HttpClient client, string url, CancellationToken ct default) { using var resp await client.GetAsync(url, ct); var json await resp.Content.ReadAsStringAsync(ct); var result JsonSerializer.DeserializeApiResultT(json, JsonOpts); if (!resp.IsSuccessStatusCode) { return new ApiResultT { Success false, Code (int)resp.StatusCode, Message result?.Message ?? resp.ReasonPhrase ?? HTTP error }; } return result!; } }JsonSerializerDefaults.Web已经内置了 camelCase 反序列化和大小写不敏感省去手动设置PropertyNameCaseInsensitive。判断 HTTP 状态码后再返回错误信息是为了把 500、404 这类传输层错误也归纳成业务结构调用方只面对一个ApiResultT。调用时一行就能拿到强类型数据var page await http.GetApiResultAsyncPagedResultEmployee( /api/employee/page?pageIndex1pageSize10); if (page.Success) { dataGridView1.DataSource page.Data?.Items; } else { MessageBox.Show(page.Message); }配合统一返回格式这个扩展方法还可以继续加BearerToken 注入、超时重试和请求日志而接口调用代码始终只有一行Demo 里所有客户端页面都会复用这套底层逻辑。本文还有配套的精品资源点击获取