Azure/go-autorest

## 迁移到受支持的 SDK - 有关新 Azure Go SDK 的常规信息，请参见[此处](https://github.com/Azure/azure-sdk-for-go/blob/main/documentation/new-version-guideline.md)。 - 关于 SDK 迁移，请查阅 SDK [迁移指南](https://github.com/Azure/azure-sdk-for-go/blob/main/documentation/MIGRATION_GUIDE.md)。 - 要从 `autorest/adal` 迁移到其替代方案，请参阅 [azidentity 迁移指南](https://github.com/Azure/azure-sdk-for-go/blob/main/sdk/azidentity/MIGRATION.md)。 ## go-autorest [](https://godoc.org/github.com/Azure/go-autorest/autorest) [](https://dev.azure.com/azure-sdk/public/_build/latest?definitionId=625&branchName=master) [](https://goreportcard.com/report/Azure/go-autorest) go-autorest 包提供了一个 HTTP 请求客户端，可与 [Autorest](https://github.com/Azure/autorest.go) 生成的 API 客户端包配合使用。 本仓库的 `github.com/Azure/go-autorest/autorest/adal` 包中还 提供了一个经过 Azure Active Directory (AAD) 测试的身份验证客户端。 尽管它的名字如此，但此包仅作为 Azure Go SDK 的一部分进行维护，与 [github.com/AzureAD](https://github.com/AzureAD) 中的其他“ADAL”库无关。 ### 概述 go-autorest 包实现了一个适合在多个 goroutine 中使用的 HTTP 请求管道，并提供了由 [Autorest](https://github.com/Azure/autorest.go) 生成的包所使用的共享例程。 该包将发送和响应 HTTP 请求分为三个阶段：Preparing、Sending 和 Responding。一个典型的模式是： ``` req, err := Prepare(&http.Request{}, token.WithAuthorization()) resp, err := Send(req, WithLogging(logger), DoErrorIfStatusCode(http.StatusInternalServerError), DoCloseIfError(), DoRetryForAttempts(5, time.Second)) err = Respond(resp, ByDiscardingBody(), ByClosing()) ``` 每个阶段都依赖于装饰器来修改和/或管理处理过程。装饰器可以先修改然后再传递数据，或者先传递数据然后再修改结果，或者将自己包裹在数据传递过程之外（例如记录器可能会这样做）。装饰器按提供的顺序运行。例如，以下代码： ``` req, err := Prepare(&http.Request{}, WithBaseURL("https://microsoft.com/"), WithPath("a"), WithPath("b"), WithPath("c")) ``` 会将 URL 设置为： ``` https://microsoft.com/a/b/c ``` 装饰器将传递的状态保存在闭包中（例如上例中的路径组件）。请小心，仅在适用于此类保留状态的上下文中共享 Preparer 和 Responder。例如，共享一个从一组固定值中应用查询字符串的 Preparer 可能没有意义。同样，共享一个将响应主体读取到传递的结构体中的 Responder（例如 `ByUnmarshallingJson`）可能是不正确的。 由 autorest 对象和方法引发的错误将符合 `autorest.Error` 接口。 有关更多详细信息，请参阅包含的示例。有关生成的客户端建议如何使用此包的详细信息，请参阅下面描述的 Client。 ### 辅助工具 #### 处理 Swagger 日期 驱动 AutoRest (https://github.com/Azure/autorest/) 的 Swagger 规范 (https://swagger.io) 精确定义了两种日期形式：date 和 date-time。 github.com/Azure/go-autorest/autorest/date 包提供了 time.Time 的派生类型，以确保正确的解析和格式化。 #### 处理空值 在 JSON 中，缺失值与空值具有不同的语义。对于使用 HTTP PATCH 动词的服务来说尤其如此。随 PATCH 请求提交的 JSON 通常只包含需要修改的值。缺失的值应保持不变。因此，开发者需要一种方法，既能指定空值，又能将值排除在提交的 JSON 之外。 Go JSON 包（`encoding/json`）支持 `omitempty` 标签。如果指定了该标签，它将从渲染的 JSON 中省略空值。由于 Go 为所有基本类型定义了默认值（例如 string 的 "" 和 int 的 0），并且没有提供将值标记为真正空值的方法，因此 JSON 包会将默认值视为空值，并将其从渲染的 JSON 中省略。这意味着，使用通过默认 JSON 包编码的 Go 基本类型，无法创建在服务器端清除值的 JSON。 ``` s := struct { S *string }{ S: &"foo" } ``` 会失败，而这段代码 ``` v := "foo" s := struct { S *string }{ S: &v } ``` 会成功。 为了简化指针的使用，子包 `to` 包含了一些辅助函数，用于在具有 Swagger 类似物的 Go 基本类型之间转换指针。它还提供了一个辅助函数，用于在 `map[string]string` 和 `map[string]*string` 之间进行转换，使得 JSON 能够指定应清除与某个键关联的值。使用这些辅助函数，前面的示例将变为 ``` s := struct { S *string }{ S: to.StringPtr("foo") } ``` ## 安装 ``` go get github.com/Azure/go-autorest/autorest go get github.com/Azure/go-autorest/autorest/azure go get github.com/Azure/go-autorest/autorest/date go get github.com/Azure/go-autorest/autorest/to ``` #### 与 Go Modules 结合使用 在 [v12.0.1](https://github.com/Azure/go-autorest/pull/386) 中，此仓库引入了以下模块。 - autorest/adal - autorest/azure/auth - autorest/azure/cli - autorest/date - autorest/mocks - autorest/to - autorest/validation - autorest - logger - tracing ### 许可证 请参阅 LICENSE 文件。 本项目已采用 [Microsoft 开源行为准则](https://opensource.microsoft.com/codeofconduct/)。了解更多信息，请参阅[行为准则常见问题解答](https://opensource.microsoft.com/codeofconduct/faq/)，或联系 [opencode@microsoft.com](mailto:opencode@microsoft.com) 提出任何其他问题或意见。

标签：日志审计