本文屬使用Prisma構(gòu)建GraphQL服務(wù)系列忍啸。
本教程學(xué)習(xí)如何使用Prisma對(duì)數(shù)據(jù)庫(kù)生成GraphQL API捅厂。
主要步驟如下：
- 安裝Prisma CLI
- 使用
prisma init構(gòu)建Prisma服務(wù) - 使用GraphQL Playground查看API盼樟，發(fā)送查詢(xún)(queries)和突變(mutations)
安裝Prisma CLI
使用Prisma CLI管理Prisma服務(wù)贫贝。
可使用npm(或yarn)安裝喷鸽。
打開(kāi)終端工具，運(yùn)行如下命令安裝Prisma CLI:
npm install -g prisma
# or
# yarn global add prisma
構(gòu)建Prisma服務(wù)
打開(kāi)終端讼庇，跳轉(zhuǎn)到任意目錄绎巨。然后用如下命令構(gòu)建Prisma 服務(wù):
prisma init hello-world
此命令創(chuàng)建一個(gè)hello-world新目錄，包括2個(gè)必須的文件:
-
prisma.yml:服務(wù)的根配置文件蠕啄，包含有關(guān)服務(wù)的信息场勤，例如名稱(chēng)（用于生成服務(wù)的HTTP端點(diǎn)），用于保護(hù)對(duì)端點(diǎn)訪(fǎng)問(wèn)的及應(yīng)該在何處部署的secret歼跟。 -
datamodel.graphql(也可能為不同名稱(chēng)和媳，如types.graphql):此文件使用GraphQL SDL定義數(shù)據(jù)模型(data model)。
來(lái)看看生成的文件：
prisma.yml
endpoint: https://eu1.prisma.sh/public-mountainninja-311/hello-world/dev
datamodel: datamodel.graphql
注意哈街，
endpoint對(duì)于會(huì)略有不同留瞳，因?yàn)?code>public-mountainninja-311是隨機(jī)生成的ID，對(duì)于部署到Sandbox的每個(gè)Prisma API都會(huì)有所不同叹卷。
以下是生成的prisma.yml中的屬性說(shuō)明：
-
endpoint:定義Prisma API的HTTP端點(diǎn); -
datamodel:所包含數(shù)據(jù)模型的文件的路徑撼港。
datamodel.graphql
type User {
id: ID! @unique
name: String!
}
數(shù)據(jù)模型包含應(yīng)用程序域中實(shí)體的類(lèi)型定義。此刻骤竹，您將開(kāi)始使用帶有id和name的非常??簡(jiǎn)單的User類(lèi)型帝牡。
@unique指令(directive)表示數(shù)據(jù)庫(kù)中每個(gè)User的id唯一，Prisma會(huì)始終確保其唯一蒙揣。
Prisma API現(xiàn)已部署并準(zhǔn)備好接收查詢(xún)(queries)靶溜，突變(mutations)和訂閱(subscriptions)。
使用GraphQL Playground查看API
你的API已被部署 - 但你怎么知道如何與它交互懒震？它的API實(shí)際上是什么樣的罩息？
通常，生成的API允許對(duì)數(shù)據(jù)模型中的類(lèi)型執(zhí)行CRUD操作个扰。它還公開(kāi)了GraphQL訂閱瓷炮，允許客戶(hù)訂閱特定事件并實(shí)時(shí)接收更新。
了解數(shù)據(jù)模型是API的基礎(chǔ)很重要递宅。每次對(duì)數(shù)據(jù)模型進(jìn)行更改（并運(yùn)行prisma deploy之后）時(shí)娘香，GraphQL API都會(huì)相應(yīng)更新苍狰。
由于您的數(shù)據(jù)模型包含User類(lèi)型，因此Prisma API現(xiàn)在允許其客戶(hù)端創(chuàng)建烘绽，讀取淋昭，更新和刪除該類(lèi)型的實(shí)例（也稱(chēng)為節(jié)點(diǎn)nodes）。尤其是安接，現(xiàn)在基于User類(lèi)型生成以下GraphQL操作：
-
user:通過(guò)其id查詢(xún)（或另一個(gè)@unique字段）檢索單個(gè)User節(jié)點(diǎn) -
users:查詢(xún)以檢索User節(jié)點(diǎn)列表翔忽。 -
createUser: 突變(Mutation)創(chuàng)建一個(gè)新的User節(jié)點(diǎn)。 -
updateUser: 突變(Mutation)更新現(xiàn)存User節(jié)點(diǎn)盏檐。 -
deleteUser: 突變(Mutation) 刪除現(xiàn)存User節(jié)點(diǎn)歇式。
注意：以上操作列表不完整。 Prisma API公開(kāi)了多個(gè)操作糯笙，例如贬丛，允許批量更新/刪除許多節(jié)點(diǎn)。但是给涕，所有操作都可以創(chuàng)建豺憔，讀取，更新或刪除數(shù)據(jù)模型中定義的類(lèi)型的節(jié)點(diǎn)够庙。
要實(shí)際使用這些操作恭应，您需要一種將請(qǐng)求發(fā)送到服務(wù)API的方法。由于該API通過(guò)HTTP公開(kāi)耘眨，因此您可以使用curl或Postman等工具與之交互昼榛。但是，GraphQL實(shí)際上具有更好的工具：GraphQL Playground剔难，一種交互式GraphQL IDE胆屿。
要打開(kāi)GraphQL Playground，可以再次使用Prisma CLI偶宫。只需在hello-world目錄中運(yùn)行以下命令：
prisma playground
這將打開(kāi)一個(gè)GraphQL Playground非迹，如下圖：
注意：Playground可以作為獨(dú)立的桌面應(yīng)用程序安裝在您的機(jī)器上。如果您沒(méi)有安裝Playground纯趋，該命令會(huì)自動(dòng)在您的默認(rèn)瀏覽器中打開(kāi)一個(gè)Playground憎兽。
GraphQL API的一個(gè)非常酷的特性是它們有效地自我說(shuō)明吵冒。 GraphQL Scheme定義了API的所有操作纯命，包括輸入?yún)?shù)和返回類(lèi)型。這允許像GraphQL Playground這樣的工具自動(dòng)生成API文檔痹栖。
要查看Prisma API的文檔亿汞，請(qǐng)單擊Playground窗口右邊緣上的綠色SCHEMA按鈕。
這帶來(lái)了Playground的文檔窗格揪阿。最左邊的列是API接受的所有操作的列表留夜。然后匙铡，您可以深入了解每個(gè)操作涉及的輸入?yún)?shù)或返回類(lèi)型的詳細(xì)信息图甜。
發(fā)送查詢(xún)和突變(queries and mutations)
好吧碍粥！借助迄今為止學(xué)到的一切，您已準(zhǔn)備好針對(duì)您的API發(fā)布一些查詢(xún)和突變(queries and mutations)黑毅。讓我們從users查詢(xún)開(kāi)始嚼摩，檢索當(dāng)前存儲(chǔ)在數(shù)據(jù)庫(kù)中的所有User節(jié)點(diǎn)。 在左邊的Playground窗格中輸入以下查詢(xún)矿瘦，然后單擊Play按鈕（或使用快捷鍵CMD + Enter）：
query {
users {
name
}
}
此時(shí)枕面，服務(wù)器只返回一個(gè)空列表。這并不奇怪缚去，因?yàn)槲覀兊侥壳盀橹惯€沒(méi)有實(shí)際創(chuàng)建任何User節(jié)點(diǎn)潮秘。因此，讓我們改變它易结，并使用createUser突變將第一個(gè)User節(jié)點(diǎn)存儲(chǔ)在數(shù)據(jù)庫(kù)中枕荞。
在Playground中打開(kāi)一個(gè)新選項(xiàng)卡，在左邊的Play中輸入以下突變:
mutation {
createUser(data: {
name: "Sarah"
}) {
id
}
}
這一次搞动，服務(wù)器的響應(yīng)實(shí)際上包含了一些數(shù)據(jù)（請(qǐng)注意躏精，當(dāng)服務(wù)器在創(chuàng)建時(shí)為每個(gè)新節(jié)點(diǎn)生成一個(gè)全局唯一的ID時(shí)，該ID當(dāng)然會(huì)有所不同）
{
"data": {
"createUser": {
"id": "cjc69nckk31jx01505vgwmgch"
}
}
}
您現(xiàn)在可以返回到users查詢(xún)的前一個(gè)選項(xiàng)卡鹦肿，并再次發(fā)送查詢(xún)矗烛。
這次，剛剛創(chuàng)建的User節(jié)點(diǎn)在服務(wù)器響應(yīng)中返回：
請(qǐng)注意箩溃，API還提供強(qiáng)大的過(guò)濾瞭吃，排序和分頁(yè)功能。以下是為
user查詢(xún)提供相應(yīng)輸入?yún)?shù)的查詢(xún)示例涣旨。
檢索name包含字符串“ra”的所有User節(jié)點(diǎn)
query {
users(where: {
name_contains: "ra"
}) {
id
name
}
}
檢索按name降序排列的所有User節(jié)點(diǎn)
query {
users(orderBy: name_DESC) {
id
name
}
}
檢索一部分User節(jié)點(diǎn)（列表中的位置20-29）
query {
users(skip: 20, first: 10) {
id
name
}
}
