GraphQL 开发指南 - 阿俊博客

单文件管理 `typeDef` 与 `resolver`#

如下，在单文件中定义 ObjectType 与其在 Query 以及 Mutation 中对应的查询。并把 typeDef 与 resolver 集中管理。

1
const typeDef = gql`
2
  type Todo @sql {
3
    id: ID!
4
  }
5

6
  extend type Query {
7
    todos: [Todo!]
8
  }
9

10
  extend type Mutation {
11
    createTodo: TODO!
12
  }
13
`
14

15
const resolver: IResolverObject<any, AppContext> = {
16
  Todo: {
17
    user () {}
18
  },
19
  Query: {
20
    todos () {}
21
  },
22
  Mutation: {
23
    createTodo () {}
24
  }
25
}

按需取数据库字段#

使用 @findOption 可以按需查询，并注入到 resolver 函数中的 info.attributes 字段

1
type Query {
2
  users: [User!] @findOption
3
}
4

5
query USERS {
6
  users {
7
    id
8
    name
9
  }
10
}

1
function users ({}, {}, { models }, { attributes }: any) {
2
  return models.User.findAll({
3
    attributes
4
  })
5
}

分页#

对列表添加 page 以及 pageSize 参数来进行分页

1
type User {
2
  id: ID!
3
  todos (
4
    page: Int = 1
5
    pageSize: Int = 10
6
  ): [Todo!] @findOption
7
}
8

9
query TODOS {
10
  todos (page: 1, pageSize: 10) {
11
    id
12
    name
13
  }
14
}

数据库层解决 N+1 查询问题#

使用 dataloader-sequelize 解决数据库查询的 batch 问题

当使用以下查询时，会出现 N+1 查询问题

1
{
2
  users (page: 1, pageSize: 3) {
3
    id
4
    todos {
5
      id
6
      name
7
    }
8
  }
9
}

如果不做优化，生成的 SQL 如下

1
select id from users limit 3
2

3
select id, name from todo where user_id = 1
4
select id, name from todo where user_id = 2
5
select id, name from todo where user_id = 3

而使用 dataloader 解决 N+1 问题后，会大大减少 SQL 语句的条数，生成的 SQL 如下

1
select id from users limit 3
2

3
select id, name, user_id from todo where user_id in (1, 2, 3)

注意 Batch 请求后需要返回 user_id 字段，为了重新分组

N+1 Query 优化后问题#

当有如下所示多级分页查询时，N+1 优化失效，所以应避免多级分页操作

此处只能在客户端避免多层分页查询，而当有恶意查询时会加大服务器压力。可以使用以下的 Hash Query 避免此类问题，同时也在生产环境禁掉 introspection

1
{
2
  users (page: 1, pageSize: 3) {
3
    id
4
    todos (page: 1, pageSize: 3) {
5
      id
6
      name
7
    }
8
  }
9
}

1
select id from users limit 3
2

3
select id, name from todo where user_id = 1 limit 3
4
select id, name from todo where user_id = 2 limit 3
5
select id, name from todo where user_id = 3 limit 3

使用 DataLoader 解决 N+1 查询问题#

使用 ID/Hash 代替 Query#

TODO 需要客户端配合

当 Query 越来越大时，http 所传输的请求体积越来越大，严重影响应用的性能，此时可以把 Query 映射成 hash。

当请求体变小时，此时可以替代使用 GET 请求，方便缓存。

我发现掘金的 GraphQL Query 已由 ID 替代

使用 `consul` 管理配置#

project 代表本项目在 consul 中对应的 key。项目将会拉取该 key 对应的配置并与本地的 config/project.ts 做 Object.assign 操作。 dependencies 代表本项目所依赖的配置，如数据库，缓存以及用户服务等的配置，项目将会在 consul 上拉取依赖配置。

项目最终生成的配置为 AppConfig 标识。

1
export const project = 'todo'
2
export const dependencies = ['redis', 'pg']

用户认证#

使用 @auth 指令表示该资源受限，需要用户登录，roles 表示只有特定角色才能访问受限资源

1
directive @auth(
2
  # USER, ADMIN 可以自定义
3
  roles: [String]
4
) on FIELD_DEFINITION
5

6
type Query {
7
  authInfo: Int @auth
8
}

以下是相关代码

1
function visitFieldDefinition (field: GraphQLField<any, AppContext>) {
2
  const { resolve = defaultFieldResolver } = field
3
  const { roles } = this.args
4
  // const roles: UserRole[] = ['USER', 'ADMIN']
5
  field.resolve = async (root, args, ctx, info) => {
6
    if (!ctx.user) {
7
      throw new AuthenticationError('Unauthorized')
8
    }
9
    if (roles && !roles.includes(ctx.user.role)) {
10
      throw new ForbiddenError('Forbidden')
11
    }
12
    return resolve.call(this, root, args, ctx, info)
13
  }
14
}

jwt 与白名单#

jwt 与 token 更新#

当用户认证成功时，检查其 token 有效期，如果剩余一半时间，则生成新的 token 并赋值到响应头中。

用户角色验证#

日志#

为 graphql，sql，redis 以及一些重要信息(如 user) 添加日志，并设置标签

1
export const apiLogger = createLogger('api')
2
export const dbLogger = createLogger('db')
3
export const redisLogger = createLogger('redis')
4
export const logger = createLogger('common')

为日志添加 requestId (sessionId)#

为日志添加 requestId 方便追踪 bug 以及检测性能问题

1
const requestId = format((info) => {
2
  info.requestId = session.get('requestId')
3
  return info
4
})

使用 Async/Await 处理异常#

结构化异常信息#

结构化 API 异常信息，其中 extensions.code 代表异常错误码，方便调试以及前端使用。extensions.exception 代表原始异常，堆栈以及详细信息。注意在生产环境需要屏蔽掉 extensions.exception

1
$ curl 'https://todo.xiange.tech/graphql' -H 'Content-Type: application/json' --data-binary '{"query":"{\n  dbError\n}"}'
2
{
3
  "errors": [
4
    {
5
      "message": "column User.a does not exist",
6
      "locations": [
7
        {
8
          "line": 2,
9
          "column": 3
10
        }
11
      ],
12
      "path": [
13
        "dbError"
14
      ],
15
      "extensions": {
16
        "code": "SequelizeDatabaseError",
17
        "exception": {
18
          "name": "SequelizeDatabaseError",
19
          "original": {
20
            "name": "error",
21
            "length": 104,
22
            "severity": "ERROR",
23
            "code": "42703",
24
            "position": "57",
25
            "file": "parse_relation.c",
26
            "line": "3293",
27
            "routine": "errorMissingColumn",
28
            "sql": "SELECT count(*) AS \"count\" FROM \"users\" AS \"User\" WHERE \"User\".\"a\" = 3;"
29
          },
30
          "sql": "SELECT count(*) AS \"count\" FROM \"users\" AS \"User\" WHERE \"User\".\"a\" = 3;",
31
          "stacktrace": [
32
            "SequelizeDatabaseError: column User.a does not exist",
33
            "    at Query.formatError (/code/node_modules/sequelize/lib/dialects/postgres/query.js:354:16)",
34
          ]
35
        }
36
      }
37
    }
38
  ],
39
  "data": {
40
    "dbError": null
41
  }
42
}

在生产环境屏蔽掉异常堆栈#

避免把原始异常以及堆栈信息暴露在生产环境

1
{
2
  "errors": [
3
    {
4
      "message": "column User.a does not exist",
5
      "locations": [
6
        {
7
          "line": 2,
8
          "column": 3
9
        }
10
      ],
11
      "path": [
12
        "dbError"
13
      ],
14
      "extensions": {
15
        "code": "SequelizeDatabaseError"
16
      }
17
    }
18
  ],
19
  "data": {
20
    "dbError": null
21
  }
22
}

返回合适的状态码#

异常报警#

根据异常的 code 对异常进行严重等级分类，并上报监控系统。这里监控系统采用的 sentry

1
// lib/error.ts:formatError
2
let code: string = _.get(error, 'extensions.code', 'Error')
3
let info: any
4
let level = Severity.Error
5

6
if (isAxiosError(originalError)) {
7
  code = `Request${originalError.code}`
8
} else if (isJoiValidationError(originalError)) {
9
  code = 'JoiValidationError'
10
  info = originalError.details
11
} else if (isSequelizeError(originalError)) {
12
  code = originalError.name
13
  if (isUniqueConstraintError(originalError)) {
14
    info = originalError.fields
15
    level = Severity.Warning
16
  }
17
} else if (isApolloError(originalError)){
18
  level = originalError.level || Severity.Warning
19
} else if (isError(originalError)) {
20
  code = _.get(originalError, 'code', originalError.name)
21
  level = Severity.Fatal
22
}
23

24
Sentry.withScope(scope => {
25
  scope.setTag('code', code)
26
  scope.setLevel(level)
27
  scope.setExtras(formatError)
28
  Sentry.captureException(originalError || error)
29
})

健康检查#

在 k8s 上根据健康检查监控应用状态，当应用发生异常时可以及时响应并解决

1
$ curl http://todo.xiange.tech/.well-known/apollo/server-health
2
{"status":"pass"}

filebeat & ELK#

通过 filebeat 把日志文件发送到 elk 日志系统，方便日后分析以及辅助 debug

监控#

在日志系统中监控 SQL 慢查询以及耗时 API 的日志，并实时邮件通知 (可以考虑钉钉)

参数校验#

使用 Joi 做参数校验

1
function createUser ({}, { name, email, password }, { models, utils }) {
2
  Joi.assert(email, Joi.string().email())
3
}
4

5
function createTodo ({}, { todo }, { models, utils }) {
6
  Joi.validate(todo, Joi.object().keys({
7
    name: Joi.string().min(1),
8
  }))
9
}

服务端渲染#

npm scripts#

npm start
npm test
npm run dev

单文件管理 `typeDef` 与 `resolver`#

按需取数据库字段#

分页#

数据库层解决 N+1 查询问题#

N+1 Query 优化后问题#

使用 DataLoader 解决 N+1 查询问题#

使用 ID/Hash 代替 Query#

使用 `consul` 管理配置#

用户认证#

jwt 与白名单#

jwt 与 token 更新#

用户角色验证#

日志#

为日志添加 requestId (sessionId)#

使用 Async/Await 处理异常#

结构化异常信息#

在生产环境屏蔽掉异常堆栈#

返回合适的状态码#

异常报警#

健康检查#

filebeat & ELK#

监控#

参数校验#

服务端渲染#

npm scripts#

使用 CI 加强代码质量#

相关阅读

单文件管理 typeDef 与 resolver#

按需取数据库字段#

分页#

数据库层解决 N+1 查询问题#

N+1 Query 优化后问题#

使用 DataLoader 解决 N+1 查询问题#

使用 ID/Hash 代替 Query#

使用 consul 管理配置#

用户认证#

jwt 与白名单#

jwt 与 token 更新#

用户角色验证#

日志#

为日志添加 requestId (sessionId)#

使用 Async/Await 处理异常#

结构化异常信息#

在生产环境屏蔽掉异常堆栈#

返回合适的状态码#

异常报警#

健康检查#

filebeat & ELK#

监控#

参数校验#

服务端渲染#

npm scripts#

使用 CI 加强代码质量#

相关阅读

单文件管理 `typeDef` 与 `resolver`#

使用 `consul` 管理配置#