GraphQL 是由 Facebook 於 2015 年開發的一種 API 查詢語言。客戶端(前端)只會接收到所需的數據,減少了不必要的數據傳輸和多次請求的需要,提高了應用程序的性能和效率。GraphQL 支持查詢、變更和即時更新操作,解決了傳統 REST API 中的因回傳整個數據結構導致流量變多處理時間變長,或需要多次請求才能獲取所有所需的訊息,增加了延遲和複雜性的問題。GraphQL作為一種標準,定義了如何查詢和操作數據,並提供了規範和指南,幫助開發者設計和使用 GraphQL API。
GraphQL 的主要特點包括:
安裝指令:
npm install graphql
type User {
id: ID!
name: String!
email: String!
age: Int
}
type Query{
user: User
}
type User
定義了一個名為 User
的類型,包含 id
、name
、email
和 age
這些欄位。type Query
定義了一個查詢類型,包含一個 user
欄位,返回 User
類型的資料。String
、Int
、Float
等),也可以是自訂的物件型別。透過這些型別,我們可以精確地描述 API 的數據結構,並使用解析函數(Resolver)來處理查詢和變更請求,返回相應的數據或錯誤訊息。GraphQLSchema 是 GraphQL 的核心部分,程式碼由此開始寫。它用來定義資料的結構,包括:
這些元素共同構成了 GraphQL API,使得客戶端能夠靈活地查詢和操作數據。
const schema = new GraphQLSchema({
query: new GraphQLObjectType({
name: 'Query',
fields: {
user: {
type: GraphQLString
}
}
}),
})
type
是因為這樣可以明確地定義字段的數據類型。這有助於確保從客戶端到伺服器之間傳輸的數據具有一致性和正確性。type的
架構:const UserType = new GraphQLObjectType({
name: 'User',
fields: {
id: { type: GraphQLID },
name: { type: GraphQLString },
age: { type: GraphQLInt },
email: { type: GraphQLString }
}
});
在 GraphQL 中,定義類型是用來描述 API 中的數據結構和它們之間的關係。這些定義類型告訴我們可以查詢哪些數據、這些數據的結構是什麼樣的,以及可以對這些數據進行哪些操作。以下是一些具體的定義類型及其作用:
User
類型可能包含 id
、name
和 email
欄位。const UserType = new GraphQLObjectType({
interfaces: [DateTimeInterface],
name: 'User',
fields: {
id: {
type: GraphQLNonNull(GraphQLID)
},
name: {
type: GraphQLString
},
email: {
type: GraphQLString
},
}
});
Int
、Float
、String
、Boolean
和 ID
。// 定義 DateType日期類型
const DateType = new GraphQLScalarType({
name: 'Date',
parseValue(value) {
return new Date(value)
},
serialize(value) {
return value.getTime()
}
});
GraphQLInputObjectType 是用來定義輸入參數的結構。當你在mutation中需要傳遞複雜的參數時,可以使用GraphQLInputObjectType來定義這些參數的結構。
當 GraphQL 中需要新增、更新或刪除資料時,會使用 mutation
作為改變資料的操作入口點。這與查詢資料的 query
不同,query
是用來查詢資料的。為了避免在數據修改時出現錯誤的數據輸入,可以使用 GraphQLInputObjectType
來定義輸入參數的結構。
GraphQLInputObjectType
的作用是:
mutation
中需要傳遞的複雜參數。Enum(枚舉或列舉)是一種用來定義一組固定選項的類型,這些選項是預先定義好的,不能隨意更改。在 GraphQL 中,枚舉類型可以幫助確保數據的一致性和完整性,因為它限制了欄位只能接受特定的值,避免錯誤的數據輸入,並使 API 更加自描述和易於理解。
查詢枚舉類型的欄位時,返回的值通常會以字串(string)的形式表示,因為枚舉的每個選項本質上都是一個有名字的固定值(具名的常量)。這些常量在查詢結果中會被轉換成對應的字串。
在狀態機(State Machine)中,我們可以使用枚舉來表示不同的狀態,例如 stop
、processing
和 completed
。枚舉可以將這些狀態代換為一個數字(例如 0、1、2),這樣我們可以更方便地進行狀態的比較和處理。枚舉提供了名稱和值的對應關係,使我們能夠將數字轉換為看得懂的字串,更好的認出當前狀態。
總結來說,Enum可以幫助我們將複雜的狀態或選項轉換成更簡單且易於閱讀的形式。這樣,我們在回傳數據時,可以提供更容易理解的資訊。
const WorkStateType = new GraphQLEnumType({
name: 'WorkState',
values: {
STOP: {
value: 0
},
COMPLETED: {
value: 1
}
}
})
在這個例子中,WorkStateType
定義了兩個固定的選項:STOP
和 COMPLETED
,分別對應數值 0
和 1
。這樣可以確保在使用 WorkStateType
的欄位中,只能接受這兩個預定義的值。
const DateTimeInterface = new GraphQLInterfaceType({
name: 'DateTimeInterface',
fields: {
created_at: {
type: DateType
},
updated_at: {
type: DateType
}
}
})
在這個例子中,DateTimeInterface
介面定義了 created_at
和 updated_at
這兩個共同欄位。然後,其他物件類型例如User
類型或查詢時可以實現這個介面,並且各自添加特有的欄位。
GraphQLList 是 GraphQL 中的一種類型包裝器,用來表示某一類型的列表。當你需要使用陣列類型時,可以使用 GraphQLList 來包裝該類型,這樣就能夠定義和處理該類型的陣列。
friends: {
type: GraphQLList(GraphQLString) // ['Tom', 'Bob', 'Ray']
}
這段程式碼定義了一個名為 friends
的欄位,其類型為 GraphQLList(GraphQLString)
。這表示 friends
欄位的值是一個字符串(String)類型的陣列,例如 ['Tom', 'Bob', 'Ray']
。
什麼是buildSchema (建立模式)?
用來簡化定義 GraphQL schema 的過程。它允許你使用一個簡單的字符串語法來定義 schema,大大簡化撰寫 schema 的過程。