Skip to content

2. 控制器、操作、路由

本章考察请求从浏览器到处理它的操作所经过的路径,以及该操作返回的响应。视图要到第 4 章才会介绍:在此处,操作直接返回文本或 JSON。

2.1. 示例 01:ASP.NET Core MVC 应用程序的结构

第一个示例是尽可能小的 [ASP.NET Core MVC] 应用程序。除了引言中介绍的 [Example01.csproj] 和 [appsettings.json] 文件外,它还有两个文件:

1
2
3
4
5
6
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]。编译完成后,服务器启动:

1
2
3
4
5
6
7
8
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/] :

Image

然后用 [curl] 请求。[-i] 选项还会显示响应的 HTTP 头(这里只展示其中几个):

curl -i http://localhost:5000/
1
2
3
4
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 有两个控制器:

1
2
3
4
5
6
7
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 页面,其中包含指向另一个控制器各操作的链接:

Image

[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
1
2
3
4
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
1
2
3
4
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
1
2
3
4
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
1
2
3
4
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
1
2
3
4
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
1
2
3
4
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
1
2
3
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]):浏览器会显示它自己的错误页面。

Image

第 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
1
2
3
4
HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8

<h1>Action [Text]</h1>
curl -i http://localhost:5000/responses/html
1
2
3
4
5
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
1
2
3
4
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
1
2
3
4
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

["Mme","Melle","Mr"]
curl -i http://localhost:5000/responses/created
1
2
3
4
HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{"message":"resource created"}
curl -i http://localhost:5000/responses/empty
HTTP/1.1 204 No Content
curl -i http://localhost:5000/responses/task
1
2
3
4
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"wait":"514 ms"}
curl -i http://localhost:5000/responses/not-found
1
2
3
4
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

对于这个异常,响应不提供关于错误的任何信息:这些细节可能帮助攻击者。它们会被记录在服务器控制台中(这里只复现开头部分):

1
2
3
4
5
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] 之间的差别:

Image

Image

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
1
2
3
HTTP/1.1 301 Moved Permanently
Content-Length: 0
Location: /new

使用选项 [-L],[curl] 会像浏览器一样跟随重定向。随后我们看到两个先后到来的响应:

curl -i -L http://localhost:5000/old
1
2
3
4
5
6
7
8
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
1
2
3
HTTP/1.1 302 Found
Content-Length: 0
Location: /page/contact
curl -i http://localhost:5000/to-action/contact
1
2
3
HTTP/1.1 302 Found
Content-Length: 0
Location: /page/contact

两个操作都得到相同的重定向:一个使用手写的 URL,另一个使用由 [ASP.NET Core] 生成的 URL。在浏览器中,只能看到最终的页面;地址栏显示新的 URL:

Image

curl -i http://localhost:5000/documentation
1
2
3
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"
1
2
3
4
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
1
2
3
4
5
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
1
2
3
4
HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8

Response written by [Response.WriteAsync]
curl -i http://localhost:5000/http/double
1
2
3
HTTP/1.1 200 OK

Start of the response... 

对于最后一个操作,浏览器收到的是状态码 200 和响应的开头部分,而不是所请求的 404。服务器控制台会报告该错误:

1
2
3
4
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)

1
2
3
4
namespace Example06.Products;

// “record”:属性由构造函数设置的数据类
public record Product(int Id, string Name, decimal Price);

一个 record:用一行声明的数据类。编译器会创建属性 [Id], [Name], and [Price]、一个初始化它们的构造函数,以及一些实用方法(比较、显示)。[decimal] 类型表示金额,不会有舍入误差。

2.6.2. 服务契约:IProductsService

1
2
3
4
5
6
7
8
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
1
2
3
4
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
1
2
3
4
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
1
2
3
4
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
1
2
3
4
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"client":"Jean Martin","items":3,"total":5.5}

案例研究的结构与此完全相同:轻量的控制器把工作委托给注入的服务,这些服务由接口描述,并在 [Program.cs] 中注册。