2. 控制器、操作、路由
本章考察请求从浏览器到处理它的操作所经过的路径,以及该操作返回的响应。视图要到第 4 章才会介绍:在此处,操作直接返回文本或 JSON。
2.1. 示例 01:ASP.NET Core MVC 应用程序的结构
第一个示例是尽可能小的 [ASP.NET Core MVC] 应用程序。除了引言中介绍的 [Example01.csproj] 和 [appsettings.json] 文件外,它还有两个文件:
| 01-structure/
├── Controllers/
│ └── HomeController.cs
├── appsettings.json
├── Example01.csproj
└── Program.cs
|
2.1.1. 入口点:Program.cs
| // 应用程序“构建器”:配置、日志、服务……
var builder = WebApplication.CreateBuilder(args);
// 注册 MVC 查找并运行控制器所需的服务
builder.Services.AddControllers();
// 构建应用程序
var app = builder.Build();
// 启用控制器声明的路由([HttpGet("/")]……)
app.MapControllers();
// 启动 HTTP 服务器(默认为 http://localhost:5000);Ctrl-C 停止
app.Run();
|
我们来逐段分析这段代码:
- 第 2 行:[WebApplication.CreateBuilder] 创建应用程序的“构建器”。它读取配置([appsettings.json] 文件、环境变量等),设置日志记录,并准备应用程序的 服务列表 [builder.Services]。[args] 参数包含命令行参数;
- 第 5 行:将 [MVC] 查找应用程序控制器并执行其操作所需的服务添加到列表中;
- 第 8 行:构建应用程序。在这一行之后,就不能再修改服务列表了;
- 第 11 行:启用控制器声明的路由(特性 [[HttpGet]]、[[Route]]……,我们后面会讨论):没有这一行,就永远不会调用任何操作;
- 第 14 行:启动 [Kestrel] Web 服务器并等待请求,直到应用程序停止([Ctrl-C])。除非另有指定,服务器监听 5000 端口。
这个文件既不包含名为 [Main] 的类也不包含这样的方法:它是一个 基于高级语句的程序。[C#] 编译器会自行把这些语句包装成一个名为 [Main] 的方法,作为程序的入口点。还要注意没有 [using] 指令:[WebApplication] 属于 [Microsoft.AspNetCore.Builder] 命名空间,该命名空间是自动导入的(参见引言中的 [ImplicitUsings] )。
2.1.2. 控制器:Controllers/HomeController.cs
| using Microsoft.AspNetCore.Mvc;
namespace Example01.Controllers;
// 控制器是继承自 Controller 的类
public class HomeController : Controller
{
// 一个操作:处理 GET / 请求时调用的方法
[HttpGet("/")]
public string Index()
{
// 操作返回的值就是发送给浏览器的响应
return "Hello from ASP.NET Core MVC!";
}
}
|
- 第 1 行:包含 [Controller] 类以及 [MVC] 特性的命名空间;
- 第 3 行:此文件中各个类所在的命名空间。按照惯例,它包含项目名称([Example01])和文件所在的目录([Controllers])。形式 [namespace X;] (不带花括号)作用于整个文件。
- 第 6 行:控制器是一个继承自 public 类 [Controller] 的类。按照惯例,其名称以 [Controller] 结尾。[ASP.NET Core] 会自动找到应用程序的控制器——无需声明它们;
- 第 9 行:[[HttpGet("/")]] 特性将 [Index] 方法与 [GET /] 请求关联起来。以这种方式与路由关联的方法就是一个 操作(action)。[C#] 的特性写在方括号中,紧挨在它所描述的对象之前:它为方法添加信息,框架在启动时读取这些信息;
- 第 13 行:操作返回的值就是发送给浏览器的响应。
2.1.3. 运行
在 [01-structure] 目录下打开的终端窗口中,输入 [dotnet run]。编译完成后,服务器启动:
| info: Microsoft.Hosting.Lifetime[14]
Now listening on: http://localhost:5000
info: Microsoft.Hosting.Lifetime[0]
Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
Hosting environment: Production
info: Microsoft.Hosting.Lifetime[0]
Content root path: C:\course\examples\01-structure
|
启动消息会指出监听地址([http://localhost:5000])和运行环境:[Production],即默认环境。我们将看到,[ASP.NET Core] 的某些行为取决于环境([Development] 或 [Production])。让我们用浏览器请求 URL [http://localhost:5000/] :

然后用 [curl] 请求。[-i] 选项还会显示响应的 HTTP 头(这里只展示其中几个):
| curl -i http://localhost:5000/
|
| HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
Hello from ASP.NET Core MVC!
|
操作返回的字符串会带着头 [Content-Type: text/plain] 发送:浏览器将其显示为纯文本,不作解释。这与 [NestJS] 不同,后者将其作为 HTML 发送([text/html])。示例 03 将展示如何发送 HTML。
2.2. 示例 02:路由
路由将一个 URL 和一个 HTTP 方法(GET、POST 等)与一个操作关联起来。示例 02 有两个控制器:
| 02-routing/
├── Controllers/
│ ├── FirstController.cs
│ └── HomeController.cs
├── appsettings.json
├── Example02.csproj
└── Program.cs
|
文件 [Program.cs] 与示例 01 中的相同:本章中除最后一个示例外的所有示例都是如此。文件 [Controllers/HomeController.cs]:
| using Microsoft.AspNetCore.Mvc;
namespace Example02.Controllers;
public class HomeController : Controller
{
// GET /:一个包含指向其他操作的链接的 HTML 页面
[HttpGet("/")]
public ContentResult Index()
{
const string html = """
<h2>Example 02 - routing</h2>
<ul>
<li><a href="/first">/first</a></li>
<li><a href="/first/action01">/first/action01</a></li>
<li><a href="/first/products/17">/first/products/17</a></li>
<li><a href="/first/products/17/reviews/3">/first/products/17/reviews/3</a></li>
<li><a href="/first/files/images/logo.png">/first/files/images/logo.png</a></li>
<li><a href="/first/products/abc">/first/products/abc</a></li>
<li><a href="/unknown">/unknown</a></li>
</ul>
""";
// Content(text, type):由我们选择类型的响应(此处为 HTML)
return Content(html, "text/html; charset=utf-8");
}
}
|
- 第 9 行:该操作不再返回字符串,而是返回 [ContentResult]:一个指定了内容 和 类型的响应;
- 第 11–22 行:一个 [C#] 原始字符串([raw string literal]),以三个引号分隔。它可以跨越多行,并且可以包含引号而无需转义。位于结尾的 ["""] 之前的空格会从每一行中去除;
- 第 24 行:[Content(text, type)] 方法(属于 [Controller] 类)生成一个 [ContentResult]。[text/html] 类型指示浏览器将文本解释为 HTML。
因此,[Index] 操作返回一个 HTML 页面,其中包含指向另一个控制器各操作的链接:

[Controllers/FirstController.cs] 文件:
| using Microsoft.AspNetCore.Mvc;
namespace Example02.Controllers;
// 控制器所有路由共享的前缀
[Route("first")]
public class FirstController : Controller
{
// GET /first
[HttpGet("")]
public string Index()
{
return "Action [Index] of the [First] controller";
}
// GET /first/action01
[HttpGet("action01")]
public string Action01()
{
return "Action [Action01] of the [First] controller, GET request";
}
// POST /first/action01:路径相同,HTTP 方法不同
[HttpPost("action01")]
public string Action01Post()
{
return "Action [Action01Post] of the [First] controller, POST request";
}
// GET /first/products/17:{id} 是路由参数,":int" 是约束
[HttpGet("products/{id:int}")]
public string Product(int id)
{
return $"Product no. {id}";
}
// GET /first/products/17/reviews/3:两个路由参数
[HttpGet("products/{id:int}/reviews/{number:int}")]
public string Review(int id, int number)
{
return $"Review no. {number} of product no. {id}";
}
// GET /first/files/...:{**path} 接受任意路径结尾
[HttpGet("files/{**path}")]
public string File(string path)
{
return $"Requested file: {path}";
}
}
|
我们来逐段分析这段代码:
- 第 6 行:应用于类的 [[Route("first")]] 特性设置了该控制器所有路由共有的前缀:它的各个操作处理以 [/first] 开头的 URL 路由;
- 第 10–11 行:[[HttpGet("")]]:操作 [Index] 处理 [GET /first]。操作的 URL 是控制器前缀与操作路径的拼接;
- 第 17–18 行:操作 [Action01] 处理 [GET /first/action01];
- 第 24–25 行:相同的路径,但用于 POST 方法:[[HttpPost]] 取代了 [[HttpGet]]。此外还有 [[HttpPut]]、[[HttpDelete]]、[[HttpPatch]]……方法的名称 [C#] ([Action01Post])是任意的:对路由而言只有特性才重要。此外,在同一个类中,两个方法不能同名且参数相同;
- 第 31–32 行:[{id}] 是一个 路由参数:URL 的这一段可以取多个值。[:int] 是一个 约束:该段必须是整数;否则,路由不匹配。该段的值会传递给操作中同名的参数 [id],并且已经被转换为 [int]:对于 [/first/products/17],[id] 等于数字 17。这就是 模型绑定 ([model binding]),下一章将详细讲解;
- 第 38–39 行:两个路由参数,传递给操作的两个参数;
- 第 44–46 行:[{**path}] 是一个“通配”参数([catch-all]):它接受 URL 的任何结尾,包括 [/]。
下面是几个请求的结果:
| curl -i http://localhost:5000/first
|
| HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
Action [Index] of the [First] controller
|
| curl -i http://localhost:5000/first/action01
|
| HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
Action [Action01] of the [First] controller, GET request
|
| curl -i http://localhost:5000/first/products/17
|
| HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
Product no. 17
|
| curl -i http://localhost:5000/first/products/17/reviews/3
|
| HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
Review no. 3 of product no. 17
|
| curl -i http://localhost:5000/first/files/images/logo.png
|
| HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
Requested file: images/logo.png
|
要发送 POST 请求,请使用 [-X POST] 选项(属于 [curl]):
| curl -i -X POST http://localhost:5000/first/action01
|
| HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
Action [Action01Post] of the [First] controller, POST request
|
如果某个 HTTP 方法没有被针对该路径的任何操作处理,就会导致 405 错误([Method Not Allowed])。[Allow] 头列出了接受的方法:
| curl -i -X PUT http://localhost:5000/first/action01
|
| HTTP/1.1 405 Method Not Allowed
Content-Length: 0
Allow: GET, POST
|
最后,没有任何路由处理的 URL 会导致 404 错误。对于不满足 [:int] 约束的标识符也是如此:没有路由与 [/first/products/abc] 匹配。
| curl -i http://localhost:5000/first/products/abc
|
| HTTP/1.1 404 Not Found
Content-Length: 0
|
| curl -i http://localhost:5000/unknown
|
| HTTP/1.1 404 Not Found
Content-Length: 0
|
[ASP.NET Core] 的 404 响应没有内容([Content-Length: 0]):浏览器会显示它自己的错误页面。

第 7 章将展示如何用 HTML 页面取代这个空响应。
2.3. 示例 03:操作的响应
操作的返回值决定了 HTTP 响应。示例 03 回顾了主要的情形。文件 [Controllers/ResponsesController.cs]:
| using Microsoft.AspNetCore.Mvc;
namespace Example03.Controllers;
[Route("responses")]
public class ResponsesController : Controller
{
// 字符串:原样发送,类型为 [text/plain]
[HttpGet("text")]
public string Text()
{
return "<h1>Action [Text]</h1>";
}
// 同一个字符串,声明为 HTML:浏览器会对其进行解释
[HttpGet("html")]
public ContentResult Html()
{
return Content("<h1>Action [Html]</h1>", "text/html; charset=utf-8");
}
// 对象:序列化为 JSON,类型为 [application/json]
[HttpGet("json")]
public object Json()
{
return new { lastName = "Martin", firstName = "Jean", age = 42 };
}
// 数组:同样序列化为 JSON
[HttpGet("array")]
public string[] Array()
{
return ["Mme", "Melle", "Mr"];
}
// IActionResult:由操作选择完整的响应(状态码、内容)
// StatusCode(201, ...):返回 201 状态码(Created)而不是 200(OK)
[HttpGet("created")]
public IActionResult ResourceCreated()
{
return StatusCode(201, new { message = "resource created" });
}
// 无响应:204 状态码(No Content)表示“没有可显示的内容”
[HttpGet("empty")]
public IActionResult EmptyResponse()
{
return NoContent();
}
// 异步操作:ASP.NET 等待任务(Task)结束
[HttpGet("task")]
public async Task<object> AsyncTask()
{
var start = DateTime.Now;
await Task.Delay(500); // 等待 500 毫秒,且不阻塞服务器
return new { wait = $"{(DateTime.Now - start).TotalMilliseconds:0} ms" };
}
// “预期内”的错误:NotFound(...) 生成 404 响应
[HttpGet("not-found")]
public IActionResult NotFoundError()
{
return NotFound(new { message = "This resource does not exist" });
}
// “预期外”的错误:未处理的异常生成 500 响应
[HttpGet("exception")]
public string Exception()
{
throw new InvalidOperationException("An unexpected error");
}
}
|
我们来逐段分析这段代码:
- 第 9–12 行:字符串按原样发送,带有头 [Content-Type: text/plain; charset=utf-8];
- 第 16–19 行:同一个字符串,声明为 HTML(见示例 02):浏览器会解释它;
- 第 23–26 行:对象被 序列化 为 JSON,带有头 [Content-Type: application/json]。[new { lastName = ..., firstName = ... }] 创建一个 匿名类型的对象:由编译器生成的无名类型,适用于只使用一次的数据。JSON 的属性名采用“camelCase”(首字母小写)写法,遵循 [JavaScript] 的约定;
- 第 30–33 行:数组同样被序列化为 JSON。[["Mme", "Melle", "Mr"]] 是一个 集合表达式 ([C#] 12),在这里它创建一个字符串数组;
- 第 39–41 行:当操作需要选择状态码时,它返回 [IActionResult]:描述完整响应的对象。[Controller] 类的方法可以生成许多这样的对象:[StatusCode(201, object)] 生成一个状态码为 201 的响应([Created]),其内容是序列化为 JSON 的对象;
- 第 46–48 行:[NoContent()] 返回状态码 204([No Content]):“无内容”;
- 第 53–57 行:操作可以是 异步的 ([async]):此时它返回一个任务([Task<T>]),相当于 [JavaScript] 中的 promise,并且 [ASP.NET Core] 会等待任务完成后再响应。[await Task.Delay(500)] 等待 500 毫秒,而不会阻塞 服务器:在等待期间,原本执行该操作的线程会被归还给服务器,服务器可以用它来处理其他请求。所有查询数据库的操作都是这样编写的;
- 第 62–64 行:程序预期会出现的错误:[NotFound(object)] 返回内容为 JSON 的 404 响应。类似地,还有 [BadRequest(...)] (400)、[Unauthorized()] (401)、[Forbid()] (403)、[Ok(...)] (200)……;
- 第 69–71 行:一个 意外错误:操作抛出了一个它没有处理的异常。[ASP.NET Core] 随后以 500 错误([Internal Server Error])作出响应。
收到的响应:
| curl -i http://localhost:5000/responses/text
|
| HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
<h1>Action [Text]</h1>
|
| curl -i http://localhost:5000/responses/html
|
| HTTP/1.1 200 OK
Content-Length: 22
Content-Type: text/html; charset=utf-8
<h1>Action [Html]</h1>
|
| curl -i http://localhost:5000/responses/json
|
| HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{"lastName":"Martin","firstName":"Jean","age":42}
|
| curl -i http://localhost:5000/responses/array
|
| HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
["Mme","Melle","Mr"]
|
| curl -i http://localhost:5000/responses/created
|
| HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
{"message":"resource created"}
|
| curl -i http://localhost:5000/responses/empty
|
| curl -i http://localhost:5000/responses/task
|
| HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{"wait":"514 ms"}
|
| curl -i http://localhost:5000/responses/not-found
|
| HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8
{"message":"This resource does not exist"}
|
| curl -i http://localhost:5000/responses/exception
|
| HTTP/1.1 500 Internal Server Error
Content-Length: 0
|
对于这个异常,响应不提供关于错误的任何信息:这些细节可能帮助攻击者。它们会被记录在服务器控制台中(这里只复现开头部分):
| fail: Microsoft.AspNetCore.Server.Kestrel[13]
Connection id "0HNP6TN0D56ES", Request id "0HNP6TN0D56ES:00000001": An unhandled exception was thrown by the application.
System.InvalidOperationException: An unexpected error
at Example03.Controllers.ResponsesController.Exception() in ...\03-responses\Controllers\ResponsesController.cs:line 71
...
|
在浏览器中,可以看出 [text/plain] 与 [text/html] 之间的差别:


2.4. 示例 04:重定向
操作可以用重定向来响应:状态码 301 或 302,以及一个 [Location] 头,告诉浏览器接下来应请求哪个 URL。浏览器会立即请求它,无需用户干预。重定向在 Web 应用程序中无处不在:成功提交表单之后、登录之后、切换语言之后……
[Controllers/RedirectsController.cs] 文件:
| using Microsoft.AspNetCore.Mvc;
namespace Example04.Controllers;
public class RedirectsController : Controller
{
// 永久重定向(301):页面地址已永久改变
[HttpGet("old")]
public IActionResult OldPage()
{
return RedirectPermanent("/new");
}
[HttpGet("new")]
public string NewPage()
{
return "You are on the [new] page";
}
// 临时重定向(302),指向一个计算得出的地址
[HttpGet("go/{destination}")]
public IActionResult Go(string destination)
{
return Redirect($"/page/{destination}");
}
// 重定向到某个操作:由 ASP.NET 自行构建 URL
[HttpGet("to-action/{destination}")]
public IActionResult ToAction(string destination)
{
return RedirectToAction(nameof(Page), new { name = destination });
}
[HttpGet("page/{name}")]
public string Page(string name)
{
return $"You are on the [{name}] page";
}
// 重定向到另一个站点
[HttpGet("documentation")]
public IActionResult Documentation()
{
return Redirect("https://learn.microsoft.com/aspnet/core");
}
}
|
我们来逐段分析这段代码:
- 第 9–11 行:[RedirectPermanent(url)] 生成永久重定向(状态码 301,[Moved Permanently]):页面的地址已永久更改。浏览器和搜索引擎可以缓存新地址;
- 第 22–24 行:[Redirect(url)] 生成临时重定向(状态码 302,[Found]),此处重定向到一个计算出来的地址。[$"/page/{destination}"] 是一个 内插字符串:花括号内的表达式会被它的值替换;
- 第 29–31 行:[RedirectToAction(action, values)] 重定向到一个 操作,而不是 URL:[ASP.NET Core] 会根据操作 [Page] 的路由([page/{name}])和提供的值([name = destination])自行生成该操作的 URL。如果操作的路径日后发生变化,重定向也会随之变化。[nameof(Page)] 返回方法名(["Page"]):拼写错误会导致编译错误,而手写字符串则没有这种保护;
- 第 42–44 行:可以重定向到另一个网站。
[curl] 演示重定向但不跟随它:
| curl -i http://localhost:5000/old
|
| HTTP/1.1 301 Moved Permanently
Content-Length: 0
Location: /new
|
使用选项 [-L],[curl] 会像浏览器一样跟随重定向。随后我们看到两个先后到来的响应:
| curl -i -L http://localhost:5000/old
|
| HTTP/1.1 301 Moved Permanently
Content-Length: 0
Location: /new
HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
You are on the [new] page
|
| curl -i http://localhost:5000/go/contact
|
| HTTP/1.1 302 Found
Content-Length: 0
Location: /page/contact
|
| curl -i http://localhost:5000/to-action/contact
|
| HTTP/1.1 302 Found
Content-Length: 0
Location: /page/contact
|
两个操作都得到相同的重定向:一个使用手写的 URL,另一个使用由 [ASP.NET Core] 生成的 URL。在浏览器中,只能看到最终的页面;地址栏显示新的 URL:

| curl -i http://localhost:5000/documentation
|
| HTTP/1.1 302 Found
Content-Length: 0
Location: https://learn.microsoft.com/aspnet/core
|
2.5. 示例 05:请求对象与响应对象
每个请求都由一个 [HttpContext] 对象表示,它包含请求([Request])和当前正在生成的响应([Response])。操作可以通过 [HttpContext]、[Request] 和 [Response] 属性(属于 [Controller] 类)直接访问它。这有时是必要的,我们在案例研究中也会这样做(例如读取或设置 Cookie),但你必须清楚自己在做什么。
文件 [Controllers/HttpController.cs]:
| using Microsoft.AspNetCore.Mvc;
namespace Example05.Controllers;
[Route("http")]
public class HttpController : Controller
{
// 请求:方法、路径、参数、标头……
[HttpGet("request")]
public object RequestInfo()
{
return new
{
method = Request.Method,
path = Request.Path.Value,
parameters = Request.QueryString.Value,
browser = Request.Headers.UserAgent.ToString(),
ip = HttpContext.Connection.RemoteIpAddress?.ToString(),
};
}
// 响应:我们为其添加一个标头,然后操作照常返回其值
[HttpGet("header")]
public string Header()
{
Response.Headers["X-Example"] = "05-httpcontext";
return "Response with an added header";
}
// “手工”写出的响应:状态码、类型,然后是正文
[HttpGet("response")]
public async Task ResponseByHand()
{
Response.StatusCode = 200;
Response.ContentType = "text/plain; charset=utf-8";
await Response.WriteAsync("Response written by [Response.WriteAsync]");
}
// 不要犯的错误:先写响应,再返回结果
[HttpGet("double")]
public async Task<IActionResult> Double()
{
await Response.WriteAsync("Start of the response... ");
// 响应已经发出:其状态码和标头不能再更改
return NotFound();
}
}
|
我们来逐段分析这段代码:
- 第 10–18 行:请求:HTTP 方法([Request.Method])、路径([Request.Path])、URL 的参数([Request.QueryString])、头([Request.Headers]),以及通过 [HttpContext.Connection] 得到的客户端地址(IP)。[?.] 是“null 条件”运算符:如果 [RemoteIpAddress] 等于 [null],表达式的值为 [null] ,而不会引发错误;
- 第 24–27 行:操作向响应添加一个头,然后照常返回其值,由 [ASP.NET Core] 发送。这是 [Response] 最常见的用法;
- 第 32–36 行:操作自己写入响应——状态码、类型,然后是正文——使用 [Response.WriteAsync]。它不返回任何内容([Task],而不是 [Task<T>]);
- 第 41–45 行:应避免的错误:写入了部分响应 之后又 返回一个结果。一旦正文的第一批字节已发送到浏览器,在正文之前发送的状态码和头就不能再更改了。
得到的响应:
| curl -i -A "Mozilla/5.0 (example)" "http://localhost:5000/http/request?name=martin"
|
| HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{"method":"GET","path":"/http/request","parameters":"?name=martin","browser":"Mozilla/5.0 (example)","ip":"127.0.0.1"}
|
([-A] 选项(属于 [curl] )用于设置 [User-Agent] 头,该头用于标识浏览器)
| curl -i http://localhost:5000/http/header
|
| HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
X-Example: 05-httpcontext
Response with an added header
|
| curl -i http://localhost:5000/http/response
|
| HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
Response written by [Response.WriteAsync]
|
| curl -i http://localhost:5000/http/double
|
| HTTP/1.1 200 OK
Start of the response...
|
对于最后一个操作,浏览器收到的是状态码 200 和响应的开头部分,而不是所请求的 404。服务器控制台会报告该错误:
| fail: Microsoft.AspNetCore.Server.Kestrel[13]
Connection id "0HNP6TN1VG5OL", Request id "0HNP6TN1VG5OL:00000001": An unhandled exception was thrown by the application.
System.InvalidOperationException: StatusCode cannot be set because the response has already started.
...
|
在本文档的其余部分,操作几乎总是返回一个结果([IActionResult]),并让 [ASP.NET Core] 来写入响应。[Request] 和 [Response] 将只用于读取请求和设置 Cookie。
2.6. 示例 06:服务与依赖注入
控制器不应包含应用程序逻辑;它们把逻辑委托给 服务。服务是一个普通对象,由 [ASP.NET Core] 创建并提供给需要它的类:这就是 依赖注入。示例 06 把一个小型应用程序分解为两部分:产品和客户:
| 06-services/
├── Clients/
│ └── ClientsController.cs
├── Products/
│ ├── IProductsService.cs
│ ├── Product.cs
│ ├── ProductsController.cs
│ ├── ProductsExtensions.cs
│ └── ProductsService.cs
├── appsettings.json
├── Example06.csproj
└── Program.cs
|
2.6.1. 产品(Product)
| namespace Example06.Products;
// “record”:属性由构造函数设置的数据类
public record Product(int Id, string Name, decimal Price);
|
一个 record:用一行声明的数据类。编译器会创建属性 [Id], [Name], and [Price]、一个初始化它们的构造函数,以及一些实用方法(比较、显示)。[decimal] 类型表示金额,不会有舍入误差。
2.6.2. 服务契约:IProductsService
| namespace Example06.Products;
// 服务的契约:它能做什么,而不说明如何做
public interface IProductsService
{
IReadOnlyList<Product> FindAll();
Product? FindById(int id);
}
|
- 第 4 行:接口 描述服务能做什么,而不指明如何做。使用该服务的类只会知道这个接口;
- 第 6 行:[IReadOnlyList<Product>]:调用者可以读取但不能修改的列表;
- 第 7 行:[Product?]:一个产品,或者在没有产品具有该标识符时为 [null] (参见引言中的 [Nullable] )。
2.6.3. 实现:ProductsService
| namespace Example06.Products;
// 契约的实现:此处为内存中的数据
public class ProductsService : IProductsService
{
private readonly List<Product> products =
[
new Product(1, "pen", 1.5m),
new Product(2, "notebook", 3.2m),
new Product(3, "eraser", 0.8m),
];
public IReadOnlyList<Product> FindAll() => products;
public Product? FindById(int id) => products.FirstOrDefault(p => p.Id == id);
}
|
- 第 4 行:该类 实现 该接口:它必须提供接口的所有方法;
- 第 6–11 行:数据,这里放在内存中,存放在由集合表达式初始化的列表里;
- 第 13–15 行:这两个方法使用 [=>] 语法编写(方法体只有一个表达式的方法)。[FirstOrDefault] ([LINQ])返回第一个满足条件的结果,如果没有则返回 [null] 。
2.6.4. ProductsController 控制器
| using Microsoft.AspNetCore.Mvc;
namespace Example06.Products;
[Route("products")]
public class ProductsController : Controller
{
private readonly IProductsService productsService;
// 依赖注入:ASP.NET 提供 IProductsService 的实现
public ProductsController(IProductsService productsService)
{
this.productsService = productsService;
}
[HttpGet("")]
public IReadOnlyList<Product> List()
{
return productsService.FindAll();
}
[HttpGet("{id:int}")]
public IActionResult OneProduct(int id)
{
var product = productsService.FindById(id);
if (product is null)
{
return NotFound(new { message = $"Product no. {id} not found" });
}
return Ok(product);
}
}
|
- 第 11–13 行:依赖注入。控制器在其构造函数中声明它需要一个 [IProductsService];[ASP.NET Core] 会为它提供为该类型注册的对象(见下文)。控制器从不调用 [new ProductsService()]:它甚至不知道这个类,只知道接口。可以替换实现(换成读取数据库的版本,或测试用的版本)而无需修改控制器;
- 第 17–19 行:操作把工作委托给服务。列表被序列化为 JSON;
- 第 23–30 行:[{id:int}] 转换标识符;不存在的产品会返回 404 响应。[Ok(object)] 返回 200 响应,其内容是序列化为 JSON 的对象。[is null] 检查某个值是否为 null。
2.6.5. ClientsController 控制器
| using Example06.Products;
using Microsoft.AspNetCore.Mvc;
namespace Example06.Clients;
// “主构造函数”(C# 12):构造函数参数直接写在类名之后
// 并可在整个类中使用
[Route("clients")]
public class ClientsController(IProductsService productsService) : Controller
{
[HttpGet("cart")]
public object Cart()
{
var products = productsService.FindAll();
return new { client = "Jean Martin", items = products.Count, total = products.Sum(p => p.Price) };
}
}
|
- 第 9 行:一个 主构造函数 ([C#] 12):构造函数参数直接写在类名之后。它可以在整个类中使用:无需把它复制到字段中。这是最紧凑的依赖注入形式;本文档的其余部分都将使用它。[ClientsController] 收到的服务与 [ProductsController] 相同;
- 第 12–15 行:它用该服务计算购物车的总额。[Sum] ([LINQ])将各个价格相加。
2.6.6. 服务注册
[ASP.NET Core] 只有知道某个服务才能提供它:每个服务都要 注册 到 [builder.Services] 中,并指定其 生存期。文件 [Products/ProductsExtensions.cs]:
| namespace Example06.Products;
// “扩展方法”:调用时就像它是 IServiceCollection 的一部分
// (builder.Services.AddProducts())。它将应用程序“产品”部分的
// 注册集中在一起。
public static class ProductsExtensions
{
public static IServiceCollection AddProducts(this IServiceCollection services)
{
// “请求 IProductsService 时,提供 ProductsService”;
// Singleton:单个实例,由所有请求共享
services.AddSingleton<IProductsService, ProductsService>();
return services;
}
}
|
- 第 6 行:一个静态类,只包含静态方法;
- 第 8 行:一个 扩展方法。第一个参数之前的关键字 [this] 使它可以像该参数类型自身的成员一样被调用:[builder.Services.AddProducts()]。[ASP.NET Core] 的各个库就是这样添加它们的服务的([AddControllers]、[AddAuthentication]……),这也是把应用程序某一特定部分的注册集中在一起的好办法;
- 第 12 行:“当某个类请求 [IProductsService] 时,向它提供一个 [ProductsService]。”[Singleton] 是服务的生存期:只有一个实例,在第一次请求时创建,并由所有请求共享。另外还有两种生存期:[Scoped] (每个请求一个实例)和 [Transient](每次请求都新建一个实例)。第 6 章将重新讨论这个主题;
- 第 13 行:该方法返回服务列表,以便可以链式调用。
文件 [Program.cs]:
| using Example06.Products;
var builder = WebApplication.CreateBuilder(args);
// MVC 服务
builder.Services.AddControllers();
// “产品”部分的服务(见 Products/ProductsExtensions.cs)
builder.Services.AddProducts();
var app = builder.Build();
app.MapControllers();
app.Run();
|
- 第 1 行:扩展方法的命名空间;
- 第 8 行:产品服务的注册。
另一方面,控制器不需要逐个注册:[AddControllers] 会找到所有控制器,并且 [ASP.NET Core] 会为每个请求创建一个新的控制器对象,把它所请求的服务注入其中。
2.6.7. 运行
| curl -i http://localhost:5000/products
|
| HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
[{"id":1,"name":"pen","price":1.5},{"id":2,"name":"notebook","price":3.2},{"id":3,"name":"eraser","price":0.8}]
|
| curl -i http://localhost:5000/products/2
|
| HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{"id":2,"name":"notebook","price":3.2}
|
| curl -i http://localhost:5000/products/9
|
| HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8
{"message":"Product no. 9 not found"}
|
| curl -i http://localhost:5000/clients/cart
|
| HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{"client":"Jean Martin","items":3,"total":5.5}
|
案例研究的结构与此完全相同:轻量的控制器把工作委托给注入的服务,这些服务由接口描述,并在 [Program.cs] 中注册。