# @gravity-ui/gateway 中文文档

规范地址：https://npmcn.com/package/%40gravity-ui/gateway/

版本：4\.19\.0
npm 元数据更新时间：2026-11-13T16:04:30.456Z
中文译文更新时间：2026-11-16T23:44:26.639Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40gravity-ui/gateway
原文对照：https://npmcn.com/package/%40gravity-ui/gateway/?lang=original
项目主页：https://github.com/gravity-ui/gateway#readme
源码仓库：https://github.com/gravity-ui/gateway

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

- 包体积（解压后）：355 kB，70 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：9 个
- peer 依赖：grpc-reflection-js ^0\.3\.0
- 首次发布：2023-08-18T19:13:00.963Z
- 最新版本发布：2026-11-13T16:04:30.265Z
- 近 30 天下载量：40273（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：90（近 12 个月 25 个）

## 中文简介

一个灵活而强大的Express控制器,用于在Node.js应用程序中与REST和gRPC API合作.

## 安装

```sh
npm install @gravity-ui/gateway
```

也可以使用：`pnpm add @gravity-ui/gateway`、`yarn add @gravity-ui/gateway`、`bun add @gravity-ui/gateway`

## README

# @gravity-ui/出入口 # [![npm package](https://img.shields.io/npm/v/@gravity-ui/gateway)](https://www.npmjs.com/package/@gravity-ui/gateway) [![CI](https://img.shields.io/github/actions/workflow/status/gravity-ui/gateway/.github/workflows/ci.yml?label=CI&logo=github)](https://github.com/gravity-ui/gateway/actions/workflows/ci.yml?query=branch:main)

一个灵活而强大的Express控制器,用于在Node.js应用程序中与REST和gRPC API合作.

## 目录

-   [安装](https://npmcn.com/package/%40gravity-ui/gateway/#readme-installation)
-   [基本用途](https://npmcn.com/package/%40gravity-ui/gateway/#readme-basic-usage)
-   [配置](https://npmcn.com/package/%40gravity-ui/gateway/#readme-configuration)
    -   [`proxyHeaders`](https://npmcn.com/package/%40gravity-ui/gateway/#readme-proxyheaders)
    -   [验证Schema](https://npmcn.com/package/%40gravity-ui/gateway/#readme-validation-schema)
    -   [使用节点.js中的 API](https://npmcn.com/package/%40gravity-ui/gateway/#readme-using-the-api-in-nodejs)
    -   [Schema 范围](https://npmcn.com/package/%40gravity-ui/gateway/#readme-schema-scopes)
    -   [连接特定动作](https://npmcn.com/package/%40gravity-ui/gateway/#readme-connecting-specific-actions)
    -   [覆盖终点](https://npmcn.com/package/%40gravity-ui/gateway/#readme-overriding-endpoints)
    -   [认证](https://npmcn.com/package/%40gravity-ui/gateway/#readme-authentication)
    -   [处理错误](https://npmcn.com/package/%40gravity-ui/gateway/#readme-error-handling)
    -   [可重试错误](https://npmcn.com/package/%40gravity-ui/gateway/#readme-retryable-errors)
        -   [REST行动](https://npmcn.com/package/%40gravity-ui/gateway/#readme-rest-actions)
        -   [gRPC-行动](https://npmcn.com/package/%40gravity-ui/gateway/#readme-grpc-actions)
    -   [请求取消](https://npmcn.com/package/%40gravity-ui/gateway/#readme-request-cancellation)
    -   [答复来自 `onBeforeAction`](https://npmcn.com/package/%40gravity-ui/gateway/#readme-responding-from-onbeforeaction)
    -   [响应内容类型验证](https://npmcn.com/package/%40gravity-ui/gateway/#readme-response-content-type-validation)
    -   [流出REST回复](https://npmcn.com/package/%40gravity-ui/gateway/#readme-streaming-rest-responses)
    -   [gRPC 响应大小计算](https://npmcn.com/package/%40gravity-ui/gateway/#readme-grpc-response-size-calculation)
    -   [gRPC 对 gRPC 动作的反思](https://npmcn.com/package/%40gravity-ui/gateway/#readme-grpc-reflection-for-grpc-actions)
-   [发展](https://npmcn.com/package/%40gravity-ui/gateway/#readme-development)
    -   [运行测试](https://npmcn.com/package/%40gravity-ui/gateway/#readme-running-tests)
    -   [捐款](https://npmcn.com/package/%40gravity-ui/gateway/#readme-contributing)
-   [许可证](https://npmcn.com/package/%40gravity-ui/gateway/#readme-license)

## 安装

```shell
npm install --save @gravity-ui/gateway
```

## 基本用途

首先,通过导入网关和您的 API 计划创建控制器 :

```javascript
import {getGatewayControllers} from '@gravity-ui/gateway';
import Schema from '<schemas package>';

const config = {
  installation: 'external',
  env: 'production',
  includeProtoRoots: ['...'],
};

const {controller: gatewayController} = getGatewayControllers({root: Schema}, config);

export default gatewayController;
```

然后,将控制器连接到您的快递路线(使用 [表达式](https://github.com/gravity-ui/expresskit):

```javascript
{
    'POST   /<prefix>/:scope/:service/:action': {target: '<controller>', afterAuth: ['credentials']}
}
```

这个 `prefix` 可以是 API 端点的任何前缀(例如, `/gateway/:service/:action`) (中文(简体) ).

## 配置

```typescript
import {AxiosRequestConfig} from 'axios';
import {IncomingHttpHeaders} from 'http';
import {IAxiosRetryConfig} from 'axios-retry';

interface OnUnknownActionData {
  service?: string;
  action?: string;
}

interface Stats {
  service: string;
  action: string;
  restStatus: number;
  grpcStatus?: number;
  responseSize: number;
  requestId: string;
  requestTime: number;
  requestMethod: string;
  requestUrl: string;
  timestamp: number;
  userId?: string;
  traceId: string;
}

type SendStats = (
  stats: Stats,
  headers: IncomingHttpHeaders,
  ctx: CoreContext,
  meta: {debugHeaders: Headers},
) => void;

type GrpcRetryCondition = (error: ServiceError) => boolean;
type AxiosRetryCondition = IAxiosRetryConfig['retryCondition'];

type ControllerType = 'rest' | 'grpc';

type ProxyHeadersFunctionExtra = {
  service: string;
  action: string;

  protopath?: string;
  protokey?: string;
};

type ProxyHeadersFunction = (
  headers: IncomingHttpHeaders,
  type: ControllerType,
  extra: ProxyHeadersFunctionExtra,
) => IncomingHttpHeaders;
type ProxyHeaders = string[] | ProxyHeadersFunction;
type ResponseContentType = AxiosResponse['headers']['Content-Type'];

type GetAuthHeadersParams<AuthArgs = Record<string, unknown>> = {
  actionType: ControllerType;
  serviceName: string;
  requestHeaders: Headers;
  authArgs: AuthArgs | undefined;
};

interface AppErrorArgs {
  code?: string | number;
  details?: object;
  debug?: object;
}

interface AppErrorWrapArgs extends AppErrorArgs {
  message?: string;
}

interface AppErrorConstructor {
  new (message?: string, args?: AppErrorArgs): Error;

  wrap: (error: Error, args?: AppErrorWrapArgs) => Error;
}

interface GatewayConfig {
  // Gateway Installation (external/internal/...). If not provided, determined from process.env.APP_INSTALLATION.
  installation?: string;

  // Gateway Environment (production/testing/...). If not provided, determined from process.env.APP_ENV.
  env?: string;

  // Additional gRPC client options.
  grpcOptions?: object;

  // Additional Axios client options.
  axiosConfig?: AxiosRequestConfig;

  // List of actions to connect from the schema. By default, all actions are connected.
  actions?: string[];

  // Called when an unknown service or action is provided.
  onUnknownAction?: (req: Request, res: Response, data: OnUnknownActionData) => any;

  // Called before the request is executed.
  // Return {responseData, responseHeaders?, debugHeaders?} to skip the action and send responseData
  // as a regular successful response (onRequestSuccess is still called). Throw to fail the request:
  // the thrown value is sent as the error body with its `status` (500 by default).
  onBeforeAction?: (
    req: Request,
    res: Response,
    scope: string,
    service: string,
    action: string,
    config?: ApiServiceActionConfig,
  ) => any;

  // Called upon successful completion of the request.
  onRequestSuccess?: (req: Request, res: Response, data: any) => any;

  // Called in case of unsuccessful request execution.
  onRequestFailed?: (req: Request, res: Response, error: any) => any;

  // List of paths to the necessary proto files for the gateway.
  includeProtoRoots?: string[];

  // Configuration of the path to the CA certificate in gRPC.
  // Set to null to use system certificates by default.
  caCertificatePath?: string | null;
  // Configuration of the path to the client certificate for mTLS in gRPC.
  clientCertificatePath?: string | null;
  // Configuration of the path to the client private key for mTLS in gRPC.
  clientKeyPath?: string | null;
  // Telemetry sending configuration.
  sendStats?: SendStats;

  // Configuration of headers sent to the API.
  proxyHeaders?: ProxyHeaders;

  // When passing a boolean value, it enables/disables debug headers in the response to the request.
  // For unary requests to gRPC backends, debug headers will include information from the trailing metadata returned by the backend.
  withDebugHeaders?: boolean | ((req: Request, res: Response) => boolean);

  // Validation schema for parameters used when no schema is present in the action.
  // You can use DEFAULT_VALIDATION_SCHEMA from lib/constants.ts.
  validationSchema?: object;

  // Enables encoding of REST path arguments (default is true).
  encodePathArgs?: boolean;

  // Configuration for automatic connection re-establishment upon connection error through L3 load balancer (default is true).
  grpcRecreateService?: boolean;

  // Customize retry behavior for grpc requests
  grpcRetryCondition?: GrpcRetryCondition;

  // Customize retry behavior for rest (axios) requests
  axiosRetryCondition?: AxiosRetryCondition;

  // Enable verification of response contentType header. Actual only for REST actions.
  // This value can be set/redefined in the action config.
  expectedResponseContentType?: ResponseContentType | ResponseContentType[];

  // Function to get authentication arguments for API requests
  getAuthArgs: (req: Request, res: Response) => Record<string, unknown> | undefined;

  // Function to get authentication headers for API requests
  getAuthHeaders: (params: GetAuthHeadersParams) => Record<string, string> | undefined;

  // Error constructor for handling errors
  ErrorConstructor: AppErrorConstructor;

  // Axios interceptors configuration
  axiosInterceptors?: AxiosInterceptorsConfig;
}
```

### `proxyHeaders`

`GatewayConfig.proxyHeaders` 是一种可选方法, 允许为整个请求设置标题 `gateway` 级别 :

```javascript
const proxyHeaders = (headers, actionType, extra) => {
  const normalizedHeaders = {...headers};
  const {service, action, protopath, protokey} = extra;

  if (actionType === 'rest' && service === 'mail') {
    normalizedHeaders['x-mail-service-action'] = action;
  }

  return normalizedHeaders;
};

const {controller: gatewayController} = getGatewayControllers(
  {root: Schema},
  {...config, proxyHeaders},
);
```

这个 `extra` 参数包含关于请求的更多信息:

-   `service`: 服务名称
-   `action`: 动作名称
-   `protopath`: 原生路径(用于 gRPC 动作)
-   `protokey`: 原型密钥(用于GRPC动作)

在访问信头时,网关会首先尝试用用户提供的确切大小写来获取信头. 如果信头与该确切的大小写不存在,那么它就回到小写中寻找同名标题. 这种行为确保了与各种HTTP客户端的相容性,这些客户端可能发送不同外壳的头像.

您可以使用 `ApiServiceBaseActionConfig.proxyHeaders`数字 :

```javascript
const schema = {
  userService: {
    serviceName: 'users',
    endpoints: {...},
    actions: {
      getProfile: {
        path: () => '/profile',
        method: 'GET',
        proxyHeaders: (headers) => ({...headers, ['x-users-service-action']: 'get-profile'}),
      },
    },
  },
};
```

这个 `GatewayConfig.proxyHeaders` 财务报告和审定财务报表 `ApiServiceBaseActionConfig.proxyHeaders` 当动作被调用时合并。 合并标题的战略没有保障.

建议使用 `GatewayConfig.proxyHeaders` 用于指定整个应用程序或大量动作共有的标题。 否则,最好使用 `ApiServiceBaseActionConfig.proxyHeaders`。 。 。 .

### 验证Schema

默认情况下,对于 REST 动作中的路径参数,使用以下正则exp : `/^((?!(\.\.|\?|#|\\|\/)).)*$/i`。 。 。 .

如果参数值没有通过验证,则请求以状态被拒绝 `400` 代码 `INVALID_PARAMS`。错误细节包含标题 `Invalid path params` 和第一个无效参数的路径 `description` (例如, `items[0].id`) (中文(简体) ). 不向上游服务机构发送请求.

你可以用这个 `DEFAULT_VALIDATION_SCHEMA` 从 `lib/constants.ts` 作为起点:

```javascript
export const DEFAULT_VALIDATION_SCHEMA = {
  additionalProperties: {
    oneOf: [
      {
        type: 'number',
      },
      {
        type: 'string',
        pattern: '^((?!(\\.\\.|\\?|#|\\\\|\\/)).)*$',
      },
      {
        type: 'object',
      },
    ],
  },
};
```

### 使用节点.js中的 API

除了快递控制器外,该网关还输出一个 `api` 对后端服务直接请求的对象 :

```javascript
import {getGatewayControllers} from '@gravity-ui/gateway';
import Schema from '<schemas package>';

const config = {
  installation: 'external',
  env: 'production',
  includeProtoRoots: ['...'],
  timeout: 25000, // default 25 seconds
  caCertificatePath: '...',
  // Optional: paths for mTLS client certificate and key
  clientCertificatePath: '...',
  clientKeyPath: '...',
};

const {api: gatewayApi} = getGatewayControllers({root: Schema}, config);

// Use the API to make requests
const result = await gatewayApi.serviceName.actionName({
  authArgs: {token: 'auth-token'},
  requestId: '123',
  headers: {},
  args: {param1: 'value1'},
  ctx: context,
});
```

这个 `actionConfig` 参数的结构如下:

```typescript
interface ApiActionConfig<Context, TRequestData> {
  requestId: string;
  headers: Headers;
  args: TRequestData;
  ctx: Context;
  timeout?: number;
  callback?: (response: TResponseData) => void;
  authArgs?: Record<string, unknown>;
  userId?: string;
  abortSignal?: AbortSignal;
}
```

### Schema 范围

每个计划都属于自己的命名空间. 服务与行动名称在计划之间是完全独立的,可以相通. 每个范围都有独立的gRPC上下文,它消除了原生文件中的chemas之间的命名冲突.

瞄准镜名称是包含计数对象的第一个参数中的密钥:

```javascript
const schemasByScopes = {scope1: schema1, scope2: schema2};
```

有两个范围命名空间的示例: `root` 财务报告和审定财务报表 `anotherScope`数字 :

```javascript
import {getGatewayControllers} from '@gravity-ui/gateway';

const {
  controller, // Controller
  api, // API (for Node.js environment)
} = getGatewayControllers({root: rootSchema, anotherScope: anotherSchema}, config);

// API calls are made by specifying the scope
const resultFromRoot = api.root.rootService.rootAction(params);
const resultFromAnother = api.anotherScope.anotherService.anotherAction(params);
```

有一个特殊的范围叫 `root`在不明确说明其范围的情况下可以援引其方法:

```javascript
const resultFromRoot = api.root.rootService.rootAction(params);
// Same result
const sameResultFromRoot = api.rootService.rootAction(params);
```

速记控制器也会期望 `:scope` 参数。 如果未指定范围参数,默认范围假定为 `root`。 。 。 .

```javascript
{
    'POST   /<prefix>/:scope/:service/:action': gatewayController
}
```

### 连接特定动作

您可以使用 `actions` 字段中的字段。 如果未提供动作,则默认会连接所有来自计划的行动.

```javascript
import {getGatewayControllers} from '@gravity-ui/gateway';
import rootSchema from '<schemas package>';
import localSchema from '../shared/schemas';

const config = {
  installation: 'external',
  env: 'production',
  includeProtoRoots: ['...'],
  actions: [
    'local.*', // All actions from the 'local' scope
    'root.serviceA.*', // All actions from 'serviceA' in the 'root' scope
    'root.serviceB.getUser', // Only the 'getUser' action from 'serviceB' in the 'root' scope
  ],
};

const {api: gatewayApi} = getGatewayControllers({root: rootSchema, local: localSchema}, config);
```

指定行动的现有模式:

-   `<scope>.*` - 来自指定范围的所有行动
-   `<scope>.<service>.*` - 来自指定服务的所有动作
-   `<scope>.<service>.<action>` - 只有指定的动作

**说明:** 此配置仅会影响客户端访问. 所有动作在服务器一侧仍可访问 .

### 覆盖终点

您可以使用 `GATEWAY_ENDPOINTS_OVERRIDES` 环境变量。 这对于测试环境是有用的.

示例格式 :

```javascript
GATEWAY_ENDPOINTS_OVERRIDES = JSON.stringify({
  serviceName: {
    endpoint: 'https://example.com',
  },
  'example.exampleService': {
    endpoint: 'https://overrided.example.com',
  },
});
```

### 认证

网关支持通过 `getAuthArgs` 财务报告和审定财务报表 `getAuthHeaders` 配置选项 :

```javascript
const config = {
  // ...other config options

  // Get authentication arguments for request
  getAuthArgs: (req, res) => ({
    token: req.authorization.token,
  }),

  // Generate authentication headers for backend requests
  getAuthHeaders: (params) => {
    if (!params?.token) return undefined;

    return {
      Authorization: `Bearer ${params.token}`,
    };
  },
};
```

您可以在三个级别上定义认证: |

1.  **网关级别** (全球)-如上所示
2.  **服务级别** - 在服务定义中增加认证方法
3.  **行动层面** (最具体的) - 在单个动作中添加认证方法 | 认证方法按以下顺序检查: 动作 > 服务 > 网关. | **服务级认证 :** |

```javascript
const schema = {
  userService: {
    serviceName: 'users',
    endpoints: {...},
    // Service-level authentication
    getAuthHeaders: (params) => ({
      'X-User-Service-Auth': params.token,
    }),
    getAuthArgs: (req, res) => ({
      token: req.authorization.token,
      serviceSpecificData: req.headers['x-service-data'],
    }),
    actions: {
      getProfile: {
        path: () => '/profile',
        method: 'GET',
        // Uses service-level authentication
      },
      updateProfile: {
        path: () => '/profile',
        method: 'PUT',
        // Action-level authentication (overrides service-level)
        getAuthHeaders: (params) => ({
          'X-Special-Auth': params.token,
        }),
      },
    },
  },
};
```

### 处理错误

网关提供了几种处理错误的方法:

1.  **错误构建器** 通过 `ErrorConstructor` (重排字段) 配置选项 :

```javascript
class CustomError extends Error {
  constructor(message, options = {}) {
    super(message);
    this.name = 'CustomError';
    this.code = options.code || 'UNKNOWN_ERROR';
    this.status = options.status || 500;
    this.details = options.details;
  }

  static wrap(error) {
    if (error instanceof CustomError) return error;
    return new CustomError(error.message, {
      code: error.code || 'INTERNAL_ERROR',
      status: error.status || 500,
    });
  }
}

const config = {
  // ...other config options
  ErrorConstructor: CustomError,
};
```

2.  **自定义请求错误处理** 通过 `onRequestFailed` 配置选项 :

```javascript
const config = {
  // ...other config options
  onRequestFailed: (req, res, error) => {
    console.error('Request failed:', error);
    return res.status(error.status || 500).json({
      error: error.message,
      code: error.code,
    });
  },
};
```

3.  **未关闭 `params` 错误**: 如果一个动作定义了 `params` 处理器和它扔出,请求以状态被拒绝 `500` 代码 `GETTING_PARAMS_FAILED`;上游服务不叫. 行动不包含 `params` 处理器不受影响.

### 可重试错误

#### REST行动

这个 **默认** rEST-Action的再试验条件包括下列条件:

-   网络出错( 由 `axiosRetry.isNetworkError`(中文(简体) )
-   HTTP 429和5xx的答复(由 `axiosRetry.isRetryableError`)),包括请求《波恩协定》

默认已禁用复读 。 设定 `retries` 在动作计划或API呼叫中允许它们. 值是附加尝试的次数 : `retries: 2` 允许最多三次请求.

复数使用指数回放与焦急并尊重 `Retry-After` 响应头, 表示 作为秒或 HTTP 日期。 超时涵盖所有尝试并重试延迟; 如果不够的话 下一次重试所剩时间, 请求会因最后一个错误而失败 .

复用原请求正文. 部分或全部消耗的可读流 无法自动重放, 因此重试可能发送不完整或空的正文 。 设定 `retries: 0` 请求使用一发子弹的流体.

您可以使用 `axiosRetryCondition` 配置选项 :

```javascript
const config = {
  // ...other config options
  axiosRetryCondition: (error) => {
    // Custom logic to determine if the request should be retried
    return error.code === 'TIMEOUT';
  },
};
```

您也可以在动作关卡设置重试条件 。 行动的条件高于 全球状况。 自定义条件取代默认条件, 因此返回 `false` (单位:千美元) 防止重试 HTTP 429 和 5xx 回复 :

```javascript
const schema = {
  userService: {
    serviceName: 'users',
    endpoints: {...},
    actions: {
      getProfile: {
        path: () => '/profile',
        method: 'GET',
        retries: 2,
        axiosRetryCondition: (error) => {
          // Custom logic for this specific action
          return error.code === 'ECONNRESET';
        },
      },
    },
  },
};
```

#### gRPC-行动

这个 **默认** gRPC-动作的再试条件包括某些gRPC状态代码:

-   `UNAVAILABLE`
-   `CANCELLED`
-   `ABORTED`
-   `UNKNOWN`

您可以使用 `grpcRetryCondition` 配置选项 :

```javascript
const config = {
  // ...other config options
  grpcRetryCondition: (error) => {
    // Custom logic to determine if the request should be retried
    return error.code === 'RESOURCE_EXHAUSTED';
  },
};
```

图书馆输出 `isRetryableGrpcError` 函数,用于检查 gRPC 错误根据默认条件是否可以重试 :

```javascript
import {isRetryableGrpcError} from '@gravity-ui/gateway';

// Use in your custom retry condition
const customGrpcRetryCondition = (error) => {
  return isRetryableGrpcError(error) || error.code === 'RESOURCE_EXHAUSTED';
};
```

除非配置选项 `grpcRecreateService` 设置为 `false`,当可能断开时,服务连接被重新创建:

-   请求因连接出错而失败( q)`UNAVAILABLE`, (中文(简体) ), `CANCELLED`, (中文(简体) ), `ABORTED`, (中文(简体) ), `UNKNOWN` 或者说 `DEADLINE_EXCEEDED`) 频道处于断裂状态(`CONNECTING`, (中文(简体) ), `TRANSIENT_FAILURE` 或者说 `SHUTDOWN`) ——连接在再试之前被重新创建,因此再试不会再用被卡住的通道;
-   请求失败 `DEADLINE_EXCEEDED` 当频道是 `READY` (最后期限最有可能由慢后端所造成)——只有在所有回覆被耗尽后才能重新创建连接.

### 请求取消

当客户端断开时, 网关支持取消请求 。 这对长期运行的操作有用,因为如果客户端不再等待响应,您想要避免不必要的处理.

对导出控制器默认启用此特性 。 API 请求时,您可以通过 `AbortSignal` 取消请求:

```javascript
const abortController = new AbortController();

const result = await gatewayApi.serviceName.actionName({
  authArgs: {token: 'auth-token'},
  requestId: '123',
  headers: {},
  args: {param1: 'value1'},
  ctx: context,
  abortSignal: abortController.signal,
});
```

您也可以使用 `abortOnClientDisconnect` 选项 :

```javascript
const schema = {
  userService: {
    serviceName: 'users',
    endpoints: {...},
    actions: {
      longRunningOperation: {
        path: () => '/process',
        method: 'POST',
        abortOnClientDisconnect: true, // Enable cancellation for this action
      },
    },
  },
};
```

### 答复来自 `onBeforeAction`

`onBeforeAction` 可以回答一个请求而不是动作,例如为模拟服务. 返回时 `createBeforeActionResponse({responseData, responseHeaders?, debugHeaders?})`:动作不叫,数据通过正则成功路径 - 页眉被设定, `onRequestSuccess` 如果配置,则调用,否则数据会以状态200发送。 任何其他返回值,包括 `undefined` 或普通对象为 `responseData`,保留默认行为.

后端在此情况下不调用,所以动作的参数验证, `getAuthArgs`, (中文(简体) ), `sendStats` 而后端自己的授权和所有权检查也没有运行. 访问检查要靠钩子:在那里决定谁可以得到这种答复,例如,只为工作人员用户或外部制作服务.

要失败请求, 扔出: 抛出值会通过正则错误路径, 并随其作为响应机构发送 `status` (默认500美元),或转至 `onRequestFailed`。 。 。 .

```javascript
import {createBeforeActionResponse} from '@gravity-ui/gateway';

const config = {
  onBeforeAction: (req, res, scope, service, action) => {
    if (service === 'users' && action === 'getUser') {
      return createBeforeActionResponse({
        responseData: {id: '1', name: 'Mock'},
        responseHeaders: {'x-mock': 'users.getUser'},
      });
    }

    if (service === 'users' && action === 'deleteUser') {
      throw {
        status: 403,
        code: 'GATEWAY_REQUEST_ERROR',
        message: 'Permission denied',
        details: {grpcCode: 7},
      };
    }

    return undefined;
  },
};
```

### 响应内容类型验证

对于 REST 动作,您可以验证响应的内容类型,以确保它符合您的预期. 这有利于确保API返回预期格式.

您可以在网关级别设置预期内容类型 :

```javascript
const config = {
  // ...other config options
  expectedResponseContentType: 'application/json',
};
```

在行动层面:

```javascript
const schema = {
  userService: {
    serviceName: 'users',
    endpoints: {...},
    actions: {
      getProfile: {
        path: () => '/profile',
        method: 'GET',
        expectedResponseContentType: 'application/json',
      },
      getDocument: {
        path: () => '/document',
        method: 'GET',
        expectedResponseContentType: ['application/pdf', 'application/octet-stream'],
      },
    },
  },
};
```

您可以指定一个单一内容类型或一组可接受的内容类型。 如果响应内容类型与任何预期类型不相匹配,则会出错.

### 流出REST回复

设定 `responseType: 'stream'` 作为可读流的节点Js接收上游反应机构。 默认控制器在客户端到达时会对这些响应进行管道处理,而不是缓冲. 使用 `proxyResponseHeaders` ưμ㼯a `Content-Type`。 。 。 .

```javascript
const schema = {
  events: {
    serviceName: 'events',
    endpoints: {production: 'https://events.example.com'},
    actions: {
      subscribe: {
        method: 'GET',
        path: () => '/subscribe',
        responseType: 'stream',
        abortOnClientDisconnect: true,
        proxyResponseHeaders: ['content-type'],
      },
    },
  },
};
```

如果上游流中响应失败,则客户端连接被关闭并被记录出错误. 何时 `onRequestSuccess` 被设定,它接收了溪流 并负责管道它 `res`。 。 。 .

### gRPC 响应大小计算

对于无效的 gRPC 动作, 网关会计算 `responseSize` 页:1 `sendStats` 使用 `object-sizeof`,这对JSON的解码响应进行序列化,可以为大型响应增加大量处理时间.

设定 `calculateResponseSize: false` 在不需要大小统计时跳过此计算时的动作 :

```javascript
const schema = {
  exportService: {
    serviceName: 'exports',
    endpoints: {...},
    actions: {
      getExport: {
        protoPath: 'exports/v1/export_service.proto',
        protoKey: 'exports.v1.ExportService',
        action: 'GetExport',
        calculateResponseSize: false,
      },
    },
  },
};
```

选项默认为 `true`。当禁用时,仍然会引用成功的无线电话 `sendStats`不过 `responseSize` 实值 `0` 以表示未计算大小。 反应数据和信头不变. 此选项同时与原生文件和反射同时工作,不影响流调或出错统计.

### gRPC 对 gRPC 动作的反思

与其使用gRPC proto文件,不如使用gRPC反射来确定服务和方法的结构.

**先决条件:**

1.  安装 `grpc-reflection-js` 软件包 :
    
    ```shell
    npm install --save grpc-reflection-js
    ```
    
2.  将补丁应用到 `protobufjs` 库 :
    
    -   添加 `npx gateway-reflection-patch` 到您的项目 `postinstall` 剧本. 这假设了原生地取自于节点-模块的根.
    -   从库的补丁文件夹复制到您的工程根并安装 [补丁包](https://www.npmjs.com/package/patch-package)中添加补丁包命令 `postinstall` 剧本. 在这种情况下,在更新时需要注意网关中补丁的更新.

如果在 Docker 构建过程中遇到“ 无法在 wd 中运行 \[......\] ” 错误, 您可以添加不安全的- perm = true 到您的. npmrc 文件 .

3.  配置您的动作以使用反射 :
    
    ```javascript
    import {GrpcReflection} from '@gravity-ui/gateway';
    
    const schema = {
      userService: {
        serviceName: 'users',
        endpoints: {...},
        actions: {
          getUser: {
            protoKey: 'users.v1.UserService',
            action: 'GetUser',
            reflection: GrpcReflection.OnFirstRequest,
            // Optional: refresh reflection cache every 3600 seconds (1 hour)
            reflectionRefreshSec: 3600,
          },
        },
      },
    };
    ```
    

**反射选项 :**

-   `GrpcReflection.OnFirstRequest` - 对第一个请求进行反思。 使用缓存反射 .
-   `GrpcReflection.OnEveryRequest` - 在每次请求前进行反思。 不要使用缓存反射 .

给 `OnFirstRequest` 选项 `reflectionRefreshSec` 参数,这表示反射缓存在秒后在背景中可以多久更新一次. 缓存更新同步发生, 不要屏蔽当前请求 。 初始的反射请求带有空缓存可能会给请求带来一些延迟.

**特殊性**

反射的缓存密钥包括 `protoKey` 财务报告和审定财务报表 `endpoint`因此,带有共享密钥的动作将使用一个共同的缓存版本,该版本将从最早的情景中获得(当第一个动作请求与 `OnFirstRequest` 战略已经制定).

此功能为实验. 已对 `protobufjs` 使用 [补丁包](https://github.com/ds300/patch-package) 基于下列公关协议:

-   参数名称转换为骆驼Case [1073卢比](https://github.com/protobufjs/protobuf.js/pull/1073)
-   处理地图的修复 [PR 1478 (英语)](https://github.com/protobufjs/protobuf.js/pull/1478) grpc-reflection-js 也被补丁支持自定义选项.

要开发, 您需要使用命令在本地应用补丁 `npx patch-package`。 。 。 .

**频道证书类型错配错误**

此错误可能因安装重复而发生 `@grpc/grpc-js` 图书馆。 建议确保这个图书馆的所有版本都一致并一致地避免这个问题.

## 发展

### 运行测试

```shell
# Run unit tests
npm test

# Run integration tests
npm run test-integration
```

### 捐款

欢迎捐款! 请看 [捐款额](https://npmcn.com/package/%40gravity-ui/gateway/CONTRIBUTING.md) 详细情况.

## 许可证

麻省理工学院

## 常见问题

### @gravity-ui/gateway 是什么？

一个灵活而强大的Express控制器,用于在Node\.js应用程序中与REST和gRPC API合作\.

### 如何安装 @gravity-ui/gateway？

在项目目录运行 npm install @gravity-ui/gateway，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 gateway-reflection-patch，可以用 npx gateway-reflection-patch 直接运行。

### @gravity-ui/gateway 支持 TypeScript 吗？

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

### @gravity-ui/gateway 支持 ESM 还是 CommonJS？

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

### @gravity-ui/gateway 可以商用吗？

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

### @gravity-ui/gateway 的下载量有多少？

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

### @gravity-ui/gateway 还在维护吗？

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

