@gravity-ui/expresskit

中文文档
3.4.0发布于 2026/11/02MITTypeScriptCommonJS近 30 天下载 3.6万

Express.js 基于节点Kit的应用程序的包装器

中文使用文档
文档目录11 节
  1. 自我遥测
  2. 社区支助方案
  3. CSRF 保护
  4. 基本配置
  5. 配置选项
  6. 使用量
  7. Per- Route 配置
  8. 缓存控制
  9. 全球配置
  10. 每个路线配置
  11. 验证和响应序列化

快捷键

ExpressKit是轻量级 表达式.js 与 节点Kit 并提供了一些有用的特性,如请求日志,追踪支持,同源控制器和中间软件以及动词路由描述等.

安装 :

npm install --save @gravity-ui/nodekit @gravity-ui/expresskit

基本用途:

import {ExpressKit} from '@gravity-ui/expresskit';
import {NodeKit} from '@gravity-ui/nodekit';

const nodekit = new NodeKit();

const app = new ExpressKit(nodekit, {
  'GET /': (req, res) => {
    res.send('Hello World!');
  },
});

app.run();

自我遥测

默认情况下,自测会发送原始请求 URL. 大型或 高心率查询字符串可以在发送数据前剥去查询参数:

const config: Partial<AppConfig> = {
  appTelemetryChEnableSelfStats: true,
  appTelemetryChSelfStatsStripQueryParams: true,
};

社区支助方案

config.ts

import type {AppConfig} from '@gravity-ui/nodekit';
import {csp} from '@gravity-ui/expresskit';

const config: Partial<AppConfig> = {
    expressCspEnable: true,
    expressCspPresets: ({getDefaultPresets}) => {
        return getDefaultPresets({defaultNone: true}).concat([
            csp.inline(),
            {csp.directives.REPORT_TO: 'my-report-group'},
        ]);
    },
    expressCspReportTo: [
        {
            group: 'my-report-group',
            max_age: 30 * 60,
            endpoints: [{ url: 'https://cspreport.com/send'}],
            include_subdomains: true,
        }
    ]
}

export default config;

CSRF 保护

ExpressKit提供内置的 Cross-Site Creat Forgery (CSRF) 保护,以保护您的应用程序免受恶意的交叉源请求. CSRF中间软件会自动生成并验证用于改变状态的HTTP请求的令牌.

基本配置

为了启用 CSRF 保护, 请在配置中配置密钥 :

import type {AppConfig} from '@gravity-ui/nodekit';

const config: Partial<AppConfig> = {
  // ...
  appCsrfSecret: 'your-secret-key-here',
};

export default config;

配置选项

选项类型默认说明
appCsrfSecretstring | string[]- 说吧要求. HMAC 令牌生成的秘密密钥 。 多个秘密允许密钥旋转.
appCsrfLifetimenumber2592000 (30天) (中文(简体) )几秒钟内就结束了 设定为 0 没有过期.
appCsrfHeaderNamestring'x-csrf-token'HTTP 符号验证头名 .
appCsrfMethodsstring[]['POST', 'PUT', 'DELETE', 'PATCH']需要CSRF验证的HTTP方法.

使用量

配置后, CSRF 保护会自动应用到所有带有指定 HTTP 方法的路径:

import {ExpressKit, AuthPolicy} from '@gravity-ui/expresskit';
import {NodeKit} from '@gravity-ui/nodekit';

const nodekit = new NodeKit({
  config: {
    appCsrfSecret: 'your-secret-key',
    appAuthPolicy: AuthPolicy.required,

    // Ensure that your middleware sets user id to the originalContext, otherwise CSRF token generation will fail
    appAuthHandler: yourAuthHandler,
  },
});

const app = new ExpressKit(nodekit, {
  'GET /api/form': (req, res) => {
    // Token is available in request context
    res.json({csrfToken: req.originalContext.get('csrfToken')});
  },

  'POST /api/submit': (req, res) => {
    // This route automatically validates CSRF token
    res.json({message: 'Form submitted successfully'});
  },
});

Per- Route 配置

您可以为特定路径禁用 CSRF 保护 :

const app = new ExpressKit(nodekit, {
  'POST /api/webhook': {
    authPolicy: AuthPolicy.required,
    disableCsrf: true, // Disable CSRF for this route
    handler: (req, res) => {
      res.json({message: 'Webhook processed'});
    },
  },
});

缓存控制

默认情况下, ExpressKit 集 no-cache 所有回复都标注在信头上。 你可以在全球控制这种行为,也可以按路线控制.

全球配置

const config: Partial<AppConfig> = {
  expressEnableCaching: true, // Allow caching by default
};

每个路线配置

const app = new ExpressKit(nodekit, {
  'GET /api/cached': {
    enableCaching: true, // Allow caching for this route
    handler: (req, res) => res.json({data: 'cacheable'}),
  },
  'GET /api/fresh': {
    enableCaching: false, // Force no-cache
    handler: (req, res) => res.json({data: 'always fresh'}),
  },
});

路线级别 enableCaching 覆盖全局设置 。 缓存状态可见于 req.routeInfo.enableCaching。 。 。 .

验证和响应序列化

版本与发布记录

@gravity-ui/expresskit 共发布 42 个版本,首次发布于 2023/02/22;过去 12 个月发布了 12 个版本。

版本发布日期距今
3.4.0latest2026/11/0214 天前
3.3.02026/10/2720 天前
3.2.02026/09/142 个月前
3.1.32026/05/285 个月前
3.1.22026/05/185 个月前
3.1.12026/05/136 个月前

关于 @gravity-ui/expresskit 的常见问题

@gravity-ui/expresskit 是什么?

Express.js 基于节点Kit的应用程序的包装器

如何安装 @gravity-ui/expresskit?

在项目目录运行 npm install @gravity-ui/expresskit,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:@gravity-ui/nodekit(^1.6.0 || ^2.0.0)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@gravity-ui/expresskit 支持 TypeScript 吗?

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

@gravity-ui/expresskit 支持 ESM 还是 CommonJS?

以 CommonJS 形式发布,可以直接 require();在 ES Module 项目中也可以用 import 引入(Node.js 会把 module.exports 作为默认导出)。

@gravity-ui/expresskit 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=20。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@gravity-ui/expresskit 可以商用吗?

@gravity-ui/expresskit 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@gravity-ui/expresskit 的下载量有多少?

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

@gravity-ui/expresskit 还在维护吗?

最新版本 3.4.0 发布于 2026/11/02(14 天前);至今共发布 42 个版本,其中过去 12 个月发布了 12 个;首次发布于 2023/02/22。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。