在一台干净的 Windows 11 机器上装好 .NET SDK,写下第一个服务端程序,最想看到的东西其实很朴素:浏览器或者 curl 能返回一段 JSON。但这一步经常卡住,而且卡住的原因多半不是代码写错,而是环境里的某层东西把你覆盖了。我当时设了 ASPNETCORE_URLS=127.0.0.1:18082,满心以为服务会监听这个端口,结果 dotnet run 打印的是 Now listening on: http://localhost:5050,环境变量像是没生效。
这篇从空目录开始,把「一个能返回 JSON 的服务」完整走一遍,顺便把三层容易混淆的东西拆开:SDK、运行时、ASP.NET Core 框架各自负责什么;Kestrel 是什么、什么时候需要在它前面加反向代理;dotnet run 和 dotnet publish 出来的东西有什么不同。所有命令和输出都来自本机 .NET SDK 8.0.427、目标框架 net8.0 的实测,没有跑过的部分会明确标出来。
这篇只讲「怎么搭」,不讲 C# 语法。类型、委托、模式匹配这些内容在 C# 语法与类型 里,读完那边再回来,看代码会更顺。
先把它跑起来:五条命令和一个端点
先确认工具链在。打开 PowerShell,输入版本查询:
dotnet --version
8.0.427
只要能打印出版本号,SDK 就装好了。接着在一个空目录里建项目。dotnet new web 是内置模板,生成的项目只有一个 Program.cs 和几个配置文件,没有 MVC 那套目录,这正是 minimal API(最小 API,直接把路由写在 Program.cs 里的写法)的起点:
dotnet new web -o csharpdemo --no-https
还原 535 毫秒
dotnet build
Build succeeded.
0 Warning(s)
0 Error(s)
Time Elapsed 00:00:33.12
还原只花了 535 毫秒,因为模板没有第三方包;构建用了 33.12 秒,第一次构建要编译框架引用和生成中间文件,慢是正常的。
模板生成的 csproj 只有一行关键配置,目标框架是 net8.0:
<Project Sdk="Microsoft.NET.Sdk.Web">
<PropertyGroup>
<TargetFramework>net8.0</TargetFramework>
</PropertyGroup>
</Project>
目录里只有三个东西,没有分层,也没有多余文件:
把模板生成的 Program.cs 换成下面这份,就是一个能增能查的 JSON 服务。--no-https 省掉了开发证书的麻烦,本地调试用明文 HTTP 就够了:
using System.Collections.Concurrent;
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
var items = new ConcurrentDictionary<long, string>();
long nextId = 0;
app.MapGet("/health", () => Results.Json(new { status = "ok" }));
app.MapPost("/api/items", (ItemInput input) =>
{
var id = Interlocked.Increment(ref nextId);
items[id] = input.Name;
return Results.Json(new { id, name = input.Name }, statusCode: 201);
});
app.MapGet("/api/items/{id:long}", (long id) =>
items.TryGetValue(id, out var name)
? Results.Json(new { id, name })
: Results.Json(new { error = "not found" }, statusCode: 404));
app.Run();
record ItemInput(string Name);
启动时不要直接 dotnet run,因为项目里的 launchSettings.json 会把端口改回它自己的设置。用 --no-launch-profile 告诉它不要读那份调试配置,再用 --urls 指定监听地址:
dotnet run --no-launch-profile --urls "http://127.0.0.1:18082"
终端会先打印几行日志,然后停在那里不返回,这是正常现象,说明进程正在前台跑着:
info: Microsoft.Hosting.Lifetime[14]
Now listening on: http://127.0.0.1:18082
info: Microsoft.Hosting.Lifetime[0]
Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
Hosting environment: Development
另开一个终端,用 curl 打健康检查端点。Windows 自带的是 curl.exe,注意在 PowerShell 里写 curl 会被解析成 Invoke-WebRequest 的别名,行为不一样,所以命令里显式写 curl.exe:
curl.exe -s -i 127.0.0.1:18082/health
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Server: Kestrel
Transfer-Encoding: chunked
{"status":"ok"}
三个响应头值得留意。Server: Kestrel 说明请求是被 Kestrel 直接接住的,中间没有 IIS 或 nginx;Content-Type: application/json; charset=utf-8 是 Results.Json 自动设置的;Transfer-Encoding: chunked 表示响应没有固定长度,是边算边发的。
再验证写入和查询。POST 一条数据,返回的状态码是 201,表示「创建成功」,响应体带上了服务端分配的 id:
curl.exe -s -i -X POST 127.0.0.1:18082/api/items -H "Content-Type: application/json" -d "{\"name\":\"widget\"}"
HTTP/1.1 201 Created
{"id":1,"name":"widget"}
curl.exe -s 127.0.0.1:18082/api/items/1
{"id":1,"name":"widget"}
curl.exe -s -i 127.0.0.1:18082/api/items/99
HTTP/1.1 404 Not Found
{"error":"not found"}
三个接口合起来不到四十行,没有 Controller,没有服务层,甚至连依赖注入的注册都只有 CreateBuilder 自带的那一份。这就是现在很多人拿 minimal API 直接写生产接口的原因:样板代码少到几乎只剩业务本身。但它也有代价,后面会讲。
SDK、运行时、框架、Kestrel 各管什么
端口被抢走这类问题,根子在于没分清这几层。它们安装在同一台机器上,出事时的表现却完全不同,按从上到下的顺序拆开看:
「dotnet 不在 PATH」是新手最常见的第一个坑:机器上可能只装了 ASP.NET Core Runtime,因为它能被某些安装器顺带装上,但 dotnet new 需要 SDK。dotnet --list-sdks 输出为空就说明只有运行时没有 SDK;这时不要怀疑代码,去补装 SDK 就行。SDK 装在 C:\Program Files\dotnet,如果 PATH 里没有这个目录,任何终端都会提示「无法将 dotnet 项识别为 cmdlet」,重启终端通常能解决,因为安装器改的是系统环境变量。
请求进入进程之后,走的是一条固定的管道,Kestrel 在最外面,你写的每个中间件和端点依次排队:
顺序很重要,第 2 篇会专门讲。这里只先建立一个直觉:越靠前的中间件越早看到请求、越晚拿到响应,像洋葱一样一层层包住端点。日志、异常处理、认证都依赖这个顺序。
启动日志里的 Microsoft.Hosting.Lifetime[14] 是日志分类加事件编号,不是错误码。分类告诉你这条日志由谁发出,编号是框架内部的事件 id。看懂这个格式,排查时就能快速判断一条日志来自框架还是来自你自己的代码。
那 Kestrel 直接对外行不行?行,但有条件。它是通用 HTTP 服务器,性能很好,单机几万并发连接不是问题。真正缺的是运维能力:TLS 证书自动续期、按 IP 限流、拦住超大请求体、处理慢连接攻击、静态文件缓存、多实例的会话粘滞。规模小的时候这些都不重要。经验上的分界是:内网服务、单实例、日请求量在几十万以内,Kestrel 加一层系统防火墙就够了;一旦对公网开放、要多实例部署、或者需要 WAF 和灰度,前面就该有一个 nginx 或网关。在反向代理后面时,Kestrel 只监听 127.0.0.1,公网端口由代理接,这一点第 6 篇会展开。
这里还有一个常见误解:Kestrel 不是 IIS 的替代品,也不是「只能开发用」。它本来就是跨平台的正式服务器,IIS 在 Windows 上只是作为前置的反向代理和进程管理器存在。搞清楚谁在前面,日志里出现的是谁的报错,才不会把代理层的 502 当成应用挂了。
Minimal API 还是 Controller:不是新旧之争
很多人把 minimal API 当成「新写法」,把 Controller 当成「老写法」,这是误解。两者在同一个框架里、跑在同一条管道上,区别只是代码的组织方式和元数据的声明方式。
minimal API 能在生产里当主力,靠的不是「代码短」,而是三件事在近几个版本里补齐了:路由约束和参数绑定足够用,依赖注入能直接写在处理函数的参数上,返回值统一成了结果对象。以前写一个小接口要新建三个文件,现在一行就能说清楚「路径、输入、输出」,所以它天然适合边界清晰的小服务,比如给内部系统提供几个查询接口。
Minimal API
路由、参数绑定、返回类型全写在 Program.cs,一个 MapGet 就是一条完整接口。启动快、样板少、读起来像脚本。适合端点少于三十个、团队一两个人、迭代频繁的小服务,也适合给已有系统加一层薄薄的 API 网关。
Controller
一个类管一组路由,靠方法和特性(attribute,写在声明上方的方括号标记)声明行为。模型绑定、过滤器、分组、API 文档的可发现性都更成熟。适合端点超过五十个、团队四个人以上、需要统一的鉴权过滤器和参数校验规则的项目。
关键的分界不是端点数量,而是「有没有统一横切逻辑」。如果每个接口都要做同样的权限判断、同样的入参校验、同样的审计日志,Controller 的 action filter 能一次挂上去;minimal API 也有 endpoint filter,但它是逐组挂的,组织不好就会重复。另一个现实因素是找人接手:新人打开项目,Controller 的目录结构一眼能看出有哪些资源,而一个三千行的 Program.cs 需要慢慢翻。
团队协作时 Controller 还有一个隐性优势:可发现性。新人接到需求「改一下订单取消」,在 Controller 目录里按资源名找,几分钟就能定位;在 minimal API 项目里,得先全局搜索路由字符串。这个差别在三个人以下时几乎感觉不到,人数一多,沟通成本会迅速放大。所以「我们团队小,用 minimal API 就行」这句话,要连带估算未来一年的团队规模,而不是只看今天。
反过来,什么时候必须用 Controller?当项目已经有一套 MVC 基础设施,比如视图、模型绑定约定、Swagger 分组、全局异常过滤器时,硬换成 minimal API 只会让两套东西并存。还有需要复杂模型绑定(嵌套对象、集合、文件加表单混合)的场景,Controller 的绑定器更省事。规模数字只是参考,真正的判断标准是「团队能不能在一分钟内找到某个接口的代码」。
照着这张表查,别猜
起步阶段九成的失败都能归到下面几类。表格里的「第一步查什么」是排查动作,不是结论,先看到事实再改代码:
| 现象 | 真实原因 | 第一步查什么 |
|---|---|---|
| 设了 ASPNETCORE_URLS,启动日志仍是 localhost:5050 | launchSettings.json 的 applicationUrl 优先级更高,dotnet run 默认读它 | 打开 Properties/launchSettings.json,看 applicationUrl 那一行 |
| 提示 dotnet 不是内部或外部命令 | 只装了运行时,或 SDK 目录没进 PATH | 执行 dotnet --list-sdks,输出为空就是没装 SDK |
| 浏览器显示一大段异常堆栈 | 当前是 Development 环境,详细错误页被打开 | 看启动日志里的 Hosting environment 一行 |
| 启动报端口已被占用 | 上一次的进程没退干净,或别的程序占着同一端口 | netstat -ano 加端口号,找到 PID 再确认进程 |
| 改了代码,接口行为没变 | 旧进程还在跑,新进程因端口冲突根本没起来 | 看启动日志时间戳,确认是不是新的一次启动 |
| curl 连不上,浏览器却正常 | 服务只监听了 127.0.0.1,或者解析到了 IPv6 的地址 | 把地址明确写成 127.0.0.1,再用 curl.exe 试 |
| 返回的 JSON 字段名全是小写开头 | System.Text.Json 默认用 camelCase 命名策略 | 对照 C# 属性名和响应体,确认是命名策略而非数据丢失 |
| 第一次构建慢到几十秒 | 首次还原和生成中间文件,不是代码有问题 | 第二次构建的耗时,正常会明显下降 |
表里最容易误判的是端口那条。很多人第一反应是「环境变量没生效」,于是反复改环境变量,其实 launchSettings.json 只是调试用的配置,优先级排在环境变量前面。dotnet run --no-launch-profile 才是把这份配置摘掉的正规做法。另一条容易误判的是「改了代码没生效」,本质是进程没重启,而进程没重启的原因又常常是端口被旧进程占着,两个现象其实是一个链条。
另外要区分「环境变量没生效」和「环境变量被覆盖」。前者是根本没读到,后者是读到了但优先级更低。ASP.NET Core 的配置源是有顺序的:命令行最高,其次环境变量,再次 appsettings.环境.json,最后 appsettings.json。launchSettings.json 不在这个序列里,它只在 dotnet run 时注入环境变量和参数,所以它的效果看起来像「比环境变量还高」。第 6 篇会把完整顺序列出来。
边界与代价:什么时候这套东西不够用
minimal API 最大的代价是「没有结构」。端点少的时候这是优点,端点一多,Program.cs 会变成一张巨大的路由清单,参数校验、错误处理、权限判断散落在每个 lambda 里。等到有五十个端点、每十个端点就要复制一次同样的错误处理时,重构的成本已经比一开始用 Controller 高。规模上的经验值:端点超过三十个、或者 Program.cs 超过三百行,就该开始用 MapGroup 按资源分组;再往上,直接换 Controller 更划算。
第二个代价是调试体验。开发态默认打开详细错误页,好处是能直接看到异常堆栈和源码位置,坏处是它会把内部路径、连接字符串、SQL 片段全部暴露给调用方。上线前必须把环境切换到 Production,这个动作不做,等于把服务器内部结构挂在公网上。日志里的 Hosting environment: Development 就是提醒你还没切。
第三个代价藏在发布方式里。dotnet run 是开发态命令,它会先编译、再启动,进程挂在前台,关掉终端服务就停;它依赖本机的 SDK 和源码目录。真正上线要用 dotnet publish -c Release 生成一套可以拷走的产物,再在目标机器上用运行时执行。两者跑的是同一份代码,但运行环境、依赖解析、优化级别都不同。所以「本机能跑」不能推出「服务器能跑」,这条在第 6 篇会具体讲。
发布产物还分两种模式。框架依赖模式只打包你的代码,目标机器必须装对应版本的运行时,产物小、升级运行时统一;自包含模式把运行时一起打进去,目标机器什么都不用装,但产物大得多,每个版本都要重新打包。选哪种取决于目标机器归谁管:自家服务器能统一装运行时,就用前者;交付给客户、环境不可控,就用后者。发布产物的具体体积本机没有实测,这里不给数字,你在自己的项目上跑一次 publish 就能看到。
ASPNETCORE_ENVIRONMENT 留在 Development 就上线,异常堆栈会被外部看到,这属于信息泄露,不是「方便排查」。切换环境变量的效果,第 6 篇有完整验证。还有一层容易被忽略的成本:内存里的数据不是数据。上面那份示例用 ConcurrentDictionary 存条目,进程一重启就清零,多开一个实例就各存各的。它适合演示接口形状,不适合任何需要留下来的业务数据。什么时候必须换成数据库?只要这条数据在重启后还要在、或者两个实例要看到同一份,就必须落库。第 3 篇会把这份示例换成 EF Core 加 SQLite,接口返回保持完全一致。
今天就能自验的五个练习
下面每条都能在半小时内做完,做完你对这套东西的理解会比读十篇教程实在:
- 在一个全新的空目录执行
dotnet new web -o demo1 --no-https,然后直接dotnet run,记下它打印的端口;再用--no-launch-profile --urls指定 18082 启动,对比两次的日志差异。这一步的目的是亲眼看到 launchSettings 的优先级。 - 把
/health改成返回{"status":"ok","env":"dev"},用curl.exe -s -i确认响应头里的 Content-Type 和 Server 两个字段,理解「谁设置的」。 - 故意把两个实例同时启动在同一端口,观察第二个进程的报错文本,再用 netstat 找到占用端口的 PID。这条练的是排查顺序,不是记命令。
- 加一个
MapPost("/api/echo", ...),把请求体原样返回,用 curl 发中文内容,观察 JSON 里的中文是否被转义。这能让你提前知道序列化器的默认行为。 - 把环境变量设成 Production 再启动,访问一个不存在的路由,对比错误页的变化。注意这一步只改环境变量,不改任何代码。
小结
下一篇讲路由和请求管道。上面那个「洋葱」只是直觉,真正决定请求走哪条路、哪个中间件先执行、认证为什么有时不生效的,是 UseRouting、UseAuthentication、UseAuthorization 和端点注册的相对位置。第 1 篇里所有端点都是匿名可访问的,一旦加上鉴权,顺序错一步就会出现「明明登录了还是 401」。
这篇的三句话总结:第一,SDK、运行时、框架、Kestrel 是四层不同的东西,报错时要先判断问题在哪一层,别一上来改代码;第二,minimal API 和 Controller 是组织方式之争,端点少于三十个、团队一两个人时前者更省事,超过这个规模就该考虑后者;第三,dotnet run 只是开发态,端口会被 launchSettings 抢走,上线要用 publish 产物并把环境切到 Production。