# @equinor/fusion-framework-module-http 中文文档

规范地址：https://npmcn.com/package/%40equinor/fusion-framework-module-http/

版本：8\.1\.5
npm 元数据更新时间：2026-11-12T09:56:42.331Z
中文译文更新时间：2026-11-13T20:09:28.741Z
软件包许可：ISC

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40equinor/fusion-framework-module-http
原文对照：https://npmcn.com/package/%40equinor/fusion-framework-module-http/?lang=original
源码仓库：https://github.com/equinor/fusion-framework

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：466 kB，106 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：4 个
- 首次发布：2022-01-14T12:18:14.570Z
- 最新版本发布：2026-11-12T09:56:42.020Z
- 近 30 天下载量：14405（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：183（近 12 个月 24 个）

## 中文简介

暂无中文简介

## 安装

```sh
npm install @equinor/fusion-framework-module-http
```

也可以使用：`pnpm add @equinor/fusion-framework-module-http`、`yarn add @equinor/fusion-framework-module-http`、`bun add @equinor/fusion-framework-module-http`

## README

# 组合框架 HTTP 模块

`@equinor/fusion-framework-module-http` 是Fusion框架应用程序和模块的HTTP层。 它给了你一个有框架感知配置, MSAL感知请求, RxJS 观察器以及可重复使用的请求/响应管道的取取式客户端工厂.

如果您只记得关于此软件包的一件事, 请做这个: 您配置过一次客户端, 并在使用时创建新的客户端实例 .

如果您是新到Fusion框架, 或者只是想呼叫 API, 请从 `configureHttpClient(...)`, (中文(简体) ), `createClient(...)`,以及 `json()`。 。 。 .

如果您正在构建更高级的工作流程,此软件包也会支持 RxJS 的可观测组成,请求和响应流检查,自定义选择器,请求和响应操作器, MSAL 意识请求,以及服务器发送事件.

## 这个软件包给你什么

-   为您交谈的后端指定 HTTP 客户端配置 .
-   新的客户端实例,所以从一种用法发出的头和处理器不会漏入另一种用法.
-   承诺和可观察API在同一请求管道上.
-   内建支持JSON,blobs,和服务器发送事件.
-   交叉行为的请求和响应处理者.
-   当认证模块可用时, MSAL 范围支持 .

## 心理模式

将HTTP模块视为客户端工厂,而不是单通HTTP客户端.

1.  在应用程序或模块设置时配置一个命名的客户端 .
2.  打电话 `createClient(name)` 当你需要提出请求.
3.  使用 `fetch`, (中文(简体) ), `json`, (中文(简体) ), `blob`,或 `sse$` 在客户的例子.
4.  在其中添加共享行为 `onCreate`, (中文(简体) ), `requestHandler`,以及 `responseHandler`。 。 。 .

每个请求都经过同样的高层次流程:

1.  决定 `baseUri` 并请求路径进入完整的 URL.
2.  运行请求处理器 .
3.  发送请求 `request$`。 。 。 .
4.  执行接取电话 .
5.  运行响应处理器.
6.  发送回复 `response$`。 。 。 .
7.  应用可选选择器.

## 新建时在此开始

最简单的有用路径是这样的:

1.  为一个后端注册一个命名客户端 .
2.  从该名称创建客户端 .
3.  打电话 `json()` 正常API电话.

这给你:

-   一致的基础 URL
-   共享认证范围配置
-   共享信头或卫士通过 `onCreate`
-   每个用户使用一个新客户实例

如果你不确定是使用承诺还是观察,从 `json()`移动到 `json$()` 当您需要 RxJS 运算符时,通过不订阅取消,或流组成.

## 当使用哪个 API

| 需求 | 使用 |
| --- | --- |
| 调用正常的 JSON API | `json()` 或者说 `json$()` |
| 与生俱来 `Response` | `fetch()` 或者说 `fetch$()` |
| 下载文件或 blob 响应 | `blob()` 或者说 `blob$()` |
| 设定流线 `text/event-stream` 结束点 | `sse$()` |
| 每个后端应用标准页眉、范围或日志 | 命名客户端配置 + `onCreate` |

## 安装

```bash
pnpm add @equinor/fusion-framework-module-http
```

## 快速启动

设置时配置一个命名客户端 :

```typescript
configurator.configureHttpClient('catalog', {
  baseUri: '/api/catalog',
  defaultScopes: ['api://catalog-api/.default'],
  onCreate: (client) => {
    client.requestHandler.setHeader('X-App-Name', 'portal');
  },
});
```

初始化框架后使用配置的客户端 :

```typescript
type CatalogItem = {
  id: string;
  title: string;
};

const client = framework.modules.http.createClient('catalog');
const items = await client.json<CatalogItem[]>('/items');
```

这里发生什么了

-   `catalog` 是一个命名的配置,而不是一个长寿的共享客户端实例.
-   `createClient('catalog')` 创建新客户端, 包含配置的基础 URI, 处理器和默认范围 .
-   `json()` 运行请求的管道并返回解析的 JSON.

## 公共条目

| 入境点 | 目的 |
| --- | --- |
| `@equinor/fusion-framework-module-http` | 模块定义、配置/提供者帮助、导出错误和共享客户端类型 |
| `@equinor/fusion-framework-module-http/client` | `HttpClient`, (中文(简体) ), `HttpClientMsal`类型 |
| `@equinor/fusion-framework-module-http/operators` | `HttpRequestHandler`, (中文(简体) ), `HttpResponseHandler`, (中文(简体) ), `ProcessOperators`, (中文(简体) ), `capitalizeRequestMethodOperator`, (中文(简体) ), `requestValidationOperator`, (中文(简体) ), `sseMap`类型 |
| `@equinor/fusion-framework-module-http/selectors` | `jsonSelector`, (中文(简体) ), `blobSelector`, (中文(简体) ), `createSseSelector`, (中文(简体) ), `ResponseSelector`和 SSE 选择器类型 |
| `@equinor/fusion-framework-module-http/errors` | `HttpResponseError`, (中文(简体) ), `HttpJsonResponseError`,以及 `ServerSentEventResponseError` |

对大多数球队来说,顶级包加 `selectors` 或者说 `operators` 子路径是足够的.

## 配置客户端

需要稳定配置后端时使用命名客户端:基础URL,默认的MSAL范围,共享头,以及请求或响应政策.

HTTP模块支持三种常见的配置风格:

-   名称客户端 `configureHttpClient(name, options)`
-   低级模块配置 `configureHttp(...)`
-   临时客户端 `createClient({ baseUri })` 或者说 `createClient('https://...')`

SAML 范围行为是客户端配置的一部分:

-   `defaultScopes` 属于配置的客户端
-   按请求数 `scopes` 附录为 `defaultScopes`
-   仅当认证模块可用且最终范围列表为非空时, 才会获得符号

见 [客户端配置](https://npmcn.com/package/%40equinor/fusion-framework-module-http/docs/client-configuration.md) 用于配置选项, `onCreate`,直接模块集成,定制客户类,临时客户类,以及 `ClientNotFoundException` 行为.

## 核心 API

每次打给 `createClient()` 返回具有自己处理器状态的新实例.

| 方法 | 回返 | 用它当 |
| --- | --- | --- |
| `fetch(path, init?)` | `Promise<Response | T>` | 你想生下来 `Response`,或者您想要提供自定义选择器 |
| `fetch$(path, init?)` | `Observable<Response | T>` | 您想要通过不订阅来取消 RxJS 组成或取消 |
| `json(path, init?)` | `Promise<T>` | 你给JSON API打电话 |
| `json$(path, init?)` | `Observable<T>` | 你想要JSON API电话作为可观察 |
| `blob(path, init?)` | `Promise<BlobResult>` | 您正在下载一个文件或二进制有效载荷 |
| `blob$(path, init?)` | `Observable<BlobResult>` | 你想在可观察的管道中 做出零星的反应 |
| `sse$(path, init?, options?)` | `Observable<ServerSentEvent<T>>` | 您正在消耗服务器发送事件 |
| `execute(method, path, init?)` | `fetch`, (中文(简体) ), `fetch$`, (中文(简体) ), `json`,或 `json$` 结果 | 你得动态地选一种方法 |
| `abort()` | `void` | 您想要取消此客户端启动的每个飞行请求 |

折旧的别名仍然存在,但新的代码应该更可取 `fetch()` 财务报告和审定财务报表 `json()` 结束 `fetchAsync()` 财务报告和审定财务报表 `jsonAsync()`。 。 。 .

### 保证还是观察?

-   在您只想要单一请求的结果时使用承诺方法.
-   需要 RxJS 组成时使用可观察到的方法,通过未订阅取消,或者基于流集成.
-   可观察之法为寒. 直到你签了字,才发送任何信息.
-   采用承诺方法 `firstValueFrom(...)` 使用相应的可观察方法.
-   `request$` 财务报告和审定财务报表 `response$` 请查看用户请求和回应.

实际上:

-   `json('/items')` 是最简单的页面负荷或命令式调用选择.
-   `json$('/items')` 当请求依赖于另一个流时,例如路由参数、用户选择、已取消的搜索条件、刷新触发器或SSE事件处理时,是更好的选择.

见 [可观察模式](https://npmcn.com/package/%40equinor/fusion-framework-module-http/docs/observable-patterns.md) 用于RxJS构成、注销、请求和反应检查以及选择器再利用.

## 选择者和处理者

选择者和处理者解决不同问题:

-   选择器塑造应用程序所消耗的响应值
-   请求处理者形状向外传送行为
-   响应处理器在选择者解析运行前执行响应政策

内建选择器包括 `jsonSelector`, (中文(简体) ), `blobSelector`,以及 `createSseSelector`。默认请求管道包括 `capitalizeRequestMethodOperator()` 财务报告和审定财务报表 `requestValidationOperator()`。 。 。 .

见 [选择者和处理者](https://npmcn.com/package/%40equinor/fusion-framework-module-http/docs/selectors-and-handlers.md) 用于指导何时使用每个API,如何添加可重复使用的运算符,以及如何将运输关切与响应解析分开.

## 服务器事件

使用 `client.sse$()` 当结束点返回时 `text/event-stream` 您想要解析事件对象而不是手动读取流。 对于较低级别的构成,使用 `createSseSelector` 或者说 `sseMap`。 。 。 .

见 [服务器事件](https://npmcn.com/package/%40equinor/fusion-framework-module-http/docs/server-sent-events.md) 页:1 `sse$()` 使用、事件过滤、心跳处理、中止行为、低级SSE 助手,以及 `ServerSentEventResponseError` 处理.

## 错误类型

| 错误 | 当使用时 |
| --- | --- |
| `ClientNotFoundException` | `createClient(name)` 使用既不配置也不绝对的密钥调用 `http:` 或者说 `https:` 網址 |
| `HttpResponseError` | 一般响应或选择器失败,包括同步选择器执行失败 |
| `HttpJsonResponseError` | JSON分析失败或非OK JSON反应 |
| `ServerSentEventResponseError` | 无效的 SSE 响应, 如非 OK 状态、 无法读取的正文或错误的内容类型 |

原生取回错误也仍然可以浮出水面,包括中止和网络故障.

## 测试

注册一个短路中间软件通过 `configurator.http.addMiddleware(...)` 在不触及网络的情况下回答请求——不需要单独的模拟客户端或配置器. `createOpenApiMockMiddleware` (单位:千美元)`@equinor/fusion-framework-module-http/mock`调整一个 `@equinor/fusion-openapi-mock` 实例,用于假冒整个 OpenAPI 文档.

见 [测试](https://npmcn.com/package/%40equinor/fusion-framework-module-http/docs/testing.md) 中间软件合同和 `createOpenApiMockMiddleware`。 。 。 .

## 高级指南

-   [客户端配置](https://npmcn.com/package/%40equinor/fusion-framework-module-http/docs/client-configuration.md): 命名客户端, `configureHttpClient`, (中文(简体) ), `configureHttp`, (中文(简体) ), `onCreate`,定制客户类,以及临时客户类
-   [可观察模式](https://npmcn.com/package/%40equinor/fusion-framework-module-http/docs/observable-patterns.md)数字 : `fetch$`, (中文(简体) ), `json$`, (中文(简体) ), `request$`, (中文(简体) ), `response$`,取消,以及 RxJS 组成
-   [选择者和处理者](https://npmcn.com/package/%40equinor/fusion-framework-module-http/docs/selectors-and-handlers.md)数字 : `jsonSelector`, (中文(简体) ), `blobSelector`,请求处理器,响应处理器和内置操作器
-   [服务器事件](https://npmcn.com/package/%40equinor/fusion-framework-module-http/docs/server-sent-events.md)数字 : `sse$`, (中文(简体) ), `createSseSelector`, (中文(简体) ), `sseMap`,事件过滤、心跳和中止行为
-   [测试](https://npmcn.com/package/%40equinor/fusion-framework-module-http/docs/testing.md):中间软件合同, `addMiddleware`,以及 `createOpenApiMockMiddleware`

## 记得的事

-   `createClient(name)` 掷出 `ClientNotFoundException` 用于未知的客户端密钥.
-   `hasClient(name)` 当客户端配置可能是可选时,则有用.
-   `json()` 财务报告和审定财务报表 `json$()` 字符串对象体 `JSON.stringify(...)` 附加 JSON 请求标题.
-   `fetch()` 财务报告和审定财务报表 `fetch$()` 除非您提供 `selector`。 。 。 .
-   `execute()` 当前支持 `fetch`, (中文(简体) ), `fetch$`, (中文(简体) ), `json`,以及 `json$` 只有这个.
-   如果您通过配置客户端 `config.http.configureClient(name, callback)`,该调用存储为 `onCreate` 并运行每次创建新的客户端实例.

## 常见问题

### 如何安装 @equinor/fusion-framework-module-http？

在项目目录运行 npm install @equinor/fusion-framework-module-http，或使用 pnpm add / yarn add / bun add。

### @equinor/fusion-framework-module-http 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @equinor/fusion-framework-module-http 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @equinor/fusion-framework-module-http 可以商用吗？

@equinor/fusion-framework-module-http 使用 ISC 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @equinor/fusion-framework-module-http 的下载量有多少？

根据 npm 官方下载统计，@equinor/fusion-framework-module-http 在 2026/10/14 – 2026/11/12 这 30 天内被下载 14,405 次，日均约 480 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @equinor/fusion-framework-module-http 还在维护吗？

最新版本 8\.1\.5 发布于 2026/11/12（1 天前）；至今共发布 183 个版本，其中过去 12 个月发布了 24 个；首次发布于 2022/01/14。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。