{"id":578,"date":"2025-04-05T03:25:37","date_gmt":"2025-04-04T19:25:37","guid":{"rendered":"https:\/\/www.hyy.net\/?p=578"},"modified":"2025-04-05T03:25:37","modified_gmt":"2025-04-04T19:25:37","slug":"asp-net-core-in-action-5-creating-a-json-api-with-minimal-apis","status":"publish","type":"post","link":"https:\/\/diji.net\/?p=578","title":{"rendered":"ASP.NET Core in Action 5 Creating a JSON API with minimal APIs"},"content":{"rendered":"

5 Creating a JSON API with minimal APIs
\n5 \u4f7f\u7528\u6700\u5c11\u7684 API \u521b\u5efa JSON API<\/p>\n

This chapter covers<\/h2>\n

\u672c\u7ae0\u6db5\u76d6<\/h2>\n

\u2022 Creating a minimal API application to return JSON to clients
\n\u521b\u5efa\u6700\u5c0f API \u5e94\u7528\u7a0b\u5e8f\u4ee5\u5c06 JSON \u8fd4\u56de\u7ed9\u5ba2\u6237\u7aef<\/p>\n

\u2022 Generating responses with IResult
\n\u751f\u6210\u54cd\u5e94IResult<\/p>\n

\u2022 Using filters to perform common actions like validation
\n\u4f7f\u7528\u7b5b\u9009\u5668\u6267\u884c\u5e38\u89c1\u4f5c\uff0c\u5982\u9a8c\u8bc1<\/p>\n

\u2022 Organizing your APIs with route groups
\n\u4f7f\u7528\u8def\u7531\u7ec4\u7ec4\u7ec7 API<\/p>\n

So far in this book you\u2019ve seen several examples of minimal API applications that return simple Hello World! responses. These examples are great for getting started, but you can also use minimal APIs to build full-featured HTTP API applications. In this chapter you\u2019ll learn about HTTP APIs, see how they differ from a server-rendered application, and find out when to use them.<\/p>\n

\u5230\u76ee\u524d\u4e3a\u6b62\uff0c\u5728\u672c\u4e66\u4e2d\uff0c\u60a8\u5df2\u7ecf\u770b\u5230\u4e86\u51e0\u4e2a\u6700\u5c0f API \u5e94\u7528\u7a0b\u5e8f\u7684\u793a\u4f8b\uff0c\u8fd9\u4e9b\u5e94\u7528\u7a0b\u5e8f\u8fd4\u56de\u7b80\u5355\u7684 Hello World\uff01\u3002\u8fd9\u4e9b\u793a\u4f8b\u975e\u5e38\u9002\u5408\u5165\u95e8\uff0c\u4f46\u60a8\u4e5f\u53ef\u4ee5\u4f7f\u7528\u6700\u5c11\u7684 API \u6765\u6784\u5efa\u529f\u80fd\u9f50\u5168\u7684 HTTP API \u5e94\u7528\u7a0b\u5e8f\u3002\u5728\u672c\u7ae0\u4e2d\uff0c\u60a8\u5c06\u4e86\u89e3 HTTP API\uff0c\u4e86\u89e3\u5b83\u4eec\u4e0e\u670d\u52a1\u5668\u5448\u73b0\u7684\u5e94\u7528\u7a0b\u5e8f\u6709\u4f55\u4e0d\u540c\uff0c\u5e76\u4e86\u89e3\u4f55\u65f6\u4f7f\u7528\u5b83\u4eec\u3002<\/p>\n

Section 5.2 starts by expanding on the minimal API applications you\u2019ve already seen. You\u2019ll explore some basic routing concepts and show how values can be extracted from the URL automatically. Then you\u2019ll learn how to handle additional HTTP verbs such as POST and PUT, and explore various ways to define your APIs.<\/p>\n

\u57285.2 \u4e2d\u8282\uff0c\u9996\u5148\u6269\u5c55\u4e86\u60a8\u5df2\u7ecf\u89c1\u8fc7\u7684\u6700\u5c0f API \u5e94\u7528\u7a0b\u5e8f\u3002\u60a8\u5c06\u63a2\u7d22\u4e00\u4e9b\u57fa\u672c\u7684\u8def\u7531\u6982\u5ff5\uff0c\u5e76\u5c55\u793a\u5982\u4f55\u4ece URL \u4e2d\u81ea\u52a8\u63d0\u53d6\u503c\u3002\u7136\u540e\uff0c\u60a8\u5c06\u5b66\u4e60\u5982\u4f55\u5904\u7406\u5176\u4ed6 HTTP \u52a8\u8bcd\uff08\u5982 POST \u548c PUT\uff09\uff0c\u5e76\u63a2\u7d22\u5b9a\u4e49 API \u7684\u5404\u79cd\u65b9\u6cd5\u3002<\/p>\n

In section 5.3 you\u2019ll learn about the different return types you can use with minimal APIs. You\u2019ll see how to use the Results and TypedResults helper classes to easily create HTTP responses that use status codes like 201 Created and 404 Not Found. You\u2019ll also learn how to follow web standards for describing your errors by using the built-in support for Problem Details.<\/p>\n

\u57285.3 \u4e2d\u8282\uff0c\u60a8\u5c06\u4e86\u89e3\u53ef\u4ee5\u4e0e\u6700\u5c11\u7684 API \u4e00\u8d77\u4f7f\u7528\u7684\u4e0d\u540c\u8fd4\u56de\u7c7b\u578b\u3002\u60a8\u5c06\u770b\u5230\u5982\u4f55\u4f7f\u7528Results \u548c TypedResults \u5e2e\u52a9\u7a0b\u5e8f\u7c7b\u8f7b\u677e\u521b\u5efa\u4f7f\u7528\u72b6\u6001\u4ee3\u7801\uff08\u5982 201 Created \u548c 404 Not Found\uff09\u7684 HTTP \u54cd\u5e94\u3002\u60a8\u8fd8\u5c06\u5b66\u4e60\u5982\u4f55\u4f7f\u7528\u5bf9 Problem Details \u7684\u5185\u7f6e\u652f\u6301\u6765\u9075\u5faa Web \u6807\u51c6\u6765\u63cf\u8ff0\u9519\u8bef\u3002<\/p>\n

Section 5.4 introduces one of the big features added to minimal APIs in .NET 7: filters. You can use filters to build a mini pipeline (similar to the middleware pipeline from chapter 4) for each of your endpoints. Like middleware, filters are great for extracting common code from your endpoint handlers, making your handlers easier to read.<\/p>\n

\u57285.3 \u4e2d\u8282\uff0c\u4ecb\u7ecd\u4e86 .NET 7 \u4e2d\u6dfb\u52a0\u5230\u6700\u5c0f API \u7684\u91cd\u8981\u529f\u80fd\u4e4b\u4e00\uff1a\u8fc7\u6ee4\u5668\u3002\u60a8\u53ef\u4ee5\u4f7f\u7528\u8fc7\u6ee4\u5668\u4e3a\u6bcf\u4e2a\u7ec8\u7aef\u8282\u70b9\u6784\u5efa\u4e00\u4e2a\u5fae\u578b\u7ba1\u9053\uff08\u7c7b\u4f3c\u4e8e\u7b2c 4 \u7ae0\u4e2d\u7684\u4e2d\u95f4\u4ef6\u7ba1\u9053\uff09\u3002\u4e0e\u4e2d\u95f4\u4ef6\u4e00\u6837\uff0c\u7b5b\u9009\u5668\u975e\u5e38\u9002\u5408\u4ece\u7ec8\u7ed3\u70b9\u5904\u7406\u7a0b\u5e8f\u4e2d\u63d0\u53d6\u5e38\u89c1\u4ee3\u7801\uff0c\u4ece\u800c\u4f7f\u5904\u7406\u7a0b\u5e8f\u66f4\u6613\u4e8e\u9605\u8bfb\u3002<\/p>\n

You\u2019ll learn about the other big .NET 7 feature for minimal APIs in section 5.5: route groups. You can use route groups to reduce the duplication in your minimal APIs, extracting common routing prefixes and filters, making your APIs easier to read, and reducing boilerplate. In conjunction with filters, route groups address many of the common complaints raised against minimal APIs when they were released in .NET 6.<\/p>\n

\u60a8\u5c06\u5728 5.5\uff1a\u8def\u7531\u7ec4 \u90e8\u5206\u4e86\u89e3\u6700\u5c0f API \u7684\u5176\u4ed6\u91cd\u8981 .NET 7 \u529f\u80fd\u3002\u60a8\u53ef\u4ee5\u4f7f\u7528\u8def\u7531\u7ec4\u6765\u51cf\u5c11\u6700\u5c0f API \u4e2d\u7684\u91cd\u590d\uff0c\u63d0\u53d6\u5e38\u89c1\u7684\u8def\u7531\u524d\u7f00\u548c\u7b5b\u9009\u6761\u4ef6\uff0c\u4f7f\u60a8\u7684 API \u66f4\u6613\u4e8e\u9605\u8bfb\uff0c\u5e76\u51cf\u5c11\u6837\u677f\u6587\u4ef6\u3002\u4e0e\u7b5b\u9009\u5668\u7ed3\u5408\u4f7f\u7528\uff0c\u8def\u7531\u7ec4\u53ef\u4ee5\u89e3\u51b3\u5728 .NET 6 \u4e2d\u53d1\u5e03\u6700\u5c0f API \u65f6\u9488\u5bf9\u6700\u5c0f API \u63d0\u51fa\u7684\u8bb8\u591a\u5e38\u89c1\u6295\u8bc9\u3002<\/p>\n

One great aspect of ASP.NET Core is the variety of applications you can create with it. The ability to easily build a generalized HTTP API presents the possibility of using ASP.NET Core in a greater range of situations than can be achieved with traditional web apps alone. But should you build an HTTP API, and if so, why? In the first section of this chapter, I\u2019ll go over some of the reasons why you may\u2014or may not\u2014want to create a web API.<\/p>\n

ASP.NET Core \u7684\u4e00\u4e2a\u91cd\u8981\u65b9\u9762\u662f\u60a8\u53ef\u4ee5\u4f7f\u7528\u5b83\u521b\u5efa\u7684\u5404\u79cd\u5e94\u7528\u7a0b\u5e8f\u3002\u4e0e\u5355\u72ec\u4f7f\u7528\u4f20\u7edf Web \u5e94\u7528\u7a0b\u5e8f\u76f8\u6bd4\uff0c\u8f7b\u677e\u6784\u5efa\u901a\u7528 HTTP API \u7684\u80fd\u529b\u4e3a\u5728\u66f4\u5927\u8303\u56f4\u5185\u4f7f\u7528 ASP.NET Core \u63d0\u4f9b\u4e86\u53ef\u80fd\u6027\u3002\u4f46\u662f\uff0c\u60a8\u5e94\u8be5\u6784\u5efa HTTP API\uff0c\u5982\u679c\u662f\u8fd9\u6837\uff0c\u4e3a\u4ec0\u4e48\uff1f\u5728\u672c\u7ae0\u7684\u7b2c\u4e00\u90e8\u5206\u4e2d\uff0c\u6211\u5c06\u4ecb\u7ecd\u60a8\u53ef\u80fd\u5e0c\u671b\uff08\u4e5f\u53ef\u80fd\u4e0d\u5e0c\u671b\uff09\u521b\u5efa Web API \u7684\u4e00\u4e9b\u539f\u56e0\u3002<\/p>\n

5.1 What is an HTTP API, and when should you use one?<\/h2>\n

5.1 \u4ec0\u4e48\u662f HTTP API\uff0c\u4f55\u65f6\u5e94\u4f7f\u7528 HTTP API\uff1f<\/h2>\n

Traditional web applications handle requests by returning HTML, which is displayed to the user in a web browser. You can easily build applications like that by using Razor Pages to generate HTML with Razor templates, as you\u2019ll learn in part 2 of this book. This approach is common and well understood, but the modern application developer has other possibilities to consider (figure 5.1), as you first saw in chapter 2.
\n\u4f20\u7edf\u7684 Web \u5e94\u7528\u7a0b\u5e8f\u901a\u8fc7\u8fd4\u56de HTML \u6765\u5904\u7406\u8bf7\u6c42\uff0cHTML \u5728 Web \u6d4f\u89c8\u5668\u4e2d\u663e\u793a\u7ed9\u7528\u6237\u3002\u901a\u8fc7\u4f7f\u7528 Razor Pages \u901a\u8fc7 Razor \u6a21\u677f\u751f\u6210 HTML\uff0c\u53ef\u4ee5\u8f7b\u677e\u6784\u5efa\u6b64\u7c7b\u5e94\u7528\u7a0b\u5e8f\uff0c\u60a8\u5c06\u5728\u672c\u4e66\u7684\u7b2c 2 \u90e8\u5206\u4e2d\u5b66\u4e60\u3002\u8fd9\u79cd\u65b9\u6cd5\u5f88\u5e38\u89c1\uff0c\u4e5f\u5f88\u5bb9\u6613\u7406\u89e3\uff0c\u4f46\u73b0\u4ee3\u5e94\u7528\u7a0b\u5e8f\u5f00\u53d1\u4eba\u5458\u8fd8\u6709\u5176\u4ed6\u53ef\u80fd\u6027\u9700\u8981\u8003\u8651\uff08\u56fe 5.1\uff09\uff0c\u6b63\u5982\u60a8\u5728\u7b2c 2 \u7ae0\u4e2d\u7b2c\u4e00\u6b21\u770b\u5230\u7684\u90a3\u6837\u3002<\/p>\n

\"alt<\/p>\n

Figure 5.1 Modern developers have to consider several consumers of their applications. As well as traditional users with web browsers, these users could be single-page applications, mobile applications, or other apps.
\n\u56fe 5.1 \u73b0\u4ee3\u5f00\u53d1\u4eba\u5458\u5fc5\u987b\u8003\u8651\u5176\u5e94\u7528\u7a0b\u5e8f\u7684\u591a\u4e2a\u4f7f\u7528\u8005\u3002\u9664\u4e86\u4f7f\u7528 Web \u6d4f\u89c8\u5668\u7684\u4f20\u7edf\u7528\u6237\u5916\uff0c\u8fd9\u4e9b\u7528\u6237\u8fd8\u53ef\u4ee5\u662f\u5355\u9875\u5e94\u7528\u7a0b\u5e8f\u3001\u79fb\u52a8\u5e94\u7528\u7a0b\u5e8f\u6216\u5176\u4ed6\u5e94\u7528\u7a0b\u5e8f\u3002<\/p>\n

Client-side single-page applications (SPAs) have become popular in recent years with the development of frameworks such as Angular, React, and Vue. These frameworks typically use JavaScript running in a web browser to generate the HTML that users see and interact with. The server sends this initial JavaScript to the browser when the user first reaches the app. The user\u2019s browser loads the JavaScript and initializes the SPA before loading any application data from the server.<\/p>\n

\u8fd1\u5e74\u6765\uff0c\u968f\u7740 Angular\u3001React \u548c Vue \u7b49\u6846\u67b6\u7684\u53d1\u5c55\uff0c\u5ba2\u6237\u7aef\u5355\u9875\u5e94\u7528\u7a0b\u5e8f \uff08SPA\uff09 \u53d8\u5f97\u6d41\u884c\u8d77\u6765\u3002\u8fd9\u4e9b\u6846\u67b6\u901a\u5e38\u4f7f\u7528\u5728 Web \u6d4f\u89c8\u5668\u4e2d\u8fd0\u884c\u7684 JavaScript \u6765\u751f\u6210\u7528\u6237\u770b\u5230\u5e76\u4e0e\u4e4b\u4ea4\u4e92\u7684 HTML\u3002\u5f53\u7528\u6237\u9996\u6b21\u8bbf\u95ee\u5e94\u7528\u7a0b\u5e8f\u65f6\uff0c\u670d\u52a1\u5668\u4f1a\u5c06\u6b64\u521d\u59cb JavaScript \u53d1\u9001\u5230\u6d4f\u89c8\u5668\u3002\u7528\u6237\u7684\u6d4f\u89c8\u5668\u5728\u4ece\u670d\u52a1\u5668\u52a0\u8f7d\u4efb\u4f55\u5e94\u7528\u7a0b\u5e8f\u6570\u636e\u4e4b\u524d\u52a0\u8f7d JavaScript \u5e76\u521d\u59cb\u5316 SPA\u3002<\/p>\n

NOTE<\/b> Blazor WebAssembly is an exciting new SPA framework. Blazor lets you write an SPA that runs in the browser like other SPAs, but it uses C# and Razor templates instead of JavaScript by using the new web standard, WebAssembly. I don\u2019t cover Blazor in this book, so to find out more, I recommend Blazor in Action, by Chris Sainty (Manning, 2022).<\/p>\n

\u6ce8\u610f\uff1aBlazor WebAssembly \u662f\u4e00\u4e2a\u4ee4\u4eba\u5174\u594b\u7684\u65b0 SPA \u6846\u67b6\u3002Blazor \u5141\u8bb8\u60a8\u7f16\u5199\u4e00\u4e2a\u5728\u6d4f\u89c8\u5668\uff0c\u4f46\u5b83\u4f7f\u7528\u65b0\u7684 Web \u6807\u51c6 WebAssembly \u4f7f\u7528 C# \u548c Razor \u6a21\u677f\uff0c\u800c\u4e0d\u662f JavaScript\u3002\u6211\u5728\u8fd9\u672c\u4e66\u4e2d\u6ca1\u6709\u4ecb\u7ecd Blazor\uff0c\u56e0\u6b64\u8981\u4e86\u89e3\u66f4\u591a\u4fe1\u606f\uff0c\u6211\u63a8\u8350 Chris Sainty \u7684 Blazor in Action\uff08\u66fc\u5b81\uff0c2022 \u5e74\uff09\u3002<\/p>\n

Once the SPA is loaded in the browser, communication with a server still occurs over HTTP, but instead of sending HTML directly to the browser in response to requests, the server-side application sends data\u2014normally, in the ubiquitous JavaScript Object Notation (JSON) format\u2014to the client-side application. Then the SPA parses the data and generates the appropriate HTML to show to a user, as shown in figure 5.2. The server-side application endpoint that the client communicates with is sometimes called an HTTP API, a JSON API, or a REST API, depending on the specifics of the API\u2019s design.<\/p>\n

\u5728\u6d4f\u89c8\u5668\u4e2d\u52a0\u8f7d SPA \u540e\uff0c\u4e0e\u670d\u52a1\u5668\u7684\u901a\u4fe1\u4ecd\u901a\u8fc7 HTTP \u8fdb\u884c\uff0c\u4f46\u670d\u52a1\u5668\u7aef\u5e94\u7528\u7a0b\u5e8f\u4e0d\u662f\u76f4\u63a5\u5411\u6d4f\u89c8\u5668\u53d1\u9001 HTML \u4ee5\u54cd\u5e94\u8bf7\u6c42\uff0c\u800c\u662f\u5c06\u6570\u636e\uff08\u901a\u5e38\u4ee5\u65e0\u5904\u4e0d\u5728\u7684 JavaScript \u5bf9\u8c61\u8868\u793a\u6cd5 \uff08JSON\uff09 \u683c\u5f0f\uff09\u53d1\u9001\u5230\u5ba2\u6237\u7aef\u5e94\u7528\u7a0b\u5e8f\u3002\u7136\u540e\uff0cSPA \u89e3\u6790\u6570\u636e\u5e76\u751f\u6210\u76f8\u5e94\u7684 HTML \u4ee5\u5411\u7528\u6237\u663e\u793a\uff0c\u5982\u56fe 5.2 \u6240\u793a\u3002\u5ba2\u6237\u7aef\u4e0e\u4e4b\u901a\u4fe1\u7684\u670d\u52a1\u5668\u7aef\u5e94\u7528\u7a0b\u5e8f\u7ec8\u7aef\u8282\u70b9\u6709\u65f6\u79f0\u4e3a HTTP API\u3001JSON API \u6216 REST API\uff0c\u5177\u4f53\u53d6\u51b3\u4e8e API \u8bbe\u8ba1\u7684\u5177\u4f53\u60c5\u51b5\u3002<\/p>\n

\"alt<\/p>\n

Figure 5.2 A sample client-side SPA using Blazor WebAssembly. The initial requests load the SPA files into the browser, and subsequent requests fetch data from a web API, formatted as JSON.
\n\u56fe 5.2 \u4f7f\u7528 Blazor WebAssembly \u7684\u5ba2\u6237\u7aef SPA \u793a\u4f8b\u3002\u521d\u59cb\u8bf7\u6c42\u5c06 SPA \u6587\u4ef6\u52a0\u8f7d\u5230\u6d4f\u89c8\u5668\u4e2d\uff0c\u540e\u7eed\u8bf7\u6c42\u4ece Web API \u83b7\u53d6\u6570\u636e\uff0c\u683c\u5f0f\u4e3a JSON\u3002<\/p>\n

DEFINITION<\/b> An HTTP API exposes multiple URLs via HTTP that can be used to access or change data on a server. It typically returns data using the JSON format. HTTP APIs are sometimes called web APIs, but as web API refers to a specific technology in ASP.NET Core, in this book I use HTTP API to refer to the generic concept.
\n\u5b9a\u4e49\uff1a HTTP API \u901a\u8fc7 HTTP \u516c\u5f00\u591a\u4e2a URL\uff0c\u53ef\u7528\u4e8e\u8bbf\u95ee\u6216\u66f4\u6539\u670d\u52a1\u5668\u4e0a\u7684\u6570\u636e\u3002\u5b83\u901a\u5e38\u4f7f\u7528 JSON \u683c\u5f0f\u8fd4\u56de\u6570\u636e\u3002HTTP API \u6709\u65f6\u4e5f\u79f0\u4e3a Web API\uff0c\u4f46\u7531\u4e8e Web API \u6307\u7684\u662f ASP.NET Core \u4e2d\u7684\u7279\u5b9a\u6280\u672f\uff0c\u56e0\u6b64\u5728\u672c\u4e66\u4e2d\uff0c\u6211\u4f7f\u7528 HTTP API \u6765\u6307\u4ee3\u901a\u7528\u6982\u5ff5\u3002<\/p>\n

These days, mobile applications are common and, from the server application\u2019s point of view, similar to client-side SPAs. A mobile application typically communicates with a server application by using an HTTP API, receiving data in JSON format, just like an SPA. Then it modifies the application\u2019s UI depending on the data it receives.<\/p>\n

\u5982\u4eca\uff0c\u79fb\u52a8\u5e94\u7528\u7a0b\u5e8f\u5f88\u5e38\u89c1\uff0c\u4ece\u670d\u52a1\u5668\u5e94\u7528\u7a0b\u5e8f\u7684\u89d2\u5ea6\u6765\u770b\uff0c\u5b83\u7c7b\u4f3c\u4e8e\u5ba2\u6237\u7aef SPA\u3002\u79fb\u52a8\u5e94\u7528\u7a0b\u5e8f\u901a\u5e38\u4f7f\u7528 HTTP API \u4e0e\u670d\u52a1\u5668\u5e94\u7528\u7a0b\u5e8f\u901a\u4fe1\uff0c\u4ee5 JSON \u683c\u5f0f\u63a5\u6536\u6570\u636e\uff0c\u5c31\u50cf SPA \u4e00\u6837\u3002\u7136\u540e\uff0c\u5b83\u6839\u636e\u63a5\u6536\u5230\u7684\u6570\u636e\u4fee\u6539\u5e94\u7528\u7a0b\u5e8f\u7684 UI\u3002<\/p>\n

One final use case for an HTTP API is where your application is designed to be partially or solely consumed by other backend services. Imagine that you\u2019ve built a web application to send emails. By creating an HTTP API, you can allow other application developers to use your email service by sending you an email address and a message. Virtually all languages and platforms have access to an HTTP library they could use to access your service from code.<\/p>\n

HTTP API \u7684\u6700\u540e\u4e00\u4e2a\u7528\u4f8b\u662f\uff0c\u60a8\u7684\u5e94\u7528\u7a0b\u5e8f\u88ab\u8bbe\u8ba1\u4e3a\u90e8\u5206\u6216\u5168\u90e8\u7531\u5176\u4ed6\u540e\u7aef\u670d\u52a1\u4f7f\u7528\u3002\u5047\u8bbe\u60a8\u5df2\u7ecf\u6784\u5efa\u4e86\u4e00\u4e2a\u7528\u4e8e\u53d1\u9001\u7535\u5b50\u90ae\u4ef6\u7684 Web \u5e94\u7528\u7a0b\u5e8f\u3002\u901a\u8fc7\u521b\u5efa HTTP API\uff0c\u60a8\u53ef\u4ee5\u5141\u8bb8\u5176\u4ed6\u5e94\u7528\u7a0b\u5e8f\u5f00\u53d1\u4eba\u5458\u901a\u8fc7\u5411\u60a8\u53d1\u9001\u7535\u5b50\u90ae\u4ef6\u5730\u5740\u548c\u6d88\u606f\u6765\u4f7f\u7528\u60a8\u7684\u7535\u5b50\u90ae\u4ef6\u670d\u52a1\u3002\u51e0\u4e4e\u6240\u6709\u8bed\u8a00\u548c\u5e73\u53f0\u90fd\u53ef\u4ee5\u8bbf\u95ee HTTP \u5e93\uff0c\u5b83\u4eec\u53ef\u4ee5\u4f7f\u7528\u8be5\u5e93\u4ece\u4ee3\u7801\u8bbf\u95ee\u60a8\u7684\u670d\u52a1\u3002<\/p>\n

That\u2019s all there is to an HTTP API: it exposes endpoints (URLs) that client applications can send requests to and retrieve data from. These endpoints are used to power the behavior of the client apps, as well as to provide all the data the client apps need to display the correct interface to a user.<\/p>\n

\u8fd9\u5c31\u662f HTTP API \u7684\u5168\u90e8\u5185\u5bb9\uff1a\u5b83\u516c\u5f00\u4e86\u5ba2\u6237\u7aef\u5e94\u7528\u7a0b\u5e8f\u53ef\u4ee5\u5411\u5176\u53d1\u9001\u8bf7\u6c42\u548c\u68c0\u7d22\u6570\u636e\u7684\u7aef\u70b9 \uff08URL\uff09\u3002\u8fd9\u4e9b\u7aef\u70b9\u7528\u4e8e\u652f\u6301\u5ba2\u6237\u7aef\u5e94\u7528\u7a0b\u5e8f\u7684\u884c\u4e3a\uff0c\u4ee5\u53ca\u63d0\u4f9b\u5ba2\u6237\u7aef\u5e94\u7528\u7a0b\u5e8f\u5411\u7528\u6237\u663e\u793a\u6b63\u786e\u754c\u9762\u6240\u9700\u7684\u6240\u6709\u6570\u636e\u3002<\/p>\n

NOTE<\/b> You have even more options when it comes to creating APIs in ASP.NET Core. You can create remote procedure call APIs using gRPC, for example, or provide an alternative style of HTTP API using the GraphQL standard. I don\u2019t cover those technologies in this book, but you can read about gRPC at https:\/\/docs.microsoft.com\/aspnet\/core\/grpc<\/a> and find out about GraphQL in Building Web APIs with ASP.NET Core, by Valerio De Sanctis (Manning, 2023).
\n\u6ce8\u610f\uff1a\u5728 ASP.NET Core \u4e2d\u521b\u5efa API \u65f6\uff0c\u60a8\u6709\u66f4\u591a\u9009\u62e9\u3002\u4f8b\u5982\uff0c\u60a8\u53ef\u4ee5\u4f7f\u7528 gRPC \u521b\u5efa\u8fdc\u7a0b\u8fc7\u7a0b\u8c03\u7528 API\uff0c\u6216\u4f7f\u7528 GraphQL \u6807\u51c6\u63d0\u4f9b HTTP API \u7684\u66ff\u4ee3\u6837\u5f0f\u3002\u6211\u4e0d\u4f1a\u5728\u672c\u4e66\u4e2d\u4ecb\u7ecd\u8fd9\u4e9b\u6280\u672f\uff0c\u4f46\u60a8\u53ef\u4ee5\u5728 https:\/\/docs.microsoft.com\/aspnet\/core\/grpc<\/a> \u9605\u8bfb\u6709\u5173 gRPC \u7684\u4fe1\u606f \uff0c\u5e76\u5728 Valerio De Sanctis\uff08Manning\uff0c2023 \u5e74\uff09\u64b0\u5199\u7684\u4f7f\u7528 ASP.NET Core \u6784\u5efa Web API \u4e2d\u4e86\u89e3 GraphQL\u3002<\/p>\n

Whether you need or want to create an HTTP API for your ASP.NET Core application depends on the type of application you want to build. Perhaps you\u2019re familiar with client-side frameworks, or maybe you need to develop a mobile application, or you already have an SPA build pipeline configured. In each case, you\u2019ll most likely want to add HTTP APIs for the client apps to access your application.<\/p>\n

\u60a8\u662f\u5426\u9700\u8981\u6216\u60f3\u8981\u4e3a ASP.NET Core \u5e94\u7528\u7a0b\u5e8f\u521b\u5efa HTTP API \u53d6\u51b3\u4e8e\u8981\u6784\u5efa\u7684\u5e94\u7528\u7a0b\u5e8f\u7c7b\u578b\u3002\u4e5f\u8bb8\u60a8\u719f\u6089\u5ba2\u6237\u7aef\u6846\u67b6\uff0c\u6216\u8005\u60a8\u9700\u8981\u5f00\u53d1\u79fb\u52a8\u5e94\u7528\u7a0b\u5e8f\uff0c\u6216\u8005\u60a8\u5df2\u7ecf\u914d\u7f6e\u4e86 SPA \u6784\u5efa\u7ba1\u9053\u3002\u5728\u6bcf\u79cd\u60c5\u51b5\u4e0b\uff0c\u60a8\u5f88\u53ef\u80fd\u5e0c\u671b\u4e3a\u5ba2\u6237\u7aef\u5e94\u7528\u7a0b\u5e8f\u6dfb\u52a0 HTTP API \u4ee5\u8bbf\u95ee\u60a8\u7684\u5e94\u7528\u7a0b\u5e8f\u3002<\/p>\n

One selling point for using an HTTP API is that it can serve as a generalized backend for all your client applications. You could start by building a client-side application that uses an HTTP API. Later, you could add a mobile app that uses the same HTTP API, making little or no modification to your ASP.NET Core code.<\/p>\n

\u4f7f\u7528 HTTP API \u7684\u4e00\u4e2a\u5356\u70b9\u662f\u5b83\u53ef\u4ee5\u7528\u4f5c\u6240\u6709\u5ba2\u6237\u7aef\u5e94\u7528\u7a0b\u5e8f\u7684\u901a\u7528\u540e\u7aef\u3002\u60a8\u53ef\u4ee5\u4ece\u6784\u5efa\u4f7f\u7528 HTTP API \u7684\u5ba2\u6237\u7aef\u5e94\u7528\u7a0b\u5e8f\u5f00\u59cb\u3002\u7a0d\u540e\uff0c\u60a8\u53ef\u4ee5\u6dfb\u52a0\u4f7f\u7528\u76f8\u540c HTTP API \u7684\u79fb\u52a8\u5e94\u7528\u7a0b\u5e8f\uff0c\u5bf9 ASP.NET Core \u4ee3\u7801\u8fdb\u884c\u5c11\u91cf\u4fee\u6539\u6216\u4e0d\u8fdb\u884c\u4fee\u6539\u3002<\/p>\n

If you\u2019re new to web development, HTTP APIs can also be easier to understand initially, as they typically return only JSON. Part 1 of this book focuses on minimal APIs so that you can focus on the mechanics of ASP.NET Core without needing to write HTML or CSS.<\/p>\n

\u5982\u679c\u60a8\u4e0d\u719f\u6089 Web \u5f00\u53d1\uff0cHTTP API \u6700\u521d\u4e5f\u66f4\u5bb9\u6613\u7406\u89e3\uff0c\u56e0\u4e3a\u5b83\u4eec\u901a\u5e38\u53ea\u8fd4\u56de JSON\u3002\u672c\u4e66\u7684\u7b2c 1 \u90e8\u5206\u91cd\u70b9\u4ecb\u7ecd\u6700\u5c11\u7684 API\uff0c\u4ee5\u4fbf\u60a8\u53ef\u4ee5\u4e13\u6ce8\u4e8e ASP.NET Core \u7684\u673a\u5236\uff0c\u800c\u65e0\u9700\u7f16\u5199 HTML \u6216 CSS\u3002<\/p>\n

In part 3, you\u2019ll learn how to use Razor Pages to create server-rendered applications instead of minimal APIs. Server-rendered applications can be highly productive. They\u2019re generally recommended when you have no need to call your application from outside a web browser or when you don\u2019t want or need to make the effort of configuring a client-side application.<\/p>\n

\u5728\u7b2c 3 \u90e8\u5206\u4e2d\uff0c\u60a8\u5c06\u5b66\u4e60\u5982\u4f55\u4f7f\u7528 Razor Pages \u521b\u5efa\u670d\u52a1\u5668\u5448\u73b0\u7684\u5e94\u7528\u7a0b\u5e8f\uff0c\u800c\u4e0d\u662f\u6700\u5c11\u7684 API\u3002\u670d\u52a1\u5668\u6e32\u67d3\u7684\u5e94\u7528\u7a0b\u5e8f\u53ef\u4ee5\u975e\u5e38\u9ad8\u6548\u3002\u5f53\u60a8\u4e0d\u9700\u8981\u4ece Web \u6d4f\u89c8\u5668\u5916\u90e8\u8c03\u7528\u5e94\u7528\u7a0b\u5e8f\uff0c\u6216\u8005\u5f53\u60a8\u4e0d\u60f3\u6216\u4e0d\u9700\u8981\u914d\u7f6e\u5ba2\u6237\u7aef\u5e94\u7528\u7a0b\u5e8f\u65f6\uff0c\u901a\u5e38\u5efa\u8bae\u4f7f\u7528\u5b83\u4eec\u3002<\/p>\n

NOTE<\/b> Although there\u2019s been an industry shift toward client-side frameworks, server-side rendering using Razor is still relevant. Which approach you choose depends largely on your preference for building HTML applications in the traditional manner versus using JavaScript (or Blazor!) on the client.
\n\u6ce8\u610f\uff1a \u5c3d\u7ba1\u884c\u4e1a\u5df2\u7ecf\u8f6c\u5411\u5ba2\u6237\u7aef\u6846\u67b6\uff0c\u4f46\u4f7f\u7528 Razor \u7684\u670d\u52a1\u5668\u7aef\u6e32\u67d3\u4ecd\u7136\u5f88\u91cd\u8981\u3002\u9009\u62e9\u54ea\u79cd\u65b9\u6cd5\u5728\u5f88\u5927\u7a0b\u5ea6\u4e0a\u53d6\u51b3\u4e8e\u60a8\u5728\u4f20\u7edf\u65b9\u5f0f\u4e0e\u5728\u5ba2\u6237\u7aef\u4e0a\u4f7f\u7528 JavaScript\uff08\u6216 Blazor\uff09\u7684\u6bd4\u8f83\u3002<\/p>\n

Having said that, whether to use HTTP APIs in your application isn\u2019t something you necessarily have to worry about ahead of time. You can always add them to an ASP.NET Core app later in development, as the need arises.<\/p>\n

\u8bdd\u867d\u5982\u6b64\uff0c\u662f\u5426\u5728\u5e94\u7528\u7a0b\u5e8f\u4e2d\u4f7f\u7528 HTTP API \u5e76\u4e0d\u662f\u60a8\u5fc5\u987b\u63d0\u524d\u62c5\u5fc3\u7684\u4e8b\u60c5\u3002\u60a8\u59cb\u7ec8\u53ef\u4ee5\u5728\u4ee5\u540e\u7684\u5f00\u53d1\u8fc7\u7a0b\u4e2d\u6839\u636e\u9700\u8981\u5c06\u5b83\u4eec\u6dfb\u52a0\u5230 ASP.NET Core \u5e94\u7528\u7a0b\u5e8f\u4e2d\u3002<\/p>\n

\n

SPAs with ASP.NET Core
\n\u5177\u6709 ASP.NET Core \u7684 SPA
\nThe cross-platform, lightweight design of ASP.NET Core means that it lends itself well to acting as a backend for your SPA framework of choice. Given the focus of this book and the broad scope of SPAs in general, I won\u2019t be looking at Angular, React, or other SPAs here. Instead, I suggest checking out the resources appropriate to your chosen SPA. Books are available from Manning for all the common client-side JavaScript frameworks, as well as Blazor:
\nASP.NET Core \u7684\u8de8\u5e73\u53f0\u8f7b\u91cf\u7ea7\u8bbe\u8ba1\u610f\u5473\u7740\u5b83\u975e\u5e38\u9002\u5408\u5145\u5f53\u6240\u9009 SPA \u6846\u67b6\u7684\u540e\u7aef\u3002\u9274\u4e8e\u672c\u4e66\u7684\u91cd\u70b9\u548c SPA \u7684\u5e7f\u6cdb\u8303\u56f4\uff0c\u6211\u4e0d\u4f1a\u5728\u8fd9\u91cc\u8ba8\u8bba Angular\u3001React \u6216\u5176\u4ed6 SPA\u3002\u76f8\u53cd\uff0c\u6211\u5efa\u8bae\u67e5\u770b\u9002\u7528\u4e8e\u60a8\u9009\u62e9\u7684 SPA \u7684\u8d44\u6e90\u3002Manning \u63d0\u4f9b\u4e86\u9002\u7528\u4e8e\u6240\u6709\u5e38\u89c1\u5ba2\u6237\u7aef JavaScript \u6846\u67b6\u4ee5\u53ca Blazor \u7684\u4e66\u7c4d\uff1a
\n\u00b7 React in Action, by Mark Tielens Thomas (Manning, 2018)
\nReact in Action\uff0c\u4f5c\u8005\uff1aMark Tielens Thomas\uff08\u66fc\u5b81\u51fa\u7248\u793e\uff0c2018 \u5e74\uff09
\n\u00b7 Angular in Action, by Jeremy Wilken (Manning, 2018)
\nAngular in Action\uff0c\u4f5c\u8005\uff1aJeremy Wilken\uff08\u66fc\u5b81\uff0c2018 \u5e74\uff09
\n\u00b7 Vue.js in Action, by Erik Hanchett with Benjamin Listwon (Manning, 2018)
\nVue.js in Action\uff0c\u57c3\u91cc\u514b\u00b7\u6c49\u5207\u7279 \uff08Erik Hanchett\uff09 \u548c\u672c\u6770\u660e\u00b7\u5229\u65af\u7279\u65fa \uff08Benjamin Listwon\uff09 \u8457\uff08\u66fc\u5b81\u51fa\u7248\u793e\uff0c2018 \u5e74\uff09
\n\u00b7 Blazor in Action, by Chris Sainty (Manning, 2022)
\nBlazor in Action\uff0c\u4f5c\u8005\uff1aChris Sainty\uff08\u66fc\u5b81\uff0c2022 \u5e74\uff09<\/p>\n<\/blockquote>\n

After you\u2019ve established that you need an HTTP API for your application, creating one is easy, as it\u2019s the default application type in ASP.NET Core! In the next section we look at various ways you can create minimal API endpoints and ways to handle multiple HTTP verbs.<\/p>\n

\u5728\u60a8\u786e\u5b9a\u5e94\u7528\u7a0b\u5e8f\u9700\u8981 HTTP API \u540e\uff0c\u521b\u5efa\u4e00\u4e2a API \u5f88\u5bb9\u6613\uff0c\u56e0\u4e3a\u5b83\u662f ASP.NET Core \u4e2d\u7684\u9ed8\u8ba4\u5e94\u7528\u7a0b\u5e8f\u7c7b\u578b\uff01\u5728\u4e0b\u4e00\u8282\u4e2d\uff0c\u6211\u4eec\u5c06\u4ecb\u7ecd\u521b\u5efa\u6700\u5c0f API \u7aef\u70b9\u7684\u5404\u79cd\u65b9\u6cd5\u4ee5\u53ca\u5904\u7406\u591a\u4e2a HTTP \u52a8\u8bcd\u7684\u65b9\u6cd5\u3002<\/p>\n

5.2 Defining minimal API endpoints<\/h2>\n

5.2 \u5b9a\u4e49\u6700\u5c0f API \u7aef\u70b9<\/h2>\n

Chapters 3 and 4 gave you an introduction to basic minimal API endpoints. In this section, we\u2019ll build on those basic apps to show how you can handle multiple HTTP verbs and explore various ways to write your endpoint handlers.<\/p>\n

\u7b2c 3 \u7ae0\u548c\u7b2c 4 \u7ae0\u4ecb\u7ecd\u4e86\u57fa\u672c\u7684\u6700\u5c0f API \u7aef\u70b9\u3002\u5728\u672c\u8282\u4e2d\uff0c\u6211\u4eec\u5c06\u4ee5\u8fd9\u4e9b\u57fa\u672c\u5e94\u7528\u7a0b\u5e8f\u4e3a\u57fa\u7840\uff0c\u5c55\u793a\u5982\u4f55\u5904\u7406\u591a\u4e2a HTTP \u52a8\u8bcd\uff0c\u5e76\u63a2\u7d22\u7f16\u5199\u7ec8\u7aef\u8282\u70b9\u5904\u7406\u7a0b\u5e8f\u7684\u5404\u79cd\u65b9\u6cd5\u3002<\/p>\n

5.2.1 Extracting values from the URL with routing<\/h2>\n

5.2.1 \u4f7f\u7528\u8def\u7531 \u4ece URL \u4e2d\u63d0\u53d6\u503c<\/h2>\n

You\u2019ve seen several minimal API applications in this book, but so far, all the examples have used fixed paths to define the APIs, as in this example:<\/p>\n

\u60a8\u5728\u672c\u4e66\u4e2d\u5df2\u7ecf\u770b\u5230\u4e86\u51e0\u4e2a\u6700\u5c0f\u7684 API \u5e94\u7528\u7a0b\u5e8f\uff0c\u4f46\u5230\u76ee\u524d\u4e3a\u6b62\uff0c\u6240\u6709\u793a\u4f8b\u90fd\u4f7f\u7528\u56fa\u5b9a\u8def\u5f84\u6765\u5b9a\u4e49 API\uff0c\u5982\u4ee5\u4e0b\u793a\u4f8b\u6240\u793a\uff1a<\/p>\n

app.MapGet("\/", () => "Hello World!");\napp.MapGet("\/person", () => new Person("Andrew", "Lock"));\n<\/pre>\n
These two APIs correspond to the paths \/ and \/person, respectively. This basic functionality is useful, but typically you need some of your APIs to be more dynamic. It\u2019s unlikely, for example, that the \/person API would be useful in practice, as it always returns the same Person object. What might be more useful is an API to which you can provide the user\u2019s first name, and the API returns all the users with that name.<\/p>\n
\u8fd9\u4e24\u4e2a API \u5206\u522b\u5bf9\u5e94\u4e8e\u8def\u5f84 \/ \u548c \/person\u3002\u6b64\u57fa\u672c\u529f\u80fd\u5f88\u6709\u7528\uff0c\u4f46\u901a\u5e38\u9700\u8981\u67d0\u4e9b API \u66f4\u52a0\u52a8\u6001\u3002\u4f8b\u5982\uff0c\/person API \u5728\u5b9e\u8df5\u4e2d\u4e0d\u592a\u53ef\u80fd\u6709\u7528\uff0c\u56e0\u4e3a\u5b83\u603b\u662f\u8fd4\u56de\u76f8\u540c\u7684 Person \u5bf9\u8c61\u3002\u53ef\u80fd\u66f4\u6709\u7528\u7684\u662f API\uff0c\u60a8\u53ef\u4ee5\u5411\u5176\u63d0\u4f9b\u7528\u6237\u7684\u540d\u5b57\uff0c\u5e76\u4e14 API \u4f1a\u8fd4\u56de\u5177\u6709\u8be5\u540d\u79f0\u7684\u6240\u6709\u7528\u6237\u3002<\/p>\n
You can achieve this goal by using parameterized routes for your API definitions. You can create a parameter in a minimal API route using the expression {someValue}, where someValue is any name you choose. The value will be extracted from the request URL\u2019s path and can be used in the lambda function endpoint.<\/p>\n
\u60a8\u53ef\u4ee5\u901a\u8fc7\u5bf9 API \u5b9a\u4e49\u4f7f\u7528\u53c2\u6570\u5316\u8def\u7531\u6765\u5b9e\u73b0\u6b64\u76ee\u6807\u3002\u60a8\u53ef\u4ee5\u5728\u6700\u5c0f\u4f7f\u7528\u8868\u8fbe\u5f0f {someValue} \u7684 API \u8def\u7531\uff0c\u5176\u4e2d someValue \u662f\u60a8\u9009\u62e9\u7684\u4efb\u4f55\u540d\u79f0\u3002\u8be5\u503c\u5c06\u4ece\u8bf7\u6c42 URL \u7684\u8def\u5f84\u4e2d\u63d0\u53d6\uff0c\u5e76\u53ef\u5728 lambda \u51fd\u6570\u7ec8\u7aef\u8282\u70b9\u4e2d\u4f7f\u7528\u3002<\/p>\n
NOTE<\/b>  I introduce only the basics of extracting values from routes in this chapter. You\u2019ll learn a lot more about routing in chapter 6, including why we use routing and how it fits into the ASP.NET Core pipeline, as well as the syntax you can use.
\n\u6ce8\u610f\uff1a \u5728\u672c\u7ae0\u4e2d\uff0c\u6211\u53ea\u4ecb\u7ecd\u4e86\u4ece routes \u4e2d\u63d0\u53d6\u503c\u7684\u57fa\u7840\u77e5\u8bc6\u3002\u5728\u7b2c 6 \u7ae0\u4e2d\uff0c\u60a8\u5c06\u4e86\u89e3\u6709\u5173 routing \u7684\u66f4\u591a\u4fe1\u606f\uff0c\u5305\u62ec\u6211\u4eec\u4e3a\u4ec0\u4e48\u4f7f\u7528 routing\u3001\u5b83\u5982\u4f55\u9002\u5e94 ASP.NET Core \u7ba1\u9053\uff0c\u4ee5\u53ca\u60a8\u53ef\u4ee5\u4f7f\u7528\u7684\u8bed\u6cd5\u3002<\/p>\n
If you create an API using the route template \/person\/{name}, for example, and send a request to the path \/person\/Andrew, the name parameter will have the value "Andrew". You can use this feature to build more useful APIs, such as the one shown in the following listing.<\/p>\n
\u5982\u679c\u60a8\u4f7f\u7528\u8def\u7531\u6a21\u677f\u521b\u5efa API \/person\/{name} \u5e76\u5411\u8def\u5f84 \/person\/Andrew \u53d1\u9001\u8bf7\u6c42\uff0c\u5219 name \u53c2\u6570\u5c06\u5177\u6709\u503c \u201cAndrew\u201d\u3002\u60a8\u53ef\u4ee5\u4f7f\u7528\u6b64\u529f\u80fd\u6765\u6784\u5efa\u66f4\u6709\u7528\u7684 API\uff0c\u4f8b\u5982\u4ee5\u4e0b\u6e05\u5355\u4e2d\u6240\u793a\u7684 API\u3002<\/p>\n
Listing 5.1 A minimal API that uses a value from the URL
\n\u6e05\u5355 5.1 \u4e00\u4e2a\u6700\u5c0f\u7684 API\uff0c\u5b83\u4f7f\u7528\u7f51\u5740<\/p>\n
\nWebApplicationBuilder builder = WebApplication.CreateBuilder(args);\nWebApplication app = builder.Build();\nvar people = new List<Person>                                    \/\/ \u2776\n{                                                                \/\/ \u2776\n    new("Tom", "Hanks"),                                         \/\/ \u2776\n    new("Denzel", "Washington"),                                 \/\/ \u2776\n    new("Leondardo", "DiCaprio"),                                \/\/ \u2776\n    new("Al", "Pacino"),                                         \/\/ \u2776\n    new("Morgan", "Freeman"),                                    \/\/ \u2776\n};                                                               \/\/ \u2776\napp.MapGet("\/person\/{name}", (string name) =>                    \/\/ \u2777\npeople.Where(p => p.FirstName.StartsWith(name)));                \/\/ \u2778\n\napp.Run();\n\npublic record Person(string FirstName, string LastName);\n<\/pre>\n
\u2776 Creates a list of people as the data for the API
\n\u521b\u5efa\u4eba\u5458\u5217\u8868\u4f5c\u4e3a API \u7684\u6570\u636e<\/p>\n
\u2777 The route is parameterized to extract the name from the URL.
\n\u8def\u7531\u53c2\u6570\u5316\u4ee5\u4ece URL \u4e2d\u63d0\u53d6\u540d\u79f0\u3002<\/p>\n
\u2778 The extracted value can be injected into the lambda handler.
\n\u63d0\u53d6\u7684\u503c\u53ef\u4ee5\u6ce8\u5165\u5230 lambda \u5904\u7406\u7a0b\u5e8f\u4e2d\u3002<\/p>\n
If you send a request to \/person\/Al for the app defined in listing 5.1, the name parameter will have the value "Al", and the API will return the following JSON:
\n\u5982\u679c\u60a8\u5411 \/person\/Al \u53d1\u9001\u5217\u8868 5.1 \u4e2d\u5b9a\u4e49\u7684\u5e94\u7528\u7a0b\u5e8f\u7684\u8bf7\u6c42\uff0c\u5219 name \u53c2\u6570\u7684\u503c\u5c06\u4e3a \u201cAl\u201d\uff0c\u5e76\u4e14 API \u5c06\u8fd4\u56de\u4ee5\u4e0b JSON\uff1a<\/p>\n
\n[{"firstName":"Al","lastName":"Pacino"}]\n<\/pre>\n
NOTE<\/b>  By default, minimal APIs serialize C# objects to JSON. You\u2019ll see how to return other types of results in section 5.3.
\n\u6ce8\u610f\uff1a \u9ed8\u8ba4\u60c5\u51b5\u4e0b\uff0c\u6700\u5c0f API \u5c06 C# \u5bf9\u8c61\u5e8f\u5217\u5316\u4e3a JSON\u3002\u60a8\u5c06\u5728 5.3 \u8282 \u4e2d\u770b\u5230\u5982\u4f55\u8fd4\u56de\u5176\u4ed6\u7c7b\u578b\u7684\u7ed3\u679c\u3002<\/p>\n
The ASP.NET Core routing system is quite powerful, and we\u2019ll explore it in more detail in chapter 6. But with this simple capability, you can already build more complex applications.
\nASP.NET Core \u8def\u7531\u7cfb\u7edf\u975e\u5e38\u5f3a\u5927\uff0c\u6211\u4eec\u5c06\u5728\u7b2c 6 \u7ae0\u4e2d\u66f4\u8be6\u7ec6\u5730\u63a2\u8ba8\u5b83\u3002\u4f46\u501f\u52a9\u8fd9\u4e2a\u7b80\u5355\u7684\u529f\u80fd\uff0c\u60a8\u5df2\u7ecf\u53ef\u4ee5\u6784\u5efa\u66f4\u590d\u6742\u7684\u5e94\u7528\u7a0b\u5e8f\u3002<\/p>\n
5.2.2 Mapping verbs to endpoints<\/h3>\n
5.2.2 \u5c06\u52a8\u8bcd\u6620\u5c04\u5230\u7aef\u70b9<\/h3>\n
So far in this book we\u2019ve defined all our minimal API endpoints by using the MapGet() function. This function matches requests that use the GET HTTP verb. GET is the most-used verb; it\u2019s what a browser uses when you enter a URL in the address bar of your browser or follow a link on a web page.<\/p>\n
\u5230\u76ee\u524d\u4e3a\u6b62\uff0c\u5728\u672c\u4e66\u4e2d\uff0c\u6211\u4eec\u5df2\u7ecf\u4f7f\u7528 MapGet\uff08\uff09 \u51fd\u6570\u5b9a\u4e49\u4e86\u6240\u6709\u6700\u5c0f API \u7aef\u70b9 \u3002\u6b64\u51fd\u6570\u5339\u914d\u4f7f\u7528 GET HTTP \u52a8\u8bcd\u7684\u8bf7\u6c42\u3002GET \u662f\u6700\u5e38\u7528\u7684\u52a8\u8bcd;\u5f53\u60a8\u5728\u6d4f\u89c8\u5668\u7684\u5730\u5740\u680f\u4e2d\u8f93\u5165 URL \u6216\u70b9\u51fb\u7f51\u9875\u4e0a\u7684\u94fe\u63a5\u65f6\uff0c\u6d4f\u89c8\u5668\u4f1a\u4f7f\u7528\u5b83\u3002<\/p>\n
You should use GET only to get data from the server, however. You should never use it to send data or to change data on the server. Instead, you should use an HTTP verb such as POST or DELETE. You generally can\u2019t use these verbs by navigating web pages in the browser, but they\u2019re easy to send from a client-side SPA or mobile app.<\/p>\n
\u4f46\u662f\uff0c\u60a8\u5e94\u8be5\u53ea\u4f7f\u7528 GET \u4ece\u670d\u52a1\u5668\u83b7\u53d6\u6570\u636e\u3002\u5207\u52ff\u4f7f\u7528\u5b83\u6765\u53d1\u9001\u6570\u636e\u6216\u66f4\u6539\u670d\u52a1\u5668\u4e0a\u7684\u6570\u636e\u3002 \u76f8\u53cd\uff0c\u60a8\u5e94\u8be5\u4f7f\u7528 HTTP \u52a8\u8bcd\uff0c\u4f8b\u5982 POST \u6216 DELETE\u3002\u60a8\u901a\u5e38\u4e0d\u80fd\u4f7f\u7528\u8fd9\u4e9b\u52a8\u8bcd\uff0c\u4f46\u5b83\u4eec\u5f88\u5bb9\u6613\u4ece\u5ba2\u6237\u7aef SPA \u6216\u79fb\u52a8\u5e94\u7528\u7a0b\u5e8f\u53d1\u9001\u3002<\/p>\n
TIP<\/b>  If you\u2019re new to web programming or are looking for a refresher, Mozilla Developer Network (MDN), maker of the Firefox web browser, has a good introduction to HTTP at http:\/\/mng.bz\/KeMK<\/a>.
\n\u63d0\u793a\uff1a \u5982\u679c\u60a8\u662f Web \u7f16\u7a0b\u7684\u65b0\u624b\u6216\u6b63\u5728\u5bfb\u627e\u590d\u4e60\u8005\uff0cFirefox Web \u6d4f\u89c8\u5668\u7684\u5236\u9020\u5546 Mozilla Developer Network \uff08MDN\uff09 \u5728 http:\/\/mng.bz\/KeMK<\/a> \u4e0a\u5bf9 HTTP \u8fdb\u884c\u4e86\u5f88\u597d\u7684\u4ecb\u7ecd\u3002<\/p>\n
In theory, each of the HTTP verbs has a well-defined purpose, but in practice, you may see apps that only ever use POST and GET. This is often fine for server-rendered applications like Razor Pages, as it\u2019s typically simpler, but if you\u2019re creating an API, I recommend that you use the HTTP verbs with the appropriate semantics wherever possible.<\/p>\n
\u7406\u8bba\u4e0a\uff0c\u6bcf\u4e2a HTTP \u52a8\u8bcd\u90fd\u6709\u4e00\u4e2a\u660e\u786e\u5b9a\u4e49\u7684\u7528\u9014\uff0c\u4f46\u5728\u5b9e\u8df5\u4e2d\uff0c\u60a8\u53ef\u80fd\u4f1a\u770b\u5230\u4ec5\u4f7f\u7528 POST \u548c GET \u7684\u5e94\u7528\u7a0b\u5e8f\u3002\u8fd9\u901a\u5e38\u9002\u7528\u4e8e\u670d\u52a1\u5668\u5448\u73b0\u7684\u5e94\u7528\u7a0b\u5e8f\uff08\u5982 Razor Pages\uff09\uff0c\u56e0\u4e3a\u5b83\u901a\u5e38\u66f4\u7b80\u5355\uff0c\u4f46\u5982\u679c\u60a8\u6b63\u5728\u521b\u5efa API\uff0c\u6211\u5efa\u8bae\u60a8\u5c3d\u53ef\u80fd\u4f7f\u7528\u5177\u6709\u9002\u5f53\u8bed\u4e49\u7684 HTTP \u52a8\u8bcd\u3002<\/p>\n
You can define endpoints for other verbs with minimal APIs by using the appropriate Map functions. To map a POST endpoint, for example, you\u2019d use MapPost(). Table 5.1 shows the minimal API Map<\/em> methods available, the corresponding HTTP verbs, and the typical semantic expectations of each verb on the types of operations that the API performs.<\/p>\n
\u60a8\u53ef\u4ee5\u4f7f\u7528\u9002\u5f53\u7684 Map \u51fd\u6570\uff0c\u4f7f\u7528\u6700\u5c11\u7684 API \u4e3a\u5176\u4ed6\u8c13\u8bcd\u5b9a\u4e49\u7aef\u70b9\u3002\u4f8b\u5982\uff0c\u8981\u6620\u5c04 POST \u7ec8\u7aef\u8282\u70b9\uff0c\u60a8\u53ef\u4ee5\u4f7f\u7528 MapPost\uff08\uff09\u3002\u8868 5.1 \u663e\u793a\u4e86\u53ef\u7528\u7684\u6700\u5c0f API Map<\/em> \u65b9\u6cd5\u3001\u76f8\u5e94\u7684 HTTP \u52a8\u8bcd\u4ee5\u53ca\u6bcf\u4e2a\u52a8\u8bcd\u5bf9 API \u6267\u884c\u7684\u4f5c\u7c7b\u578b\u7684\u5178\u578b\u8bed\u4e49\u671f\u671b\u3002<\/p>\n
Table 5.1 The minimal API map endpoints and the corresponding HTML verbs
\n\u8868 5.1 \u6700\u5c0f API \u6620\u5c04\u7aef\u70b9\u548c\u76f8\u5e94\u7684 HTML \u52a8\u8bcd<\/p>\n\n\n\n\n\n\n\n\n\n\n\n\n
Method<\/th>\nHTTP verb<\/th>\nExpected operation<\/th>\n<\/tr>\n<\/thead>\n
MapGet(path, handler)<\/td>\nGET<\/td>\nFetch data only; no modification of state. May be safe to cache. 
\u4ec5\u83b7\u53d6\u6570\u636e;\u4e0d\u4fee\u6539\u72b6\u6001\u3002\u53ef\u4ee5\u5b89\u5168\u5730\u7f13\u5b58\u3002<\/td>\n<\/tr>\n
MapPost(path, handler)<\/td>\nPOST<\/td>\nCreate a new resource. 
\u521b\u5efa\u65b0\u8d44\u6e90\u3002<\/td>\n<\/tr>\n
MapPut(path, handler)<\/td>\nPUT<\/td>\nCreate or replace an existing resource.
\u521b\u5efa\u6216\u66ff\u6362\u73b0\u6709\u8d44\u6e90\u3002<\/td>\n<\/tr>\n
MapDelete(path, handler)<\/td>\nDELETE<\/td>\nDelete the given resource.  
\u5220\u9664\u7ed9\u5b9a\u7684\u8d44\u6e90\u3002<\/td>\n<\/tr>\n
MapPatch(path, handler)<\/td>\nPATCH<\/td>\nModify the given resource. 
\u4fee\u6539\u7ed9\u5b9a\u7684\u8d44\u6e90\u3002<\/td>\n<\/tr>\n
MapMethods(path, methods,handler)<\/td>\nMultiple verbs<\/td>\nMultiple operations 
\u591a\u4e2a\u52a8\u4f5c<\/td>\n<\/tr>\n
Map(path, handler)<\/td>\nAll verbs<\/td>\nMultiple operations 
\u591a\u4e2a\u52a8\u4f5c<\/td>\n<\/tr>\n
MapFallback(handler)<\/td>\nAll verbs<\/td>\nUseful for SPA fallback routes 
\u5bf9 SPA \u56de\u9000\u8def\u7531\u5f88\u6709\u7528\u3002<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
RESTful applications (as described in chapter 2) typically stick close to these verb uses where possible, but some of the actual implementations can differ, and people can easily get caught up in pedantry. Generally, if you stick to the expected operations described in table 5.1, you\u2019ll create a more understandable interface for consumers of the API.<\/p>\n
RESTful \u5e94\u7528\u7a0b\u5e8f\uff08\u5982\u7b2c 2 \u7ae0\u6240\u8ff0\uff09\u901a\u5e38\u5c3d\u53ef\u80fd\u5730\u4f7f\u7528\u8fd9\u4e9b\u52a8\u8bcd\u7528\u6cd5\uff0c\u4f46\u4e00\u4e9b\u5b9e\u9645\u5b9e\u73b0\u53ef\u80fd\u4f1a\u6709\u6240\u4e0d\u540c\uff0c\u4eba\u4eec\u5f88\u5bb9\u6613\u9677\u5165\u8fc2\u8150\u3002\u901a\u5e38\uff0c\u5982\u679c\u60a8\u575a\u6301\u4f7f\u7528 \u8868 5.1 \u4e2d\u63cf\u8ff0\u7684\u9884\u671f\u4f5c\uff0c\u60a8\u5c06\u4e3a API \u7684\u4f7f\u7528\u8005\u521b\u5efa\u4e00\u4e2a\u66f4\u6613\u4e8e\u7406\u89e3\u7684\u754c\u9762\u3002<\/p>\n
NOTE<\/b>  You may notice that if you use the MapMethods() and Map() methods listed in table 5.1, your API probably doesn\u2019t correspond to the expected operations of the HTTP verbs it supports, so I avoid these methods where possible. MapFallback() doesn\u2019t have a path and is called only if no other endpoint matches. Fallback routes can be useful when you have a SPA that uses client-side routing. See http:\/\/mng.bz\/9DMl<\/a> for a description of the problem and an alternative solution.
\n\u6ce8\u610f\uff1a \u60a8\u53ef\u80fd\u4f1a\u6ce8\u610f\u5230\uff0c\u5982\u679c\u4f7f\u7528\u8868 5.1 \u4e2d\u5217\u51fa\u7684 MapMethods\uff08\uff09 \u548c Map\uff08\uff09 \u65b9\u6cd5\uff0c\u5219 API \u53ef\u80fd\u4e0e\u5b83\u652f\u6301\u7684 HTTP \u52a8\u8bcd\u7684\u9884\u671f\u4f5c\u4e0d\u5bf9\u5e94\uff0c\u56e0\u6b64\u6211\u5c3d\u53ef\u80fd\u907f\u514d\u4f7f\u7528\u8fd9\u4e9b\u65b9\u6cd5\u3002MapFallback\uff08\uff09 \u6ca1\u6709\u8def\u5f84\uff0c\u4ec5\u5f53\u6ca1\u6709\u5176\u4ed6\u7ec8\u7aef\u8282\u70b9\u5339\u914d\u65f6\u624d\u4f1a\u8c03\u7528\u3002\u5f53\u60a8\u62e5\u6709\u4f7f\u7528\u5ba2\u6237\u7aef\u8def\u7531\u7684 SPA \u65f6\uff0c\u56de\u9000\u8def\u7531\u53ef\u80fd\u5f88\u6709\u7528\u3002\u6709\u5173\u95ee\u9898\u7684\u8bf4\u660e\u548c\u66ff\u4ee3\u89e3\u51b3\u65b9\u6848\uff0c\u8bf7\u53c2\u9605 http:\/\/mng.bz\/9DMl<\/a>\u3002<\/p>\n
As I mentioned at the start of section 5.2.2, testing APIs that use verbs other than GET is tricky in the browser. You need to use a tool that allows sending arbitrary requests such as Postman (https:\/\/www.postman.com<\/a>) or the HTTP Client plugin in JetBrains Rider. In chapter 11 you\u2019ll learn how to use a tool called Swagger UI to visualize and test your APIs.<\/p>\n
\u6b63\u5982\u6211\u5728 5.2.2 \u8282\u5f00\u5934\u63d0\u5230\u7684\uff0c\u5728\u6d4f\u89c8\u5668\u4e2d\u6d4b\u8bd5\u4f7f\u7528 GET \u4ee5\u5916\u7684\u52a8\u8bcd\u7684 API \u662f\u5f88\u68d8\u624b\u7684\u3002\u60a8\u9700\u8981\u4f7f\u7528\u5141\u8bb8\u53d1\u9001\u4efb\u610f\u8bf7\u6c42\u7684\u5de5\u5177\uff0c\u4f8b\u5982 Postman \uff08https:\/\/www.postman.com<\/a>\uff09 \u6216 JetBrains Rider \u4e2d\u7684 HTTP Client \u63d2\u4ef6\u3002\u5728\u7b2c 11 \u7ae0\u4e2d\uff0c\u60a8\u5c06\u5b66\u4e60\u5982\u4f55\u4f7f\u7528\u540d\u4e3a Swagger UI \u7684\u5de5\u5177\u6765\u53ef\u89c6\u5316\u548c\u6d4b\u8bd5\u60a8\u7684 API\u3002<\/p>\n
TIP<\/b>  The HTTP client plugin in JetBrains Rider makes it easy to craft HTTP requests from inside your API, and even discovers all the endpoints in your application automatically, making them easier to test. You can read more about it at https:\/\/www.jetbrains.com\/help\/rider\/Http_client_in_product__code_editor.html<\/a>.
\n\u63d0\u793a\uff1a JetBrains Rider \u4e2d\u7684 HTTP \u5ba2\u6237\u7aef\u63d2\u4ef6\u53ef\u4ee5\u8f7b\u677e\u5730\u4ece API \u5185\u90e8\u6784\u5efa HTTP \u8bf7\u6c42\uff0c\u751a\u81f3\u53ef\u4ee5\u81ea\u52a8\u53d1\u73b0\u5e94\u7528\u7a0b\u5e8f\u4e2d\u7684\u6240\u6709\u7aef\u70b9\uff0c\u4f7f\u5176\u66f4\u6613\u4e8e\u6d4b\u8bd5\u3002\u60a8\u53ef\u4ee5\u5728 https:\/\/www.jetbrains.com\/help\/rider\/Http_client_in_product__code_editor.html<\/a> \u4e0a\u9605\u8bfb\u66f4\u591a\u76f8\u5173\u4fe1\u606f\u3002<\/p>\n
As a final note before we move on, it\u2019s worth mentioning the behavior you get when you call a method with the wrong HTTP verb. If you define an API like the one in listing 5.1,and call it by using a POST request to \/person\/Al instead of a GET request, the handler won\u2019t run, and the response you get will have status code 405 Method Not Allowed.
\n\u5728\u6211\u4eec\u7ee7\u7eed\u4e4b\u524d\uff0c\u6700\u540e\u8981\u6ce8\u610f\u7684\u662f\uff0c\u5f53\u4f60\u4f7f\u7528\u9519\u8bef\u7684 HTTP \u52a8\u8bcd\u8c03\u7528\u65b9\u6cd5\u65f6\uff0c\u4f60\u5f97\u5230\u7684\u884c\u4e3a\u662f\u503c\u5f97\u4e00\u63d0\u7684\u3002\u5982\u679c\u4f60\u5b9a\u4e49\u4e86\u4e00\u4e2a\u7c7b\u4f3c\u4e8e\u6e05\u5355 5.1 \u4e2d\u7684 API\u3002\u5e76\u4f7f\u7528\u5bf9 \/person\/Al \u7684 POST \u8bf7\u6c42\u800c\u4e0d\u662f GET \u8bf7\u6c42\u6765\u8c03\u7528\u5b83\uff0c\u5219\u5904\u7406\u7a0b\u5e8f\u4e0d\u4f1a\u8fd0\u884c\uff0c\u5e76\u4e14\u60a8\u83b7\u5f97\u7684\u54cd\u5e94\u5c06\u5177\u6709\u72b6\u6001\u4ee3\u7801 405 Method Not Allowed\u3002<\/p>\n
\napp.MapGet("\/person\/{name}", (string name) =>\n    people.Where(p => p.FirstName.StartsWith(name)));\n<\/pre>\n
TIP<\/b>  You should never see this response when you\u2019re calling the API correctly, so if you receive a 405 response, make sure to check that you\u2019re using the right HTTP verb and the right path. Often when I see a 405, I\u2019ve used the correct verb but made a typo in the URL!
\n\u63d0\u793a\uff1a \u6b63\u786e\u8c03\u7528 API \u65f6\uff0c\u60a8\u5e94\u8be5\u6c38\u8fdc\u4e0d\u4f1a\u770b\u5230\u6b64\u54cd\u5e94\uff0c\u56e0\u6b64\uff0c\u5982\u679c\u60a8\u6536\u5230 405 \u54cd\u5e94\uff0c\u8bf7\u52a1\u5fc5\u68c0\u67e5\u60a8\u662f\u5426\u4f7f\u7528\u4e86\u6b63\u786e\u7684 HTTP \u52a8\u8bcd\u548c\u6b63\u786e\u7684\u8def\u5f84\u3002\u901a\u5e38\uff0c\u5f53\u6211\u770b\u5230 405 \u65f6\uff0c\u6211\u4f7f\u7528\u4e86\u6b63\u786e\u7684\u52a8\u8bcd\uff0c\u4f46\u5728 URL \u4e2d\u6253\u9519\u4e86\u5b57\uff01<\/p>\n
In all the examples in this book so far, you provide a lambda function as the handler for an endpoint. But in section 5.2.3, you\u2019ll see that there are many ways to define the handler.<\/p>\n
\u5230\u76ee\u524d\u4e3a\u6b62\uff0c\u5728\u672c\u4e66\u7684\u6240\u6709\u793a\u4f8b\u4e2d\uff0c\u60a8\u90fd\u63d0\u4f9b\u4e86\u4e00\u4e2a lambda \u51fd\u6570\u4f5c\u4e3a\u7ec8\u7aef\u8282\u70b9\u7684\u5904\u7406\u7a0b\u5e8f\u3002\u4f46\u662f\u5728 5.2.3 \u8282 \u4e2d\uff0c\u4f60\u4f1a\u770b\u5230\u6709\u5f88\u591a\u65b9\u6cd5\u53ef\u4ee5\u5b9a\u4e49\u5904\u7406\u7a0b\u5e8f\u3002<\/p>\n
5.2.3 Defining route handlers with functions<\/h3>\n
5.2.3 \u4f7f\u7528\u51fd\u6570\u5b9a\u4e49\u8def\u7531\u5904\u7406\u7a0b\u5e8f<\/h3>\n
For basic examples, using a lambda function as the handler for an endpoint is often the simplest approach, but you can take many approaches, as shown in listing 5.2. This listing also demonstrates creating a simple CRUD (Create, Read, Update, Delete) API using different HTTP verbs, as discussed in section 5.2.1.<\/p>\n
\u5bf9\u4e8e\u57fa\u672c\u793a\u4f8b\uff0c\u4f7f\u7528 lambda \u51fd\u6570\u4f5c\u4e3a\u7ec8\u7aef\u8282\u70b9\u7684\u5904\u7406\u7a0b\u5e8f\u901a\u5e38\u662f\u6700\u7b80\u5355\u7684\u65b9\u6cd5\uff0c\u4f46\u60a8\u53ef\u4ee5\u91c7\u7528\u591a\u79cd\u65b9\u6cd5\uff0c\u5982\u6e05\u5355 5.2 \u6240\u793a\u3002\u6b64\u6e05\u5355\u8fd8\u6f14\u793a\u4e86\u4f7f\u7528\u4e0d\u540c\u7684 HTTP \u52a8\u8bcd\u521b\u5efa\u7b80\u5355\u7684 CRUD\uff08\u521b\u5efa\u3001\u8bfb\u53d6\u3001\u66f4\u65b0\u3001\u5220\u9664\uff09API\uff0c\u5982 5.2.1 \u8282\u6240\u8ff0\u3002<\/p>\n
Listing 5.2 Creating route handlers for a simple CRUD API
\n\u6e05\u5355 5.2 \u4e3a\u7b80\u5355\u7684 CRUD API \u521b\u5efa\u8def\u7531\u5904\u7406\u7a0b\u5e8f<\/p>\n
\nWebApplicationBuilder builder = WebApplication.CreateBuilder(args);\nWebApplication app = builder.Build();\n\napp.MapGet("\/fruit", () => Fruit.All);                             \/\/ \u2776\n\nvar getFruit = (string id) => Fruit.All[id];                       \/\/ \u2777\napp.MapGet("\/fruit\/{id}", getFruit);                               \/\/ \u2777\n\napp.MapPost("\/fruit\/{id}", Handlers.AddFruit);                     \/\/ \u2778\n\nHandlers handlers = new();                                         \/\/ \u2779\napp.MapPut("\/fruit\/{id}", handlers.ReplaceFruit);                  \/\/ \u2779\n\napp.MapDelete("\/fruit\/{id}", DeleteFruit);                         \/\/ \u277a\n\napp.Run();\n\nvoid DeleteFruit(string id)                                        \/\/ \u277a\n{\n    Fruit.All.Remove(id);\n}\n\nrecord Fruit(string Name, int Stock)\n{\n    public static readonly Dictionary<string, Fruit> All = new();\n};\n\nclass Handlers\n{\n    public void ReplaceFruit(string id, Fruit fruit)                \/\/ \u277b\n    {\n        Fruit.All[id] = fruit;\n    }\npublic static void AddFruit(string id, Fruit fruit)                 \/\/ \u277c\n    {\n    Fruit.All.Add(id, fruit);\n}\n}\n<\/pre>\n
\u2776 Lambda expressions are the simplest but least descriptive way to create a handler.
\nLambda \u8868\u8fbe\u5f0f\u662f\u521b\u5efa\u5904\u7406\u7a0b\u5e8f\u7684\u6700\u7b80\u5355\u4f46\u63cf\u8ff0\u6027\u6700\u5dee\u7684\u65b9\u6cd5\u3002<\/p>\n
\u2777 Storing the lambda expression as a variable means you can name it\u2014getFruit in this case.
\n\u5c06 lambda \u8868\u8fbe\u5f0f\u5b58\u50a8\u4e3a\u53d8\u91cf\u610f\u5473\u7740\u60a8\u53ef\u4ee5\u5c06\u5176\u547d\u540d\u4e3a getFruit\uff0c\u5728\u672c\u4f8b\u4e2d\u4e3a getFruit\u3002<\/p>\n
\u2778 Handlers can be static methods in any class.
\n\u5904\u7406\u7a0b\u5e8f\u53ef\u4ee5\u662f\u4efb\u4f55\u7c7b\u4e2d\u7684\u9759\u6001\u65b9\u6cd5\u3002<\/p>\n
\u2779 Handlers can also be instance methods.
\n\u5904\u7406\u7a0b\u5e8f\u4e5f\u53ef\u4ee5\u662f\u5b9e\u4f8b\u65b9\u6cd5\u3002<\/p>\n
\u277a You can also use local functions, introduced in C# 7.0, as handler methods.
\n\u8fd8\u53ef\u4ee5\u4f7f\u7528 C# 7.0 \u4e2d\u5f15\u5165\u7684\u672c\u5730\u51fd\u6570\u4f5c\u4e3a\u5904\u7406\u7a0b\u5e8f\u65b9\u6cd5\u3002<\/p>\n
\u277b Handlers can also be instance methods.
\n\u5904\u7406\u7a0b\u5e8f\u4e5f\u53ef\u4ee5\u662f\u5b9e\u4f8b\u65b9\u6cd5\u3002<\/p>\n
\u277c Converts the response to a JsonObject
\n\u5c06\u54cd\u5e94\u8f6c\u6362\u4e3a JsonObject<\/p>\n
Listing 5.2 demonstrates the various ways you can pass handlers to an endpoint by simulating a simple API for interacting with a collection of Fruit items:
\n\u6e05\u5355 5.2 \u901a\u8fc7\u6a21\u62df\u4e00\u4e2a\u7b80\u5355\u7684 API \u6765\u4e0e Fruit \u9879\u76ee\u96c6\u5408\u4ea4\u4e92\uff0c\u6f14\u793a\u4e86\u5c06\u5904\u7406\u7a0b\u5e8f\u4f20\u9012\u7ed9\u7aef\u70b9\u7684\u5404\u79cd\u65b9\u6cd5\uff1a<\/p>\n
\u2022   A lambda expression, as in the MapGet("\/fruit") endpoint
\nlambda \u8868\u8fbe\u5f0f\uff0c\u5982\u7ec8\u7aef\u8282\u70b9\u4e2d\u6240\u793aMapGet("\/fruit")<\/p>\n
\u2022   A Func<T, TResult><\/code> variable, as in the MapGet("\/fruit\/{id}") endpoint
\n\u4e00\u4e2aFunc<T, TResult>`\u53d8\u91cf,\u5982\u7aef\u70b9,MapGet("\/fruit\/{id}")<\/p>\n
\u2022   A static method, as in the MapPost endpoint
\n\u9759\u6001\u65b9\u6cd5\uff0c\u5982\u7aef\u70b9MapPost<\/p>\n
\u2022   A method on an instance variable, as in the MapPut endpoint
\n\u5b9e\u4f8b\u53d8\u91cf\u4e0a\u7684\u65b9\u6cd5\uff0c\u5982\u7aef\u70b9\u4e2d\u6240\u793aMapPut<\/p>\n
\u2022   A local function, as in the MapDelete endpoint
\n\u672c\u5730\u51fd\u6570\uff0c\u5982\u7aef\u70b9MapDelete<\/p>\n
All these approaches are functionally identical, so you can use whichever pattern works best for you.
\n\u6240\u6709\u8fd9\u4e9b\u65b9\u6cd5\u5728\u529f\u80fd\u4e0a\u90fd\u662f\u76f8\u540c\u7684\uff0c\u56e0\u6b64\u60a8\u53ef\u4ee5\u4f7f\u7528\u6700\u9002\u5408\u60a8\u7684\u6a21\u5f0f\u3002<\/p>\n
Each Fruit record in listing 5.2 has a Name and a Stock level and is stored in a dictionary with an id. You call the API by using different HTTP verbs to perform the CRUD operations against the dictionary.<\/p>\n
\u6e05\u5355 5.2 \u4e2d\u7684\u6bcf\u4e2a Fruit \u8bb0\u5f55\u90fd\u6709\u4e00\u4e2a Name \u548c\u4e00\u4e2a Stock \u7ea7\u522b\uff0c\u5e76\u5b58\u50a8\u5728\u4e00\u4e2a\u5e26\u6709 id \u7684\u5b57\u5178\u4e2d\u3002\u60a8\u53ef\u4ee5\u4f7f\u7528\u4e0d\u540c\u7684 HTTP \u52a8\u8bcd\u8c03\u7528 API\uff0c\u4ee5\u5bf9\u5b57\u5178\u6267\u884c CRUD\u4f5c\u3002<\/p>\n
WARNING<\/b> This API is simple. It isn\u2019t thread-safe, doesn\u2019t validate user input, and doesn\u2019t handle edge cases. We\u2019ll remedy some of those deficiencies in section 5.3.
\n\u8b66\u544a: \u6b64 API \u5f88\u7b80\u5355\u3002\u5b83\u4e0d\u662f\u7ebf\u7a0b\u5b89\u5168\u7684\uff0c\u4e0d\u9a8c\u8bc1\u7528\u6237\u8f93\u5165\uff0c\u4e5f\u4e0d\u5904\u7406\u8fb9\u7f18\u60c5\u51b5\u3002\u6211\u4eec\u5c06\u5728\u7b2c 5.3 \u8282\u4e2d\u7ea0\u6b63\u5176\u4e2d\u4e00\u4e9b\u7f3a\u9677\u3002<\/p>\n
The handlers for the POST and PUT endpoints in listing 5.2 accept both an id parameter and a Fruit parameter, showing another important feature of minimal APIs. Complex types\u2014that is, types that can\u2019t be extracted from the URL by means of route parameters\u2014are created by deserializing the JSON body of a request.<\/p>\n
\u6e05\u5355 5.2 \u4e2d POST \u548c PUT \u7aef\u70b9\u7684\u5904\u7406\u7a0b\u5e8f\u540c\u65f6\u63a5\u53d7 id \u53c2\u6570\u548c Fruit \u53c2\u6570\uff0c\u8fd9\u663e\u793a\u4e86\u6700\u5c0f API \u7684\u53e6\u4e00\u4e2a\u91cd\u8981\u7279\u6027\u3002\u590d\u6742\u7c7b\u578b\uff08\u5373\u65e0\u6cd5\u901a\u8fc7\u8def\u7531\u53c2\u6570\u4ece URL \u4e2d\u63d0\u53d6\u7684\u7c7b\u578b\uff09\u662f\u901a\u8fc7\u53cd\u5e8f\u5217\u5316\u8bf7\u6c42\u7684 JSON \u6b63\u6587\u6765\u521b\u5efa\u7684\u3002<\/p>\n
NOTE<\/b>  By contrast with APIs built using ASP.NET and ASP.NET Core web API controllers (which we cover in chapter 20), minimal APIs can bind only to JSON bodies and always use the System.Text.Json library for JSON deserialization.
\n\u6ce8\u610f: \u4e0e\u4f7f\u7528 ASP.NET \u548c ASP.NET Core Web API \u63a7\u5236\u5668\u6784\u5efa\u7684 API\uff08\u6211\u4eec\u5c06\u5728\u7b2c 20 \u7ae0\u4e2d\u4ecb\u7ecd\uff09\u76f8\u6bd4\uff0c\u6700\u5c0f\u7684 API \u53ea\u80fd\u7ed1\u5b9a\u5230 JSON \u6b63\u6587\uff0c\u5e76\u59cb\u7ec8\u4f7f\u7528 System.Text.Json \u5e93\u8fdb\u884c JSON \u53cd\u5e8f\u5217\u5316\u3002<\/p>\n
Figure 5.3 shows an example of a POST request sent with Postman. Postman sends the request body as JSON, which the minimal API automatically deserializes into a Fruit instance before calling the endpoint handler. You can bind only a single object in your endpoint handler to the request body in this way. I cover model binding in detail in chapter 7.<\/p>\n
\u56fe 5.3 \u663e\u793a\u4e86\u4f7f\u7528 Postman \u53d1\u9001\u7684 POST \u8bf7\u6c42\u7684\u793a\u4f8b\u3002Postman \u4ee5 JSON \u683c\u5f0f\u53d1\u9001\u8bf7\u6c42\u6b63\u6587\uff0c\u6700\u5c0f API \u4f1a\u81ea\u52a8\u5c06\u5176\u53cd\u5e8f\u5217\u5316\u4e3a Fruit
\n\u5b9e\u4f8b\u3002\u901a\u8fc7\u8fd9\u79cd\u65b9\u5f0f\uff0c\u60a8\u53ea\u80fd\u5c06\u7ec8\u7aef\u8282\u70b9\u5904\u7406\u7a0b\u5e8f\u4e2d\u7684\u5355\u4e2a\u5bf9\u8c61\u7ed1\u5b9a\u5230\u8bf7\u6c42\u6b63\u6587\u3002\u6211\u5728\u7b2c 7 \u7ae0\u4e2d\u8be6\u7ec6\u4ecb\u7ecd\u4e86\u6a21\u578b\u7ed1\u5b9a\u3002<\/p>\n
\"alt<\/p>\n
Figure 5.3 Sending a POST request with Postman. The minimal API automatically deserializes the JSON in the request body to a Fruit instance before calling the endpoint handler.
\n\u56fe 5.3 \u4f7f\u7528 Postman \u53d1\u9001 POST \u8bf7\u6c42\u3002\u5728\u8c03\u7528\u7ec8\u7aef\u8282\u70b9\u5904\u7406\u7a0b\u5e8f\u4e4b\u524d\uff0c\u6700\u5c0f API \u4f1a\u81ea\u52a8\u5c06\u8bf7\u6c42\u6b63\u6587\u4e2d\u7684 JSON \u53cd\u5e8f\u5217\u5316\u4e3a Fruit \u5b9e\u4f8b\u3002<\/p>\n
Minimal APIs leave you free to organize your endpoints any way you choose. That flexibility is often cited as a reason to not use them, due to the fear that developers will keep all the functionality in a single file, as in most examples (such as listing 5.2). In practice, you\u2019ll likely want to extract your endpoints to separate files so as to modularize them and make them easier to understand. Embrace that urge; that\u2019s the way they were intended to be used!<\/p>\n
\u6700\u5c11\u7684 API \u8ba9\u60a8\u53ef\u4ee5\u81ea\u7531\u5730\u6309\u7167\u60a8\u9009\u62e9\u7684\u4efb\u4f55\u65b9\u5f0f\u7ec4\u7ec7\u7ec8\u7aef\u8282\u70b9\u3002\u8fd9\u79cd\u7075\u6d3b\u6027\u7ecf\u5e38\u88ab\u5f15\u7528\u4e3a\u4e0d\u4f7f\u7528\u5b83\u4eec\u7684\u7406\u7531\uff0c\u56e0\u4e3a\u62c5\u5fc3\u5f00\u53d1\u4eba\u5458\u4f1a\u4fdd\u7559\u6240\u6709\u529f\u80fd\u5728\u5355\u4e2a\u6587\u4ef6\u4e2d\uff0c\u5c31\u50cf\u5927\u591a\u6570\u793a\u4f8b\u4e00\u6837\uff08\u6bd4\u5982\u6e05\u5355 5.2\uff09\u3002\u5728\u5b9e\u8df5\u4e2d\uff0c\u60a8\u53ef\u80fd\u5e0c\u671b\u5c06\u7ec8\u7aef\u8282\u70b9\u63d0\u53d6\u5230\u5355\u72ec\u7684\u6587\u4ef6\u4e2d\uff0c\u4ee5\u4fbf\u5c06\u5b83\u4eec\u6a21\u5757\u5316\u5e76\u4f7f\u5176\u66f4\u6613\u4e8e\u7406\u89e3\u3002\u62e5\u62b1\u8fd9\u79cd\u51b2\u52a8;\u8fd9\u5c31\u662f\u5b83\u4eec\u7684\u4f7f\u7528\u65b9\u5f0f\uff01<\/p>\n
Now you have a simple API, but if you try it out, you\u2019ll quickly run into scenarios in which your API seems to break. In section 5.3 you learn how to handle some of these scenarios by returning status codes.<\/p>\n
\u73b0\u5728\u4f60\u6709\u4e00\u4e2a\u7b80\u5355\u7684 API\uff0c\u4f46\u5982\u679c\u4f60\u5c1d\u8bd5\u4e00\u4e0b\uff0c\u4f60\u5f88\u5feb\u5c31\u4f1a\u9047\u5230 API \u4f3c\u4e4e\u5d29\u6e83\u7684\u60c5\u51b5\u3002\u5728 Section 5.3 \u4e2d\uff0c\u60a8\u5c06\u5b66\u4e60\u5982\u4f55\u901a\u8fc7\u8fd4\u56de\u72b6\u6001\u4ee3\u7801\u6765\u5904\u7406\u5176\u4e2d\u4e00\u4e9b\u573a\u666f\u3002<\/p>\n
5.3 Generating responses with IResult<\/h2>\n
5.3 \u4f7f\u7528 IResult \u751f\u6210\u54cd\u5e94<\/h2>\n
You\u2019ve seen the basics of minimal APIs, but so far, we\u2019ve looked only at the happy path, where you can handle the request successfully and return a response. In this section we look at how to handle bad requests and other errors by returning different status codes from your API.<\/p>\n
\u60a8\u5df2\u7ecf\u4e86\u89e3\u4e86\u6700\u5c0f API \u7684\u57fa\u7840\u77e5\u8bc6\uff0c\u4f46\u5230\u76ee\u524d\u4e3a\u6b62\uff0c\u6211\u4eec\u53ea\u4e86\u89e3\u4e86 Happy Path\uff0c\u60a8\u53ef\u4ee5\u5728\u5176\u4e2d\u6210\u529f\u5904\u7406\u8bf7\u6c42\u5e76\u8fd4\u56de\u54cd\u5e94\u3002\u5728\u672c\u8282\u4e2d\uff0c\u6211\u4eec\u5c06\u4e86\u89e3\u5982\u4f55\u901a\u8fc7\u4ece API \u8fd4\u56de\u4e0d\u540c\u7684\u72b6\u6001\u4ee3\u7801\u6765\u5904\u7406\u9519\u8bef\u8bf7\u6c42\u548c\u5176\u4ed6\u9519\u8bef\u3002<\/p>\n
The API in listing 5.2 works well as long as you perform only operations that are valid for the current state of the application. If you send a GET request to \/fruit, for example, you\u2019ll always get a 200 success response, but if you send a GET request to \/fruit\/f1 before you create a Fruit with the id f1, you\u2019ll get an exception and a 500 Internal Server Error response, as shown in figure 5.4.<\/p>\n
\u6e05\u5355 5.2 \u4e2d\u7684 API \u8fd0\u884c\u826f\u597d\uff0c\u53ea\u8981\u60a8\u53ea\u6267\u884c\u5bf9\u5e94\u7528\u7a0b\u5e8f\u5f53\u524d\u72b6\u6001\u6709\u6548\u7684\u4f5c\u3002\u4f8b\u5982\uff0c\u5982\u679c\u5411 \/fruit \u53d1\u9001 GET \u8bf7\u6c42\uff0c\u5219\u59cb\u7ec8\u4f1a\u6536\u5230 200 \u6210\u529f\u54cd\u5e94\uff0c\u4f46\u5982\u679c\u5728\u521b\u5efa ID \u4e3a f1 \u7684 Fruit \u4e4b\u524d\u5411 \/fruit\/f1 \u53d1\u9001 GET \u8bf7\u6c42\uff0c\u5219\u4f1a\u6536\u5230\u5f02\u5e38\u548c 500 Internal Server Error \u54cd\u5e94\uff0c\u5982\u56fe 5.4 \u6240\u793a\u3002<\/p>\n
\"alt<\/p>\n
Figure 5.4 If you try to retrieve a fruit by using a nonexistent id for the simplistic API in listing 5.2, the endpoint throws an exception. This exception is handled by the DeveloperExceptionPageMiddleware but provides a poor experience.
\n\u56fe 5.4 \u5982\u679c\u4f60\u5c1d\u8bd5\u4f7f\u7528\u6e05\u5355 5.2 \u4e2d\u7b80\u5355 API \u7684\u4e0d\u5b58\u5728\u7684 id \u6765\u68c0\u7d22\u6c34\u679c\uff0c\u7aef\u70b9\u4f1a\u629b\u51fa\u4e00\u4e2a\u5f02\u5e38\u3002\u6b64\u5f02\u5e38\u7531 DeveloperExceptionPage-Middleware \u5904\u7406\uff0c\u4f46\u63d0\u4f9b\u7684\u4f53\u9a8c\u5f88\u5dee\u3002<\/p>\n
Throwing an exception whenever a user requests an id that doesn\u2019t exist clearly makes for a poor experience all round. A better approach is to return a status code indicating the problem, such as 404 Not Found or 400 Bad Request. The most declarative way to do this with minimal APIs is to return an IResult instance.<\/p>\n
\u6bcf\u5f53\u7528\u6237\u8bf7\u6c42\u4e0d\u5b58\u5728\u7684 ID \u65f6\u5f15\u53d1\u5f02\u5e38\uff0c\u663e\u7136\u4f1a\u5bfc\u81f4\u6574\u4f53\u4f53\u9a8c\u4e0d\u4f73\u3002\u66f4\u597d\u7684\u65b9\u6cd5\u662f\u8fd4\u56de\u6307\u793a\u95ee\u9898\u7684\u72b6\u6001\u4ee3\u7801\uff0c\u4f8b\u5982 404 Not Found \u6216 400 Bad Request\u3002\u4f7f\u7528\u6700\u5c11\u7684 API \u6267\u884c\u6b64\u4f5c\u7684\u6700\u58f0\u660e\u6027\u65b9\u6cd5\u662f\u8fd4\u56de IResult \u5b9e\u4f8b\u3002<\/p>\n
All the endpoint handlers you\u2019ve seen so far in this book have returned void, a string, or a plain old CLR object (POCO) such as Person or Fruit. There is one other type of object you can return from an endpoint: an IResult implementation. In summary, the endpoint middleware handles each return type as follows:<\/p>\n
\u5230\u76ee\u524d\u4e3a\u6b62\uff0c\u60a8\u5728\u672c\u4e66\u4e2d\u770b\u5230\u7684\u6240\u6709\u7aef\u70b9\u5904\u7406\u7a0b\u5e8f\u90fd\u8fd4\u56de\u4e86 void\u3001\u5b57\u7b26\u4e32\u6216\u666e\u901a\u7684\u65e7 CLR \u5bf9\u8c61 \uff08POCO\uff09\uff0c\u4f8b\u5982 Person \u6216 Fruit\u3002\u60a8\u53ef\u4ee5\u4ece\u7aef\u70b9\u8fd4\u56de\u53e6\u4e00\u79cd\u7c7b\u578b\u7684\u5bf9\u8c61\uff1aIResult \u5b9e\u73b0\u3002\u603b\u4e4b\uff0c\u7ec8\u7aef\u8282\u70b9\u4e2d\u95f4\u4ef6\u6309\u5982\u4e0b\u65b9\u5f0f\u5904\u7406\u6bcf\u4e2a\u8fd4\u56de\u7c7b\u578b\uff1a<\/p>\n