Microsoft REST API指南 摘要 Microsoft REST API指南作为一种设计原则，鼓励应用程序开发人员通过RESTful HTTP接口访问资源。...分类 作为Microsoft REST API指南的一部分，服务必须符合下面定义的分类法。 5.1 错误 错误，或者更具体地说是服务错误，定义为因客户端向服务传递错误数据，导致服务端拒绝该请求。...即使api没有使用其他OData结构，也应该使用这种格式。 错误响应必须是单个JSON对象。该对象必须有一个名为“error”的 名称/值（name/value） 对。该值必须是JSON对象。...“target”键值对的值 是指向错误的具体的目标(例如，错误中属性的名称)。...空值(NULL)必须排序为“小于”非空值。 必须根据第一个表达式的结果值对项进行排序，然后根据第二个表达式的结果值对第一个表达式具有相同值的项进行排序，以此类推。 排序顺序是属性类型的固有顺序。
应用程序从 Main 方法开始执行，但参数是以数组 (string[] args) 形式传入，并不区分数组中的哪些项是命令、选项和参数等。...再以 dotnet new 为例，--name 选项有用于指定项目名称的参数。与命令或选项关联的值称为“参数”。 指令：这些是跨所有应用程序的整合命令。...另一个功能是命令行语法验证，它检测是否缺少必需参数（没有指定默认值的参数）。如果你没有指定必需参数，System.CommandLine 会自动发出错误消息“选项 --output 缺少必需参数”。...如果你键入无法识别的选项或命令名称，System.CommandLine 会自动返回命令行错误消息“无法识别命令或参数…”。不过，如果指定的名称与现有选项类似，那么错误消息就会提示建议更正拼写错误。...也可以在运行时动态提供这些值，如通过在参数是 NuGet 引用时返回可用 NuGet 包列表的 REST 调用。
Address = null); 生成的模式为该类型提供了 JSON 序列化契约的规范。从这个例子中可以看出，它区分了可空属性和不可空属性，并根据构造函数参数是否可选来填充“required”关键字。...“Name”不允许为空值。...如果您希望在这些情况下强制执行可空性验证，建议您将类型建模为 struct（因为结构体不允许空值），或者编写一个自定义转换器，将其 HandleNull 属性(https://learn.microsoft.com...Optional = null); // JsonException：类型“MyPoco”的 JSON 反序列化缺少必需的属性，包括：“Required”。...我们希望您尝试新功能并向我们提供反馈，告诉我们它如何改进您的应用程序，以及您可能遇到的任何可用性问题或错误。
二、可能出错的原因 导致org.springframework.web.bind.MissingRequestHeaderException报错的原因主要有以下几点： 请求头缺失：客户端请求中缺少必需的请求头...请求头名称错误：请求头的名称拼写错误或大小写不匹配。 默认值未设置：当请求头不是必须的，但未提供默认值时。...三、错误代码示例 以下是一个可能导致该报错的代码示例，并解释其错误之处： @RestController @RequestMapping("/api") public class ApiController...四、正确代码示例 为了解决该报错问题，我们可以采取以下几种方法： 设置默认值：如果请求头不是必须的，可以为其设置默认值。 指定请求头为可选：通过将required属性设置为false。...默认值设置：对于非必需的请求头，设置合理的默认值以避免异常。 错误处理：在控制器中添加适当的错误处理逻辑，提供清晰的错误信息。 代码风格和规范：遵循良好的代码风格和规范，保持代码清晰和可维护。
服务可以支持 PUT 更新现有资源，但必须是完整替换（也就是说，在 PUT 后，资源的所有属性必须与请求中提供的内容相匹配，包括删除所有未提供的服务端属性）。...Prefer | 返回=极小值 ，返回=代表事物 | 如果指定了返回＝最小优先级，则服务应响应成功插入或更新返回空主体。如果指定了Reale=表示，服务应该返回响应中创建的或更新的资源。...这些错误代码应在“内部错误”中公开，如下所述。为现有客户端可见的“代码”引入新值是一个突破性的改变，需要增加版本。服务可以通过向“内部错误”添加新的错误代码来避免破坏更改。...“消息”键值对的值必须是错误提示消息，必须是可读且易于理解。它的目的是帮助开发人员，不适合暴露给最终用户。希望为最终用户公开合适消息的服务必须通过注释或自定义属性进行。...“目标”键值对的值是特定错误的目标（例如，错误的属性名称）。
虽然它可以使用 XML 来描述数据，但它更常用的是 JSON，它是一种轻量级的数据包装器。 JSON 使用标签标识数据，但标签没有在正式的模式定义中指定，也没有明确的数据类型。...%REST.Impl 类提供了可以调用的方法，以便设置 HTTP 标头、报告错误等。Web 应用程序，通过 Web Gateway 提供对 REST 服务的访问。...Web 应用程序配置为启用 REST 访问并使用特定的调度类。 Web 应用程序还控制对 REST 服务的访问。对这些组件遵循严格的命名约定。...%REST.API 类，可以使用它来发现服务器上的 REST 服务，为这些 REST 服务生成 OpenAPI 2.0 规范，以及在服务器上创建、更新或删除 REST 服务。...创建 REST 服务概述创建 REST 服务的推荐方式大致如下：获取（或编写）服务的 OpenAPI 2.0 规范。使用 API 管理工具生成 REST 服务类和关联的 Web 应用程序。
你的工作不是写setter、空值检查或try-catch-finally，但大多数C#代码库却逼着你做这些。...深入探讨前：先看看痛点（和解决方案） 1. required + init：告别构造函数 这对组合让你在编译时快速发现错误，无需构造函数、魔术字符串和空值，就能构建DTO和配置。...缺少必填属性会在编译时直接报错——这是最佳的错误发现时机。 参考：required修饰符 — Microsoft Docs 2....模式匹配：比if更智能 模式匹配已全面升级： • 类型模式 • 属性模式 • 递归和列表模式（C# 12+） ✅ 实际API示例： return request.Method switch {...; 借助深层模式，你甚至可以匹配嵌套的对象结构和集合——无需空值链和类型检查。
Address = null); 生成的模式为该类型提供了 JSON 序列化契约的规范。从这个例子中可以看出，它区分了可空属性和不可空属性，并根据构造函数参数是否可选来填充“required”关键字。...“Name”不允许为空值。...如果您希望在这些情况下强制执行可空性验证，建议您将类型建模为 struct（因为结构体不允许空值），或者编写一个自定义转换器，将其 HandleNull 属性(https://learn.microsoft.com...Optional = null); // JsonException：类型“MyPoco”的 JSON 反序列化缺少必需的属性，包括：“Required”。...我们希望您尝试新功能并向我们提供反馈，告诉我们它如何改进您的应用程序，以及您可能遇到的任何可用性问题或错误。 我们随时欢迎社区贡献。
Web API在现代软件开发中是不可或缺的组成部分，它们促使了系统的模块化、可扩展性和互操作性，为开发人员提供了强大的工具来构建各种类型的应用程序。...约束（Constraints）： 路由约束允许你指定路由参数的格式或值的范围。例如，你可以使用正则表达式来确保id参数是数字，或者使用[Range]属性进行范围验证。...如果验证失败，将返回包含错误信息的 BadRequest 响应。...如果验证失败，将返回包含错误信息的 BadRequest 响应；否则，将继续执行创建产品的逻辑。...了解Web API路由的基本概念是关键，可以通过特性路由或全局路由配置来定义API端点。创建数据模型是构建API的基础，可以通过数据注解或Fluent Validation来进行验证。
上面的代码同时将其默认路由的前缀设置为 api/1.0。...例如上面的 MaxLength ，已经用错了，MaxLength 是指定属性中允许的数组或字符串数据的最大长度，不能用在 int 类型上。大家测试一下请求下面的 json，会发现报异常。...[Range]：验证属性值是否在指定的范围内。 [RegularExpression]：验证属性值是否与指定的正则表达式匹配。 [Required]：验证字段是否不为 null。...有关此属性的行为的详细信息 [StringLength]：验证字符串属性值是否不超过指定长度限制。 [Url]：验证属性是否具有 URL 格式。...[MaxLength ] MaxLength 是指定属性中允许的数组或字符串数据的最大长度 参考：https://docs.microsoft.com/zh-cn/dotnet/api/system.componentmodel.dataannotations
REST 架构风格中最复杂的约束，也是构建成熟 REST 服务的核心。...它的重要性在于打破了客户端和服务器之间严格的契约，使得客户端可以更加智能和自适应，而 REST 服务本身的演化和更新也变得更加容易。...HATEOAS的优点有: 具有可进化性并且能自我描述 超媒体(Hypermedia, 例如超链接)驱动如何消费和使用API, 它告诉客户端如何使用API, 如何与API交互, 例如: 如何删除资源, 更新资源...-30T21:41:12.650Z" } 如果不使用HATEOAS的话, 可能会有这些问题: 客户端更多的需要了解API内在逻辑 如果API发生了一点变化(添加了额外的规则, 改变规则)都会破坏API...我们可以点击超链接进行跳转, 也可以提交表单, 这就是超媒体驱动应用程序(浏览器)状态的例子.
在应用程序的其它层面可能会需要附加验证（例如，数据层可能会强制外键约束）。 {"Id":4, "Name":"Gizmo"} 此处，客户端并未指定Price或Weight的值。...JSON格式化器会将默认值（这里是零）赋给这些缺失的属性。 “Under-Posting（递交不足）”：当客户端遗漏了某些属性时，便会发生“Under-posting”。...此时模型的状态是有效的，因为零是这些属性的有效值。这是否是一个问题取决于你所处的场景。例如，在一个更新操作中，你可能希望区分出“零”与“未设置”。...为了强迫客户端要设置一个值，将该属性构造成nullable（可空的），并设置Required注解属性： [Required] public decimal?...当验证失败时，Web API并不会自动地将错误返回给客户端。
REST的原则/约束 REST有6大原则/约束, 每一个原则都是对API有正面或负面影响的设计决定....只有满足了这6个原则的系统才可以真正称得上是RESTful的, 其实大部分系统的RESTful API并不是RESTful的, 但这样并不代表这些API就不好, 利弊需要开发人员去衡量...., 但并不是直接支持RESTful的 Web API....为MVC定义路由有两种方式：使用IRouteBuilder或者使用基于属性标签的路由。针对Rest，最好还是使用基于属性标签的方式。...那么在Action里面得到的参数person的属性值都是null。
举个例子，假设我们有一个 RESTful API，用于更新用户信息的请求路径为 /users/{id}，其中 {id} 表示要更新的用户的唯一标识。...如果转换失败，即说明路径中没有提供有效值，我们可以手动为变量赋予默认值。 总结来说，@PathVariable 注解本身是没有提供默认值的属性的。...这样如果 URL 中缺少路径变量 id，将会接收 null 值，并可以在方法中处理缺少路径变量的情况。 需要注意的是，将 required 属性设置为 false 可能会导致安全问题。...例如，如果处理敏感数据的 URL 缺少必需的路径变量，那么将导致应用程序返回错误或意外的结果。...另外，如果路径变量是必需的，即使仅仅是可解析的空值（例如 /users//profile），@PathVariable 注解也会引发 MissingPathVariableException 异常。
app.MapMethods() 方法用于处理指定的 HTTP 请求方法，当请求的路径为 /hello 且方法为 GET、POST、PUT 或 DELETE 时，返回相应的信息。...如果模型验证失败，我们通过自定义的 `InvalidModelStateResponseFactory` 来返回验证错误信息。 ...如果模型验证失败，将返回包含验证错误信息的 BadRequest 响应；如果模型验证成功，将返回包含有效的 `Person` 对象的 Ok 响应。 ...在应用程序的主函数中，我们注册了自定义的异常处理中间件，并在根路径上抛出一个异常，以模拟应用程序中的异常情况。当访问根路径时，异常处理中间件将捕获并处理异常，并返回相应的错误响应。 ...下面是一个更全面的代码示例，演示了如何在 Minimal API 中使用依赖注入： ```csharp using Microsoft.AspNetCore.Builder; using Microsoft.AspNetCore.Http
如果没有设置报头字段，且发送的数据是 json 格式，默认会将 Content-Type 设置为 application/json，否则设置为 text/plain。...如果该参数为空，则不使用代理 官方在这里提供了一个例子来介绍如何使用封装的对象。...选中Process tags_，_会讲webhook返回的json属性值作为问题事件标签。选中事件菜单复选框，可以在事件发生时点击问题名称访问外部的地址。...输入数据验证包括 Webhook 配置或 Webhook 测试中使用的值无效。 缺少网络钩子参数。webhook 代码应该验证所需的参数并确定必需的参数是否存在。 宏是否被解析。...这包括以下验证： 是否有响应并且没有 HTTP 错误。 响应是否包含预期格式的数据（原始/JSON/XML/等）。 响应是否包含所有必需的字段或数据。 响应数据中有没有错误。
在开启 Nullable 可空类型之后，原本可以调用的 API 也许就会提示 400 BadRequest 因为传入参数不合法，模型校验失败，此时将不会进入预期的 API 函数，同时也不会在输出里面找到有用的信息...API 也许在客户端调用的时候，将会提示 400 BadRequest 内容大概如下 { "type":"https://tools.ietf.org/html/rfc7231#section...也许调用的 API 错误了，本来是预期调用 Foo 的，但却调用了 A 接口 也许调用的端口不对，也许是被 Fiddler 干扰了 也许是传入的参数不合法 如上面提示，实际内容是 The Account...实际上在开启可空之后，尽管在客户端代码里面设置了 multipartFormDataContent.Add(new StringContent(account), "Account"); 但是传入的内容是空字符串...而开启可空之后，定义的数据模型 public string Account { get; set; } 表示 Account 一定不是空，于是传入空的 Account 属性将会校验不通过 有两个解决方法
REST 架构风格中最复杂的约束，也是构建成熟 REST 服务的核心。...它的重要性在于打破了客户端和服务器之间严格的契约，使得客户端可以更加智能和自适应，而 REST 服务本身的演化和更新也变得更加容易。...HATEOAS的优点有: 具有可进化性并且能自我描述 超媒体(Hypermedia, 例如超链接)驱动如何消费和使用API, 它告诉客户端如何使用API, 如何与API交互, 例如: 如何删除资源, 更新资源...我们可以点击超链接进行跳转, 也可以提交表单, 这就是超媒体驱动应用程序(浏览器)状态的例子....EntityBase是我的项目特有的, 您可能不需要.
HTTP 状态码 404 用于错误的 URL 400 -responses 有特定错误的附加信息（例如缺少必需的属性） 当 API 使用者使用错误的凭证时使用 401 -response 403 使用有效但请求...API 使用者无法访问的端点或尝试使用他们不允许执行的操作 500 - 当存在 API 使用者无法通过更改请求来解决的内部处理问题时响应 500 -responses 具有特定于应用程序的错误代码...，但不是关于确切错误（堆栈跟踪或错误文本）的非常清晰的普通消息，这可能会将内部实现暴露给 API 使用者 GET: 200 OK 和 items -array 作为空数组 GET：204 空响应，正文中没有任何内容...如果使用 ISO 标准中的地理坐标？ 有效负载本地化支持或可通过 API 访问的本地化值？ 支持错误消息本地化吗？...规范包含标准格式的请求和响应示例，API 文档根据规范、模式和示例自动生成 POST, PUT: 201 为创建新资源而创建 来自客户端的 400 个错误请求，例如缺少必需的查询参数 白名单：POST、
由上述例子可知，我们实现了5种操作，但只用了两个接口地址， /api/v1/love 和 /api/v1/love/1 。...所以这是一个客户端发生的错误, 程序为让客户端知道是它引起了错误, 就应该返回一个Bad Request 400 (Bad Request表示客户端引起的错误)的 Status Code....其他的验证注解都有一个属性叫做 ErrorMessage (string), 表示如果验证失败, 就会把ErrorMessage的内容添加到错误结果里面去....Dictionary, 它里面是请求提交到Action的Name和Value的对们, 一个name对应着model的一个属性, 它也包含了一个针对每个提交的属性的错误信息的集合....返回: PUT建议返回NoContent(), 因为更新是客户端发起的, 客户端已经有了最新的值, 无须服务器再给它传递一次, 当然了, 如果有些值是在后台更新的, 那么也可以使用Ok(xxx)然后把更新后的
云服务器
ICP备案
腾讯会议
云直播
对象存储
