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

Question

GraphQL Query Complexity Analysis for graphql-js

该库提供 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

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

• Query complexity analysis in the Sangria GraphQL implementation.
• graphql-cost-analysis - Multipliers and directiveEstimator