Smart Comments
Ensure you've read the Smart Tags page before referring here.
在阅读本页之前,请确保已先阅读 Smart Tags 页面。
You can customize your PostGraphile GraphQL schema without making breaking changes to your database schema by adding specially formatted comments to tables, columns, functions, relations, etc. within your PostgreSQL database. We call these "smart comments".
无需对数据库 schema 做出破坏性变更,只要在 PostgreSQL 数据库中为表、列、函数、relation 等对象添加特定格式的注释,即可定制你的 PostGraphile GraphQL schema。我们把这种注释称为“smart comments(智能注释)”。
Smart tags are the annotations themselves; smart comments are one way to add
smart tags to an entity, specifically via PostgreSQL COMMENT statements.
Smart tag 指的是注解本身;而 smart comment 则是为实体添加 smart tag 的一种方式,具体而言就是通过 PostgreSQL 的 COMMENT 语句来实现。
Smart comment specSmart comment 规范
Comments can be added to various entities within PostgreSQL using
the COMMENT statement;
we add a special syntax to these comments that enables PostGraphile to treat
them as smart comments.
在 PostgreSQL 中,可以使用 COMMENT 语句为各类数据库实体添加注释;我们在这些注释中引入了一套特殊语法,让 PostGraphile 能够将其识别为 smart comment。
A smart comment is made up of one or more "tags" and optionally followed by the
remaining comment. Leading spaces and tabs are ignored. If the very first line
is blank, that is also ignored. Tags may have a string payload (which follows
the tag and a space, and must not contain newline characters) and are separated
by newlines (\n or \r\n). Tags always start with an @ symbol and must
always come before the remaining comment, hence all smart comments start with
an @ symbol. If a tag has no payload then its value will be the boolean
true, otherwise it will be a string. If the same tag is present more than
once in a smart comment then its final value will become an array of the
individual values for that tag.
一条 smart comment 由一个或多个“标签(tag)”组成,后面可选地跟上其余说明性注释。行首的空格和制表符会被忽略;如果首行为空行,也会一并忽略。每个标签可以携带一段字符串 payload(紧跟在标签名和单个空格之后,且其中不能包含换行符),标签之间通过换行符(\n 或 \r\n)分隔。标签始终以 @ 符号开头,并且必须位于其余说明性注释之前——因此所有 smart comment 都以 @ 开头。如果某个标签没有携带 payload,它的值就是布尔值 true,否则为字符串;如果同一条 smart comment 中多次出现相同的标签,其最终取值会合并为由各个值组成的数组。
The following text could be parsed as a smart comment (the smart comment values shown are examples only, and don't have any meaning):
下面这段文本可以被解析为 smart comment(此处展示的标签与值仅为示例,本身不具备实际含义):
@name meta
@isImportant
@jsonField date timestamp
@jsonField name text
@jsonField episode enum ONE=1 TWO=2
This field has a load of arbitrary tags.
and would result in the following JSON tags object:
解析后会得到如下 JSON 标签对象:
{
"name": "meta",
"isImportant": true,
"jsonField": ["date timestamp", "name text", "episode enum ONE=1 TWO=2"]
}
and the description on the last line
(This field has a load of arbitrary tags.) would be made available as
documentation as regular comments are.
而最后一行(This field has a load of arbitrary tags.)则会像普通注释一样,作为该实体的说明文档保留下来。
Note that the parser is deliberately very strict currently, we might make it more flexible in future; you might want to check out the test suite.
注意,当前的解析器刻意设计得非常严格,未来我们可能会放宽限制;如需了解具体解析规则,可查阅测试套件。
Adding newlines添加换行符
We recommend you define smart tags using dollar quoting, which makes adding newlines natural. We support both LF and CRLF line endings (and treat them the same).
我们建议使用美元符号引用(dollar quoting)来定义 smart tag,这样写多行文本与换行会更自然。PostGraphile 同时支持 LF 和 CRLF 换行符(且两者处理方式完全一致)。
Traditionally we recommended the use of the
E "escape" string constants,
wherein you can use \n for newlines, but that was before we made the parser less strict.
早期我们曾推荐使用 E“转义”字符串常量(即在其中使用 \n 表示换行),但那是在后来放宽解析器限制之前的做法了。
comment on column my_schema.my_table.my_column is $$
@name meta
@isImportant
@jsonField date timestamp
@jsonField name text
@jsonField episode enum ONE=1 TWO=2
This field has a load of arbitrary tags.
$$;
Note that adding two newlines in a row separates the smart tags section from the
descriptive prose. Content after two newlines will not be parsed for smart tags
even if it starts with an @ character.
请注意,连续两个换行符会将 smart tag 区块与后面的说明文本分隔开。一旦出现连续两个换行,即使后续内容以 @ 开头,也不会再被解析为 smart tag。
For example:
例如:
comment on column my_schema.my_table.my_column is $$
@name meta
@isImportant
@jsonField date timestamp
@jsonField name text
This field has a load of arbitrary tags.
@jsonField episode enum ONE=1 TWO=2
$$;
results in the following JSON tags object:
将会解析为以下 JSON 标签对象:
{
"name": "meta",
"isImportant": true,
"jsonField": ["date timestamp", "name text"]
}
and the description:
以及如下说明文档:
This field has a load of arbitrary tags.
@jsonField episode enum ONE=1 TWO=2
Applying smart tags to database entities将 smart tag 应用于数据库实体
Tables表
comment on table my_schema.my_table is
E'@name my_new_table_name\n@omit update,delete\nThis is the documentation.';
Views视图
comment on view my_schema.mv_view is
E'@name my_new_view_name\n@omit update,delete\nThis is the documentation.';
Materialized Views物化视图
comment on materialized view my_schema.mv_view is
E'@name my_new_view_name\n@omit update,delete\nThis is the documentation.';
Types类型
comment on type my_schema.my_type is
E'@name my_new_type_name\nThis is the documentation.';
Columns列
comment on column my_schema.my_table.my_column is
E'@name my_new_column\n@omit create,update\nThis is the documentation.';
Constraints约束
comment on constraint my_constraint on my_schema.my_table is
E'@foreignFieldName foos\n@fieldName bar\nDocumentation here.';
Functions函数
comment on function my_function(arg_type_1, arg_type_2) is
E'@name my_new_function_name\nDocumentation here.';
Adding smart tags to virtual constraints为虚拟约束添加 smart tag
If you need to apply any smart comments to a virtual constraint (sometimes
informally called a "fake constraint"), you cannot use newlines (\n) because
they will be interpreted as separate smart comments on the original entity.
We've added a workaround for this: you can use the pipe (|) symbol to assign
smart comments to the virtual constraint, for example to rename it:
如果需要为虚拟约束(有时也非正式地称为“伪约束”)附加 smart comment,不能直接使用换行符(\n),因为换行后会被解析成原实体上各自独立的 smart comment。为此,我们提供了一种变通写法:使用管道符(|)将 smart comment 关联到该虚拟约束上,例如对其进行重命名:
comment on materialized view my_materialized_view is
E'@foreignKey (post_id) references posts (id)|@fieldName yourNameHere';