# @gravitee/gamma-modules-sdk 中文文档

规范地址：https://npmcn.com/package/%40gravitee/gamma-modules-sdk/

版本：1\.4\.0
npm 元数据更新时间：2026-10-10T18:45:00.998Z
中文译文更新时间：2026-11-16T23:30:14.500Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40gravitee/gamma-modules-sdk
原文对照：https://npmcn.com/package/%40gravitee/gamma-modules-sdk/?lang=original

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

- 包体积（解压后）：179 kB，39 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：react \>=19，react-dom \>=19，react-router-dom \>=6
- 首次发布：2026-04-23T08:52:39.737Z
- 最新版本发布：2026-10-10T18:45:00.846Z
- 近 30 天下载量：24948（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：140（近 12 个月 140 个）

## 中文简介

Gamma主机(gamma-console)和联邦远程模块之间的共享合同. 提供类型,接口,和运行时间的分位符,在运行时间被主机通过模块联合会实际执行所取代.

## 安装

```sh
npm install @gravitee/gamma-modules-sdk
```

也可以使用：`pnpm add @gravitee/gamma-modules-sdk`、`yarn add @gravitee/gamma-modules-sdk`、`bun add @gravitee/gamma-modules-sdk`

## README

# 翻译:

Gamma主机(gamma-console)和联邦远程模块之间的共享合同. 提供类型,接口,和运行时间的分位符,在运行时间被主机通过模块联合会实际执行所取代.

## 安装

```bash
yarn add @gravitee/gamma-modules-sdk
```

## 分支

`main` 是默认分支和释放行。 分支特色工作来自 `main`合并为 `main` 通过 npm 发布稳定版本 [语义释放](https://github.com/semantic-release/semantic-release)。 。 。 .

## 建筑

SDK发布4个切入点:

| 入境点 | 目录 | 用于 |
| --- | --- | --- |
| `@gravitee/gamma-modules-sdk` | 类型 + 运行时间根 | 遥控器(和主机管) |
| `@gravitee/gamma-modules-sdk/types` | 只有接口( 无运行时间) | 东道方执行 |
| `@gravitee/gamma-modules-sdk/routing` | 模块路由帮助 | 远程 |
| `@gravitee/gamma-modules-sdk/mock` | OpenAPI 模拟中间软件 | 模块dev 服务器 |

远程模块编译并捆绑在根上. 在运行时,东道主作为模块联合会单子提供其实际执行(`additionalShared`),透明地替换了根根.

### 远程使用

```typescript
import { useHasPermission, PermissionGate } from '@gravitee/gamma-modules-sdk';

function MyPage() {
  const canEdit = useHasPermission({ anyOf: ['environment-api-u'] });
  return (
    <PermissionGate anyOf={['environment-api-r']}>
      <p>Protected content</p>
    </PermissionGate>
  );
}
```

### 东道方执行

主机导入界面 `/types` 子路径( 即 **没有** 由 rspack 化名或 tsconfig 路径覆盖所捕获) 执行编译时遵守合同 :

```typescript
import type { IPermissionService, PermissionScope } from '@gravitee/gamma-modules-sdk/types';

export class PermissionService implements IPermissionService {
  load(scope: PermissionScope, permissions: string[]): void {
    /* ... */
  }
  // TypeScript will error if any method is missing or has wrong signature
}
```

### 模块联盟配置

主机和远程都宣布SDK为共享单子:

```typescript
additionalShared: [
  ['@gravitee/gamma-modules-sdk', { singleton: true, requiredVersion: false, strictVersion: false }],
],
```

主机的 rspack 配置使用 **精确匹配** 使亚路径进口(`/types`解决 `node_modules`数字 :

```javascript
resolve: {
  alias: {
    '@gravitee/gamma-modules-sdk$': gammaModulesSdkEntry, // note the $ for exact match
  },
},
```

## 出口

### 模拟中件( M)`/mock`(中文(简体) )

OpenAPI基于独立dev模式的模拟中间软件. 读取OpenAPI specs并服务自固定文件的模拟响应,因此模块可以在没有后端的情况下运行.

```typescript
import { createOpenApiMockMiddleware } from '@gravitee/gamma-modules-sdk/mock';

// In rsbuild.config.ts setupMiddlewares:
createOpenApiMockMiddleware({
  moduleId: 'aim',
  specs: [join(__dirname, 'src/main/resources/openapi/openapi-catalog.yaml')],
  fixturesDir: join(__dirname, 'src/main/resources/catalog-fixtures'),
});
```

处理 获取列表( Pagement, `?q=` 搜索),通过ID、子资源过滤、POST、PUT、DELETE和 `/gamma/ui/bootstrap` 终点.

Fixture 文件以光谱中最后一个路径段命名(例如. `models.json`, (中文(简体) ), `mcp-servers.json`) (中文(简体) ).

#### 为新模块建立独立的 dev 模式

1.  添加 `public/constants.json` 与 `{ "gammaBaseURL": "/gamma" }`
2.  写入您的 OpenAPI 光谱( 从已有模块复制)
3.  添加匹配您光谱路径的固定 JSON 文件( 例如 ). `models.json` 页:1 `/catalog/models`(中文(简体) )
4.  单位 `rsbuild.config.ts`数字 :

```typescript
import { createOpenApiMockMiddleware } from '@gravitee/gamma-modules-sdk/mock';

export default defineConfig(() => ({
  dev: {
    setupMiddlewares: [
      (middlewares) => {
        middlewares.unshift(
          createOpenApiMockMiddleware({
            moduleId: 'your-module',
            specs: [join(__dirname, 'path/to/openapi.yaml')],
            fixturesDir: join(__dirname, 'path/to/fixtures'),
          }),
        );
        return middlewares;
      },
    ],
  },
}));
```

5.  运行 `yarn serve` 并开放 http://localhost:302

### 权限域

**类型**数字 : `PermissionScope`, (中文(简体) ), `PermissionCheck`, (中文(简体) ), `UserRole`, (中文(简体) ), `PermissionGateProps`, (中文(简体) ), `UseHasPermissionOptions`

**接口** (从) `/types`: `IPermissionService`, (中文(简体) ), `UseHasPermissionFn`, (中文(简体) ), `PermissionGateFn`, (中文(简体) ), `NormalizeCrudMapRecordFn`, (中文(简体) ), `NormalizeOrgPermissionsFn`

**积分**数字 : `PermissionService`, (中文(简体) ), `permissionService`, (中文(简体) ), `useHasPermission`, (中文(简体) ), `PermissionGate`, (中文(简体) ), `normalizeCrudMapRecord`, (中文(简体) ), `normalizeOrganizationPermissionsFromRoles`

### 许可证域

**类型**数字 : `License`

**接口** (从) `/types`: `ILicenseService`, (中文(简体) ), `UseHasFeatureFn`, (中文(简体) ), `UseHasPackFn`

**积分**数字 : `LicenseService`, (中文(简体) ), `licenseService`, (中文(简体) ), `useHasFeature`, (中文(简体) ), `useHasPack`

### 环境领域

**类型**数字 : `Environment`

**接口** (从) `/types`: `IEnvironmentService`, (中文(简体) ), `UseEnvironmentFn`

**积分**数字 : `EnvironmentService`, (中文(简体) ), `environmentService`, (中文(简体) ), `useEnvironment`

### 排队(`/routing`(中文(简体) )

联邦单元的助手 `/environments/:envHrid/:moduleId/<routePath>`数字 : `ModuleRouteConfig`, (中文(简体) ), `useModuleRouting`, (中文(简体) ), `useToHref`, (中文(简体) ), `isRouteKey`。 。 。 .

`useModuleRouting(config)` 给每个路线按键一个目的地,由链接和单击使用:

-   `pathForKey(key)`: 路由器路径,用于 `navigate()` 财务报告和审定财务报表 `<Link to>`。 。 。 .
-   `hrefForKey(key)`: 路由器基道下相同的路径,用于 `<a href>` 可以在新标签中打开.
-   `navigateToKey(key)`数字 : `navigate(pathForKey(key))`。 。 。 .

三把钥匙都丢掉了 `config.routes`。 。 。 . `hrefForKey` 在导航构建时运行, 因此未知的密钥会失败渲染, 不仅仅是点击: 守护非路径的导航项目( 如外部链接) `isRouteKey`。 。 。 .

解决其活动项本身的模块仍然可以使用 `useModuleRouting` 他们将受刑罚 `activeNavKey`模块,其点击通过一个守卫(如未保存的更改提示)应当通过 `pathForKey(key)` 导航系统,而不是使用 `navigateToKey`,它叫回声路由器 `navigate` 直接说.

`useToHref()` 返回将路由器的基础路径前缀为绝对路由器路径的函数,用于 `<a href>` 或相片的面包屑b `toHref` 选项。 它不需要路由配置。 路径必须从 `/`,而相对路径抛出: Graphene 选项允许相对 `to`但钩子不知道 `navigate` 根据路由或 URL 解析它, 所以给 crumbs 绝对 `to` (例如来自 `pathForKey`) (中文(简体) ).

图形类型 : `string`。 。 。 . `isRouteKey` 将其缩入模块的路由键, 因此不需要铸入 :

```tsx
const { activeNavKey, hrefForKey, navigateToKey } = useModuleRouting(ROUTE_CONFIG);
const toHref = useToHref();
const groups = NAV_GROUPS.map((group) => ({
  ...group,
  items: group.items.map((item) =>
    isRouteKey(item.key, ROUTE_CONFIG.routeKeys) ? { ...item, href: hrefForKey(item.key) } : item,
  ),
}));
<SidebarNavigation
  groups={groups}
  activeItemKey={activeNavKey}
  onItemSelect={(key) => isRouteKey(key, ROUTE_CONFIG.routeKeys) && navigateToKey(key)}
/>;
buildLinearBreadcrumbs(navigate, segments, { toHref });
```

## 发展

### 先决条件

-   节点.js 24+(见 `.nvmrc`(中文(简体) )
-   Yarn 4(通过Corepack启用)

一个完整的本地伽玛堆栈 [插头/README.md](https://npmcn.com/package/%40gravitee/gamma-modules-sdk/docker/README.md)中,使用 [gck 伽玛语境](https://gravitee-io-labs.github.io/gck/registry/gravitee-io/ee/gamma/)。 。 。 .

### 图标

```bash
yarn install          # Install dependencies
yarn build            # Typecheck + Vite build
yarn test             # Vitest
yarn lint             # ESLint
yarn lint:fix:all     # ESLint --fix, Prettier write
yarn format:check     # Prettier check
yarn typecheck        # TypeScript only
```

为了在拉动请求前进行全面的局部检查, `yarn lint:fix:all` 运行 [ESLint 语录](https://eslint.org/) 有固定和 [高级](https://prettier.io/) 以格式化树.

### 伽马孔局部发展

将 SDK 更改与主机或远程同步进行, 不发布 :

```bash
# In this repo
yarn build
yarn link

# In gravitee-api-management
yarn link @gravitee/gamma-modules-sdk
```

### 捐款

1.  分行从 `main`,并打开拉动请求
2.  使用 [常规武器委员会](https://www.conventionalcommits.org/) 用于执行消息
3.  在特征分支上, CI 运行 Lint, 排字检查, 构建, 测试, 以及分支扫描 npm 预放
4.  合并为 `main` 发布 a **稳定** 通过语义释放在npm上的版本

### 释放

自动打开 **`main`** 通过语义释放.

该版本取自常规承诺信息:

-   `fix:` - > 补丁
-   `feat:` - > 未成年人
-   `feat!:` 或者说 `BREAKING CHANGE:` - > 主要

## 许可证

[Apache 2.0 (英语)](https://npmcn.com/package/%40gravitee/gamma-modules-sdk/LICENSE.txt)

## 常见问题

### @gravitee/gamma-modules-sdk 是什么？

Gamma主机\(gamma-console\)和联邦远程模块之间的共享合同\. 提供类型,接口,和运行时间的分位符,在运行时间被主机通过模块联合会实际执行所取代\.

### 如何安装 @gravitee/gamma-modules-sdk？

在项目目录运行 npm install @gravitee/gamma-modules-sdk，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=19）、react-dom（\>=19）、react-router-dom（\>=6）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @gravitee/gamma-modules-sdk 支持 TypeScript 吗？

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

### @gravitee/gamma-modules-sdk 支持 ESM 还是 CommonJS？

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

### @gravitee/gamma-modules-sdk 可以商用吗？

@gravitee/gamma-modules-sdk 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @gravitee/gamma-modules-sdk 的下载量有多少？

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

### @gravitee/gamma-modules-sdk 还在维护吗？

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

