ts-http-运行时

这是由 @azure-tools/typespec-ts生成的包的运行时依赖关系。 它旨在成为一个与云无关的库，用于在运行时促进 HTTP 请求。

入门指南

要求

当前支持的环境

• LTS 版本的 Node.js
• Safari、Chrome、Edge 和 Firefox 的最新版本。

详情请参见我们的支持政策。

安装

此包主要用于生成的代码中，不应由最终用户直接使用。 只应使用此包中的顶级导出。 subpath internal 下的任何导出都供私人使用，并且不能保证稳定性。

重要概念

管道请求

PipelineRequest 描述了向 HTTP REST 终结点发出请求所需的所有信息。

管道响应

PipelineResponse 描述发出 HTTP 请求后返回的 REST 终结点的 HTTP 响应（正文、标头和状态代码）。

发送请求

SendRequest 方法是一种给定 PipelineRequest 可以异步返回 PipelineResponse的方法。

import { PipelineRequest, PipelineResponse } from "@typespec/ts-http-runtime";

type SendRequest = (request: PipelineRequest) => Promise<PipelineResponse>;

Http客户端

HttpClient 是满足以下接口实现 SendRequest 方法的任何对象：

import { SendRequest } from "@typespec/ts-http-runtime";

interface HttpClient {
  /**
   * The method that makes the request and returns a response.
   */
  sendRequest: SendRequest;
}

HttpClient实际上会使用一些特定于平台的机制向服务器终结点发出 HTTP 请求。

管道策略

PipelinePolicy 是实现以下接口的简单对象：

import { PipelineRequest, SendRequest, PipelineResponse } from "@typespec/ts-http-runtime";

interface PipelinePolicy {
  /**
   * The policy name. Must be a unique string in the pipeline.
   */
  name: string;
  /**
   * The main method to implement that manipulates a request/response.
   * @param request - The request being performed.
   * @param next - The next policy in the pipeline. Must be called to continue the pipeline.
   */
  sendRequest(request: PipelineRequest, next: SendRequest): Promise<PipelineResponse>;
}

它的形状类似于 HttpClient，但包括策略名称以及稍微修改的 SendRequest 签名，允许它有条件地调用管道中的下一个策略。

人们可以将策略的角色视为 middleware的角色，而 NodeJS 开发人员熟悉该概念，这些开发人员曾使用过 Express等框架。

sendRequest 实现可以转换传出请求和传入响应：

import { PipelineRequest, SendRequest, PipelineResponse } from "@typespec/ts-http-runtime";

const customPolicy = {
  name: "My wonderful policy",
  async sendRequest(request: PipelineRequest, next: SendRequest): Promise<PipelineResponse> {
    // Change the outgoing request by adding a new header
    request.headers.set("X-Cool-Header", 42);
    const result = await next(request);
    if (result.status === 403) {
      // Do something special if this policy sees Forbidden
    }

    return result;
  },
};

大多数策略只关注请求或响应，但也有一些例外，如LogPolicy会记录各自的信息。

Pipelines

Pipeline 是管理一组 PipelinePolicy 对象的对象。 其主要功能是确保策略按一致且可预测的顺序执行。

可以将策略视为像堆栈一样应用（先入/最后一出）。第一个 PipelinePolicy 能够在任何其他策略之前修改 PipelineRequest，也是最后一个修改 PipelineResponse，使其最接近调用方。 最后一个策略是最后一个能够修改传出请求，第一个可以处理响应，使其最接近网络。

Pipeline 满足以下接口：

import {
  PipelinePolicy,
  AddPolicyOptions,
  PipelinePhase,
  HttpClient,
  PipelineRequest,
  PipelineResponse,
} from "@typespec/ts-http-runtime";

interface Pipeline {
  addPolicy(policy: PipelinePolicy, options?: AddPolicyOptions): void;
  removePolicy(options: { name?: string; phase?: PipelinePhase }): PipelinePolicy[];
  sendRequest(httpClient: HttpClient, request: PipelineRequest): Promise<PipelineResponse>;
  getOrderedPolicies(): PipelinePolicy[];
  clone(): Pipeline;
}

正如你所看到的，它允许添加或删除策略，并且它与 HttpClient 松散耦合，以执行对服务器终结点的实际请求。

Pipeline的一个重要概念是，它们将策略分组到有序阶段：

1. 序列化阶段
2. 策略不在阶段
3. 反序列化阶段
4. 重试阶段

阶段按上述顺序发生，先应用序列化策略，最后应用重试策略。 大多数自定义策略都属于第二个存储桶，未提供阶段名称。

将策略添加到管道时，不仅可以指定策略处于哪个阶段，还可以指定策略具有任何依赖项：

import { PipelinePhase } from "@typespec/ts-http-runtime";

interface AddPipelineOptions {
  beforePolicies?: string[];
  afterPolicies?: string[];
  afterPhase?: PipelinePhase;
  phase?: PipelinePhase;
}

beforePolicies 是新策略之前必须执行的策略，afterPolicies 是新策略之后必须发生的策略。 同样，afterPhase 意味着策略只能在指定阶段发生后执行。

此语法允许自定义策略作者在使用 @typespec/ts-http-runtime创建管道时表达其自己的策略与 createPipelineFromOptions 提供的内置策略之间的任何必要关系。

实现者还可以按名称或阶段删除策略，以防他们希望修改现有 Pipeline，而无需使用 createEmptyPipeline创建新策略。 重新创建 clone 而不修改原始方法时，Pipeline 方法特别有用。

满足所有其他约束后，策略将按添加的顺序应用。

例子

可以在 samples 文件夹中找到示例。

后续步骤

可以通过执行 npm run test在本地生成和运行测试。 浏览 test 文件夹以查看公共类的高级用法和行为。

故障排除

如果您在使用该库时遇到问题，请随时file问题。

贡献

如果你想为本库贡献内容，请阅读 贡献指南，了解更多关于如何构建和测试代码的信息。