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';
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 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。
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
- Yarn
- pnpm
- Bun
npm install --save-dev graphile
npx graphile inflection list
yarn add --dev graphile
npx graphile inflection list
pnpm add --save-dev graphile
npx graphile inflection list
bun add --dev graphile
npx graphile inflection list

graphile inflection list command, including a summary of the available inflectors and their arguments.graphile inflection list 命令的初始输出截图,展示了可用 inflector 及其参数的汇总列表。
graphile inflection list command, detailing each inflector, its documentation and its rough TypeScript definition.graphile inflection list 命令后续输出的截图,详细列出了每个 inflector、其文档说明以及大致的 TypeScript 类型定义。