在一台干净的 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唯一的入口,启动代码和路由都写在这里
Properties/launchSettings.json本地调试用的端口和环境名,发布时不会被带走
csharpdemo.csproj项目定义,声明目标框架和依赖

把模板生成的 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 各管什么

端口被抢走这类问题,根子在于没分清这几层。它们安装在同一台机器上,出事时的表现却完全不同,按从上到下的顺序拆开看:

SDK开发工具链,提供 dotnet new、dotnet build、dotnet run、dotnet publish 这些命令。只有开发机需要,服务器上不需要装。
运行时真正执行程序的引擎,分 Microsoft.NETCore.App 和 Microsoft.AspNetCore.App 两套。服务器上只需要它,装了程序才能跑。
ASP.NET Core 框架提供 WebApplication、路由、中间件、依赖注入这些类库。它跟着运行时一起装,版本号要和编译时用的对得上。
Kestrel框架内置的 HTTP 服务器,负责监听端口、解析 HTTP 报文、把请求交给你写的管道。它不负责 TLS 证书管理之外的那些「运维级」能力。

「dotnet 不在 PATH」是新手最常见的第一个坑:机器上可能只装了 ASP.NET Core Runtime,因为它能被某些安装器顺带装上,但 dotnet new 需要 SDK。dotnet --list-sdks 输出为空就说明只有运行时没有 SDK;这时不要怀疑代码,去补装 SDK 就行。SDK 装在 C:\Program Files\dotnet,如果 PATH 里没有这个目录,任何终端都会提示「无法将 dotnet 项识别为 cmdlet」,重启终端通常能解决,因为安装器改的是系统环境变量。

请求进入进程之后,走的是一条固定的管道,Kestrel 在最外面,你写的每个中间件和端点依次排队:

一个请求在进程里的路线
Kestrel监听端口,解析报文,生成 HttpContext
中间件按注册顺序执行,可短路、可改写请求和响应
端点路由匹配到的处理函数,返回结果对象
序列化把结果对象写成 JSON,交回 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:5050launchSettings.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,接口返回保持完全一致。

今天就能自验的五个练习

下面每条都能在半小时内做完,做完你对这套东西的理解会比读十篇教程实在:

  1. 在一个全新的空目录执行 dotnet new web -o demo1 --no-https,然后直接 dotnet run,记下它打印的端口;再用 --no-launch-profile --urls 指定 18082 启动,对比两次的日志差异。这一步的目的是亲眼看到 launchSettings 的优先级。
  2. 把 /health 改成返回 {"status":"ok","env":"dev"},用 curl.exe -s -i 确认响应头里的 Content-Type 和 Server 两个字段,理解「谁设置的」。
  3. 故意把两个实例同时启动在同一端口,观察第二个进程的报错文本,再用 netstat 找到占用端口的 PID。这条练的是排查顺序,不是记命令。
  4. 加一个 MapPost("/api/echo", ...),把请求体原样返回,用 curl 发中文内容,观察 JSON 里的中文是否被转义。这能让你提前知道序列化器的默认行为。
  5. 把环境变量设成 Production 再启动,访问一个不存在的路由,对比错误页的变化。注意这一步只改环境变量,不改任何代码。

小结

下一篇讲路由和请求管道。上面那个「洋葱」只是直觉,真正决定请求走哪条路、哪个中间件先执行、认证为什么有时不生效的,是 UseRouting、UseAuthentication、UseAuthorization 和端点注册的相对位置。第 1 篇里所有端点都是匿名可访问的,一旦加上鉴权,顺序错一步就会出现「明明登录了还是 401」。

这篇的三句话总结:第一,SDK、运行时、框架、Kestrel 是四层不同的东西,报错时要先判断问题在哪一层,别一上来改代码;第二,minimal API 和 Controller 是组织方式之争,端点少于三十个、团队一两个人时前者更省事,超过这个规模就该考虑后者;第三,dotnet run 只是开发态,端口会被 launchSettings 抢走,上线要用 publish 产物并把环境切到 Production。