Skip to main content

Inflection

Inflection governs how things are named whilst building your PostGraphile schema. “Inflection” is the system of naming things; it’s composed of a large set of named functions, and we call each of these inflection functions an “inflector.”

在构建 PostGraphile schema 的过程中,inflection 负责控制各类名称的生成规则。所谓命名推导(inflection),就是一套命名系统:它由大量具名函数组成,其中每一个用于命名推导的函数都称为一个 inflector。

The inflectors that you have available will depend on the plugins and presets you’re using. To get a list of the inflectors available to you, you can use TypeScript autocompletion, or install the graphile package and run yarn graphile inflection list (or equivalent for other package managers).

当前可用的 inflector 取决于你所启用的插件和 preset。要查看当前可用的 inflector 列表,既可以借助 TypeScript 的自动补全功能,也可以安装 graphile 包后运行 yarn graphile inflection list(或使用其他包管理器的等价命令)。

In GraphQL, types typically use singular UpperCamelCase (PascalCase); fields, arguments and directives typically use camelCase; and enum values typically use CONSTANT_CASE. These conventions can be seen in the GraphQL specification itself. The default inflectors attempt to map things to natural names in GraphQL whilst avoiding naming conflicts. For example:

在 GraphQL 中,类型名通常采用单数形式的大驼峰命名(UpperCamelCase,即 PascalCase);字段、参数和指令通常采用小驼峰命名(camelCase);枚举值则通常采用全大写下划线分隔命名(CONSTANT_CASE)。这些命名约定在 GraphQL 官方规范 中也有明确体现。默认的 inflector 会在避免命名冲突的前提下,尽量将数据库对象映射为符合 GraphQL 习惯的自然名称。例如:

  • Table names are singularized and changed to UpperCamelCase: pending_users → PendingUser

    表名会被转为单数形式并采用大驼峰命名:pending_users → PendingUser

  • Column names are changed to camelCase: created_at → createdAt

    列名会被转换为小驼峰命名:created_at → createdAt

  • Relations reference the target type and the referencing columns: postsByAuthorId (see “advice” below about making this shorter!)

    关联关系(relation)名称会结合目标类型与外键引用列:postsByAuthorId(关于如何缩短此类名称,请参阅下文的“实践建议”)

But if you don’t want this (or it’s doing something wrong), then you can fix it by overriding inflectors!

不过,如果默认命名不符合预期(或者推导结果有误),你随时可以通过覆盖 inflector 来调整!

Overriding Naming — One-off单点重命名覆盖​

If you want to rename just one field or type, your best bet is to use a smart tag; e.g. for a table you might do:

如果只想修改某一个字段或类型的名称,最佳方式是使用 smart tag;例如针对某张表可以这样标注:

COMMENT ON TABLE post IS E'@name message';
note注意

Each inflector is responsible for checking for any relevant smart tags and honouring them.

每个 inflector 都会自行检查并遵循相关的 smart tag 配置。

Overriding Inflection覆盖 inflection 规则​

You can easily write a plugin to override an individual inflector, it just needs to add the new inflector under the inflection.replace object; an example might look like:

编写插件来覆盖单个 inflector 非常简单,只需将新的实现挂载到 inflection.replace 对象下即可。示例如下:

export default {
name: "ReplacePatchTypeInflectorPlugin",
version: "0.0.0",

inflection: {
replace: {
patchType(previous, resolvedPreset, typeName) {
return this.upperCamelCase(`${typeName}-change-set`);
},
},
},
};

In this example, previous is the previous inflector (in case you only want to override in certain circumstances) — you would call it using the same arguments, just dropping the first two — so in this case: previous(typeName).

在这个示例中,previous 代表上一个版本的 inflector(方便你仅在特定条件下进行覆盖)。调用 previous 时传入与原函数相同的参数,但需省略前两个参数——因此此处写作 previous(typeName)。

TypeScript works with inflectorsTypeScript 对 inflector 提供完整类型支持

TypeScript is your friend when replacing inflectors, it should know what inflectors are available, their documentation, and the types of all their arguments.

在替换 inflector 时,TypeScript 是得力助手——它能自动提示所有可用的 inflector、对应文档说明以及全部参数类型。

Advice实践建议​

By default, the relation field names are explicit to avoid accidental conflicts, and can make your schema somewhat verbose, e.g. userByAuthorId, userByEditorId, userByPublisherId, etc.

默认情况下,关联字段名会保留完整信息以避免意外冲突,但这可能使你的 schema 略显冗长,例如 userByAuthorId、userByEditorId、userByPublisherId 等。

Some people like this verbosity; however if you, like us, prefer shorter names then we encourage you use the @graphile/simplify-inflection plugin. This would automatically change those fields to be named author, editor and publisher respectively.

有些开发者喜欢这种明确详尽的命名;但如果你和我们一样更偏好简洁的名称,推荐启用 @graphile/simplify-inflection 插件。它会自动将上述字段分别简化为 author、editor 和 publisher。

graphile.config.mjs
import { PgSimplifyInflectionPreset } from "@graphile/simplify-inflection";

const preset = {
extends: [
PgSimplifyInflectionPreset,
//...
],
//...
};

Our maintainer, Benjie, prefers to use this plugin in all his projects.

我们的核心维护者 Benjie 在他的所有项目中都会使用这个插件。

Listing available inflectors列出所有可用的 inflector​

We’ve built a command into our graphile development assistant to help you determine all the inflectors available to you:

我们在 graphile 开发助手工具中内置了一条命令,帮助你查看当前可用的所有 inflector:

npm install --save-dev graphile
npx graphile inflection list

Initial output of the graphile inflection list command

Screenshot showing the initial output of the graphile inflection list command, including a summary of the available inflectors and their arguments.graphile inflection list 命令的初始输出截图,展示了可用 inflector 及其参数的汇总列表。

More detailed output from later in the graphile inflection list command

Screenshot from lower down in the output of the graphile inflection list command, detailing each inflector, its documentation and its rough TypeScript definition.graphile inflection list 命令后续输出的截图,详细列出了每个 inflector、其文档说明以及大致的 TypeScript 类型定义。