@500px_info/graphql-query-complexity 中文文档教程

发布于 5年前 浏览 30 项目主页 更新于 3年前

GraphQL Query Complexity Analysis for graphql-js

npm 版本CircleCI

该库提供 GraphQL 查询分析以拒绝对 GraphQL 服务器的复杂查询。 这可用于保护您的 GraphQL 服务器免受资源耗尽和 DoS 攻击。

使用 graphql-js 参考实现。

Installation

通过 npm 安装包

npm install -S graphql-query-complexity

Usage

创建具有最大查询复杂度的规则:

import queryComplexity, {
  simpleEstimator
} from 'graphql-query-complexity';

const rule = queryComplexity({
  // The maximum allowed query complexity, queries above this threshold will be rejected
  maximumComplexity: 1000,

  // The query variables. This is needed because the variables are not available
  // in the visitor of the graphql-js library
  variables: {},

  // Optional callback function to retrieve the determined query complexity
  // Will be invoked whether the query is rejected or not
  // This can be used for logging or to implement rate limiting
  onComplete: (complexity: number) => {console.log('Determined query complexity: ', complexity)},

  // Optional function to create a custom error
  createError: (max: number, actual: number) => {
    return new GraphQLError(`Query is too complex: ${actual}. Maximum allowed complexity: ${max}`);
  },

  // Add any number of estimators. The estimators are invoked in order, the first
  // numeric value that is being returned by an estimator is used as the field complexity.
  // If no estimator returns a value, an exception is raised. 
  estimators: [
    // Add more estimators here...

    // This will assign each field a complexity of 1 if no other estimator
    // returned a value. 
    simpleEstimator({
      defaultComplexity: 1
    })
  ]
});

Configuration / Complexity Estimators

可以使用所谓的复杂度估算器自定义 GraphQL 查询的复杂度计算。 复杂性估计器是一个简单的函数,用于计算字段的复杂性。 你可以加 规则的任意数量的复杂性估计器,然后一个接一个地执行。 返回数字复杂性值的第一个估计器确定该字段的复杂性。

至少有一个估计器必须返回一个复杂度值,否则会引发异常。 你可以 例如使用 simpleEstimator 作为最后一个估计器 在你的链中定义一个默认值。

您可以使用任何可用的估算器来计算字段的复杂性 或编写您自己的:

  • simpleEstimator: The simple estimator returns a fixed complexity for each field. Can be used as last estimator in the chain for a default value.
  • directiveEstimator: Set the complexity via a directive in your schema definition (for example via GraphQL SDL)
  • fieldExtensionsEstimator: The field extensions estimator lets you set a numeric value or a custom estimator function in the field config extensions of your schema.
  • fieldConfigEstimator: (DEPRECATED) The field config estimator lets you set a numeric value or a custom estimator function in the field config of your schema.
  • legacyEstimator: (DEPRECATED) The legacy estimator implements the logic of previous versions. Can be used to gradually migrate your codebase to new estimators.
  • PRs welcome…

查阅每个估算器的文档以获取有关如何使用它们的信息。

Creating Custom Estimators

估计器具有以下函数签名:

type ComplexityEstimatorArgs = {
  // The composite type (interface, object, union) that the evaluated field belongs to
  type: GraphQLCompositeType,

  // The GraphQLField that is being evaluated
  field: GraphQLField<any, any>,

  // The input arguments of the field
  args: {[key: string]: any},

  // The complexity of all child selections for that field
  childComplexity: number
}

type ComplexityEstimator = (options: ComplexityEstimatorArgs) => number | void;

Usage with express-graphql

要将查询复杂性分析验证规则与 express-graphql 一起使用,请使用类似 以下:

import queryComplexity from 'graphql-query-complexity';
import express from 'express';
import graphqlHTTP from 'express-graphql';
import schema from './schema';

const app = express();
app.use('/api', graphqlHTTP(async (request, response, {variables}) => ({
  schema,
  validationRules: [ queryComplexity({
    maximumComplexity: 1000,
    variables,
    onComplete: (complexity: number) => {console.log('Query Complexity:', complexity);},
  }) ]
})));

Calculate query complexity

如果您想在验证阶段之外计算 GraphQL 查询的复杂性,例如 在解析器中返回复杂度值,您可以通过 getComplexity 计算复杂度:

import { getComplexity, simpleEstimator } from 'graphql-query-complexity';
import { parse } from 'graphql';

// Import your schema or get it form the info object in your resolver
import schema from './schema';

// You can also use gql template tag to get the parsed query
const query = parse(`
  query Q($count: Int) {
    some_value
    some_list(count: $count) {
      some_child_value
    }
  }
`);

const complexity = getComplexity({
  estimators: [
    simpleEstimator({defaultComplexity: 1})
  ],
  schema,
  query,
  variables: {
    count: 10,
  },
});

console.log(complexity); // Output: 3

Prior Art

该项目受到以下先前项目的启发:

GraphQL Query Complexity Analysis for graphql-js

npm versionCircleCI

This library provides GraphQL query analysis to reject complex queries to your GraphQL server. This can be used to protect your GraphQL servers against resource exhaustion and DoS attacks.

Works with graphql-js reference implementation.

Installation

Install the package via npm

npm install -S graphql-query-complexity

Usage

Create the rule with a maximum query complexity:

import queryComplexity, {
  simpleEstimator
} from 'graphql-query-complexity';

const rule = queryComplexity({
  // The maximum allowed query complexity, queries above this threshold will be rejected
  maximumComplexity: 1000,

  // The query variables. This is needed because the variables are not available
  // in the visitor of the graphql-js library
  variables: {},

  // Optional callback function to retrieve the determined query complexity
  // Will be invoked whether the query is rejected or not
  // This can be used for logging or to implement rate limiting
  onComplete: (complexity: number) => {console.log('Determined query complexity: ', complexity)},

  // Optional function to create a custom error
  createError: (max: number, actual: number) => {
    return new GraphQLError(`Query is too complex: ${actual}. Maximum allowed complexity: ${max}`);
  },

  // Add any number of estimators. The estimators are invoked in order, the first
  // numeric value that is being returned by an estimator is used as the field complexity.
  // If no estimator returns a value, an exception is raised. 
  estimators: [
    // Add more estimators here...

    // This will assign each field a complexity of 1 if no other estimator
    // returned a value. 
    simpleEstimator({
      defaultComplexity: 1
    })
  ]
});

Configuration / Complexity Estimators

The complexity calculation of a GraphQL query can be customized with so called complexity estimators. A complexity estimator is a simple function that calculates the complexity for a field. You can add any number of complexity estimators to the rule, which are then executed one after another. The first estimator that returns a numeric complexity value determines the complexity for that field.

At least one estimator has to return a complexity value, otherwise an exception is raised. You can for example use the simpleEstimator as the last estimator in your chain to define a default value.

You can use any of the available estimators to calculate the complexity of a field or write your own:

  • simpleEstimator: The simple estimator returns a fixed complexity for each field. Can be used as last estimator in the chain for a default value.
  • directiveEstimator: Set the complexity via a directive in your schema definition (for example via GraphQL SDL)
  • fieldExtensionsEstimator: The field extensions estimator lets you set a numeric value or a custom estimator function in the field config extensions of your schema.
  • fieldConfigEstimator: (DEPRECATED) The field config estimator lets you set a numeric value or a custom estimator function in the field config of your schema.
  • legacyEstimator: (DEPRECATED) The legacy estimator implements the logic of previous versions. Can be used to gradually migrate your codebase to new estimators.
  • PRs welcome…

Consult the documentation of each estimator for information about how to use them.

Creating Custom Estimators

An estimator has the following function signature:

type ComplexityEstimatorArgs = {
  // The composite type (interface, object, union) that the evaluated field belongs to
  type: GraphQLCompositeType,

  // The GraphQLField that is being evaluated
  field: GraphQLField<any, any>,

  // The input arguments of the field
  args: {[key: string]: any},

  // The complexity of all child selections for that field
  childComplexity: number
}

type ComplexityEstimator = (options: ComplexityEstimatorArgs) => number | void;

Usage with express-graphql

To use the query complexity analysis validation rule with express-graphql, use something like the following:

import queryComplexity from 'graphql-query-complexity';
import express from 'express';
import graphqlHTTP from 'express-graphql';
import schema from './schema';

const app = express();
app.use('/api', graphqlHTTP(async (request, response, {variables}) => ({
  schema,
  validationRules: [ queryComplexity({
    maximumComplexity: 1000,
    variables,
    onComplete: (complexity: number) => {console.log('Query Complexity:', complexity);},
  }) ]
})));

Calculate query complexity

If you want to calculate the complexity of a GraphQL query outside of the validation phase, for example to return the complexity value in a resolver, you can calculate the complexity via getComplexity:

import { getComplexity, simpleEstimator } from 'graphql-query-complexity';
import { parse } from 'graphql';

// Import your schema or get it form the info object in your resolver
import schema from './schema';

// You can also use gql template tag to get the parsed query
const query = parse(`
  query Q($count: Int) {
    some_value
    some_list(count: $count) {
      some_child_value
    }
  }
`);

const complexity = getComplexity({
  estimators: [
    simpleEstimator({defaultComplexity: 1})
  ],
  schema,
  query,
  variables: {
    count: 10,
  },
});

console.log(complexity); // Output: 3

Prior Art

This project is inspired by the following prior projects:

    我们使用 Cookies 和其他技术来定制您的体验包括您的登录状态等。通过阅读我们的 隐私政策 了解更多相关信息。 单击 接受 或继续使用网站,即表示您同意使用 Cookies 和您的相关数据。
    原文