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

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

版本：8\.2\.0
npm 元数据更新时间：2026-11-12T09:58:40.505Z
中文译文更新时间：2026-11-13T20:20:47.247Z
软件包许可：ISC

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

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

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

- 包体积（解压后）：739 kB，394 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：4 个
- peer 依赖：odata-query ^8\.0\.0，@equinor/fusion-framework-module ^6\.2\.0
- 首次发布：2022-10-03T06:26:30.564Z
- 最新版本发布：2026-11-12T09:58:40.226Z
- 近 30 天下载量：9298（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：165（近 12 个月 24 个）

## 中文简介

暂无中文简介

## 安装

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

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

## README

# @ equinor/ 组合框架- 模块- 服务

为Fusion框架所打入的API服务客户端. 提供基于工厂的平台后端服务访问(app state,书签,上下文,通知,人),有版本端点,自动HTTP客户端解析,以及响应验证.

## 特征

-   **域特有 API 客户端** —— 说 `AppStateApiClient`, (中文(简体) ), `BookmarksApiClient`, (中文(简体) ), `ContextApiClient`, (中文(简体) ), `NotificationApiClient`, (中文(简体) ), `PeopleApiClient`
-   **版本终点** ——每个服务都暴露出有版本意识的方法(如. `v1`, (中文(简体) ), `v2`, (中文(简体) ), `v4`)带有类型安全请求/响应形状
-   **双重消费模式** - 每一个终点都支持 `Promise` (单位:千美元)`json`)和可观测(`json$`返回类型
-   **自动 HTTP 客户端解析** ——通过HTTP模块解决被命名客户端,回归服务发现
-   **反应验证** ——内置响应处理器验证HTTP状态代码并抛出结构化 `ApiProviderError` 失败时
-   **Zod 计划选择器** —— 说 `schemaSelector` 用 Zod 计程器解析运行时响应的工具
-   **书签 Zod 计划** 预先建造的Zod计划`ApiBookmarkSchema`, (中文(简体) ), `ApiBookmarkPayload`用于书签实体

## 安装

```sh
pnpm add @equinor/fusion-framework-module-services
```

## 使用量

### 启用模块

在应用程序配置时注册服务模块 :

```ts
import { enableServices } from '@equinor/fusion-framework-module-services';

export const configure = (configurator) => {
  enableServices(configurator);
};
```

### 自定义客户端厂

覆盖 HTTP 客户端解析度 `configureServices`数字 :

```ts
import { configureServices } from '@equinor/fusion-framework-module-services';

export const configure = (configurator) => {
  configurator.addConfig(
    configureServices((cfg) => {
      cfg.createClient = async (name) => myHttpClientFactory(name);
    }),
  );
};
```

### 创建和使用 API 客户端

运行时访问服务提供商创建域客户端 :

```ts
// App State
const appState = await provider.services.createAppStateClient('json');
const apps = await appState.listMyApps('v1');
await appState.wipeMyAppState('v1', { appKey: 'my-app' });

// Bookmarks
const bookmarks = await provider.services.createBookmarksClient('json');
const allBookmarks = await bookmarks.query('v1');
const single = await bookmarks.get('v1', { bookmarkId: 'abc-123' });

// Context
const context = await provider.services.createContextClient('json');
const ctx = await context.get('v1', { id: 'context-id' });
const results = await context.query('v1', { query: 'my search' });

// Notifications
const notifications = await provider.services.createNotificationClient('json');
const all = await notifications.getAll('v1');
await notifications.setSeenByUser('v1', { notificationId: 'notif-id' });

// People
const people = await provider.services.createPeopleClient();
const person = await people.get('v4', 'json', { azureId: 'azure-unique-id' });
const photo = await people.photo('v2', 'blob', { azureId: 'azure-unique-id' });
```

## API 参考

### 模块设置

| 导出 | 说明 |
| --- | --- |
| `enableServices` | 用框架配置器注册服务模块 |
| `configureServices` | 创建自定义配置回调的模块配置对象 |
| `module` | 原始模块定义 |

### 提供者

| 导出 | 说明 |
| --- | --- |
| `ApiProvider` 编号 : `IApiProvider` | 拥有创建域名客户端的工厂方法的服务提供商 |
| `ApiConfigurator` 编号 : `IApiConfigurator` | 配置接口( 设置) `createClient` 以覆盖 HTTP 客户端分辨率) |
| `ApiProviderError` | 非 OK HTTP 回复时所抛出的结构错误 |

### 域客户端

| 客户端 | 导入路径 | 服务 |
| --- | --- | --- |
| `AppStateApiClient` | `@equinor/fusion-framework-module-services/app-state` | 获取/刷新自己的应用程序状态, 管理员获取/刷新每个用户或每个应用程序状态 |
| `BookmarksApiClient` | `@equinor/fusion-framework-module-services/bookmarks` | CRUD 书签,最喜欢的 |
| `ContextApiClient` | `@equinor/fusion-framework-module-services/context` | 获取、查询、相关上下文 |
| `NotificationApiClient` | `@equinor/fusion-framework-module-services/notification` | CRUD 通知、设置 |
| `PeopleApiClient` | `@equinor/fusion-framework-module-services/people` | 获取,询问,照片,建议,解决 |

### 类型和公用事业

| 导出 | 说明 |
| --- | --- |
| `ClientMethod` | 地图 `json` 编号 : `json$` 改为 `Promise` 编号 : `StreamResponse` |
| `ClientDataMethod` | 地图 `blob` 编号 : `blob$` 二进制响应 |
| `ApiClientFactory` | 用于创建命名的 HTTP 客户端的工厂函数类型 |
| `FilterAllowedApiVersions` | 用于限制 API 版本联盟的工具类型 |
| `ExtractApiVersion` | 用于解析其字符串值的版本密钥的工具类型 |
| `UnsupportedApiVersion` | 无效的 API 版本字符串错误分类 |
| `extractVersion` | 从 API-version enum 解析一个版本密钥或值 |
| `schemaSelector` | 创建使用 Zod 方案验证的响应选择器 |
| `isApiPerson` | API 版本用于验证个人实体的护卫型工厂 |

## 操作遥测

当遥测模块可用时, `ApiProvider` 记录一 `fusion.services.create-client.duration` 以它创建的 API 客户端为单位, 服务发现厂和定制工厂,其中一家已消毒 `fusion.services.create-client.failure` 无法创建客户端时除外。 服务 姓名、URI和错误从未被记录。 报告发现分辨率和HTTP尝试 由他们自己的模块.

## 配置

服务单元取决于:

-   **`@equinor/fusion-framework-module-http`** ——提供命名的HTTP客户端
-   **`@equinor/fusion-framework-module-service-discovery`** (可选)——通过服务发现自动客户端解析

当注册的HTTP客户端或服务发现无法为服务名称提供时,模块会在客户端创建过程中抛出错误.

## 常见问题

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

在项目目录运行 npm install @equinor/fusion-framework-module-services，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：odata-query（^8\.0\.0）、@equinor/fusion-framework-module（^6\.2\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

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

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

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

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

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

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

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

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

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

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