@gravitee/gamma-modules-sdk

中文文档
1.4.0发布于 2026/10/11Apache-2.0TypeScriptES Module近 30 天下载 2.5万

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

中文使用文档
文档目录19 节
  1. 安装
  2. 分支
  3. 建筑
  4. 远程使用
  5. 东道方执行
  6. 模块联盟配置
  7. 出口
  8. 模拟中件( M) /mock (中文(简体) )
  9. 权限域
  10. 许可证域
  11. 环境领域
  12. 排队( /routing (中文(简体) )
  13. 发展
  14. 先决条件
  15. 图标
  16. 伽马孔局部发展
  17. 捐款
  18. 释放
  19. 许可证

翻译:

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

安装

yarn add @gravitee/gamma-modules-sdk

分支

main 是默认分支和释放行。 分支特色工作来自 main合并为 main 通过 npm 发布稳定版本 语义释放。 。 。 .

建筑

SDK发布4个切入点:

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

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

远程使用

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 路径覆盖所捕获) 执行编译时遵守合同 :

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为共享单子:

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

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

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

出口

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

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

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数字 :
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;
      },
    ],
  },
}));
  1. 运行 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 将其缩入模块的路由键, 因此不需要铸入 :

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中,使用 gck 伽玛语境。 。 。 .

图标

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 语录 有固定和 高级 以格式化树.

伽马孔局部发展

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

# In this repo
yarn build
yarn link

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

捐款

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

释放

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

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

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

许可证

Apache 2.0 (英语)

版本与发布记录

@gravitee/gamma-modules-sdk 共发布 140 个版本,首次发布于 2026/04/23;过去 12 个月发布了 140 个版本。

版本发布日期距今
1.4.0latest2026/10/111 个月前
1.3.0-feat-ai-workspace-permission-scope.1239e66prerelease2026/10/111 个月前
1.3.02026/10/091 个月前
1.2.1-feat-found-314-href-for-key.347df182026/10/091 个月前
1.2.1-feat-found-314-href-for-key.6d58d3c2026/10/091 个月前
1.2.1-feat-found-314-href-for-key.86fd9402026/10/091 个月前

其他发布通道:alpha → 1.0.0-alpha.15,prerelease → 1.3.0-feat-ai-workspace-permission-scope.1239e66。

关于 @gravitee/gamma-modules-sdk 的常见问题

@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 和提交记录判断。