模式命名惯例

在您的 GraphQL 模式中对类型、字段和参数进行命名规范和考量的说明

schema-design

💡 小贴士

如果您是寻求更多此主题资料的商用客户，请尝试 Odyssey 上的课程企业最佳实践：模式设计课程。

尚未成为企业客户？了解 GraphOS for Enterprise。

强制执行约定

使用 GraphOS 模式校验来捕捉命名违规。 GraphOS 模式校验可以在模式检查中执行，这允许您在 CI/CD 管道中强制执行此规范，或者可以使用 Rover 进行本地的一次性请求。

高层次指导

无论您的选择何种规范，都要在整个模式中保持一致。
使用具体的名称—不要“抢占”适用范围广的名称。
避免使用缩写词、首字母缩略词和缩写。

大小写

使用camelCase 用于字段名称、参数名称和指令名称：

1
type Query {
2
  myCamelCaseFieldNames(myArgumentName: String): String
3
}
4

5
directive @myDirective on FIELD

使用 PascalCase 为类型名称：

1
type MyType { ... }
2

3
enum MyEnum { ... }
4

5
interface MyInterface { ... }
6

7
union MyUnion = ...
8

9
scalar MyScalar

使用 SCREAMING_SNAKE_CASE 为枚举值：

1
enum MyEnum {
2
  VALUE_ONE
3
  VALUE_TWO
4
}

字段名称

避免在 get 或 list 等查询字段上使用动词前缀：

1
type Query {
2
  # ❌ incorrect
3
  getProducts: [Product]
4

5
  # ✅ correct
6
  products: [Product]
7
}

这会在根字段和嵌套字段之间创建一致性：

1
# ❌ incorrect
2
query Products {
3
  getProducts {
4
    id
5
    getReviews {
6
      content
7
    }
8
  }
9
}
10

11
# ✅ correct
12
query Products {
13
  products {
14
    id
15
    reviews {
16
      content
17
    }
18
  }
19
}

将 mutation 字段以动词开头：

1
type Mutation {
2
  # ❌ incorrect
3
  customerAdd(input: AddCustomerInput): AddCustomerPayload!
4

5
  # ✅ correct
6
  addCustomer(input: AddCustomerInput): AddCustomerPayload!
7
}

类型名称

命名输入类型时，使用后缀 Input：

1
input AddCustomerInput {
2
  name: String!
3
}

命名从 mutations 返回的输出类型时，使用一致的后缀如 Response 或 Payload：

1
type Mutation {
2
  addCustomer(input: AddCustomerInput!): AddCustomerResponse!
3
}
4

5
type AddCustomerResponse {
6
  success: Boolean!
7
}

其他考虑因素

命名空间

在解决不同领域之间的命名冲突时，我们建议使用以下方法之一：

`PascalCase` 前缀

1
type StoreCustomer { ... }
2
type SiteCustomer { ... }

`Single_Underscore` 前缀

1
type Store_Customer { ... }
2
type Site_Customer { ... }

首页