GraphQL

@easy-cms/plugin-graphql ให้บริการ GraphQL API ที่สร้างจาก collection และ global ของคุณ อ่านและเขียนผ่าน Local API กฎสิทธิ์ สิทธิ์ระดับ field, hook, การตรวจข้อมูล, draft และหลายภาษาจึงทำงานเหมือน REST ทุกอย่าง เหมาะกับ frontend ที่ใช้ Apollo, urql หรือ Relay อยู่แล้ว หรืออยากขอเฉพาะ field ที่ต้องใช้ใน request เดียว

ติดตั้ง

npm install @easy-cms/plugin-graphql

pnpm add @easy-cms/plugin-graphql

yarn add @easy-cms/plugin-graphql

bun add @easy-cms/plugin-graphql

import { graphqlPlugin } from '@easy-cms/plugin-graphql'
 
export default defineConfig({
  // …
  plugins: [graphqlPlugin()],
})

endpoint อยู่ที่ <routes.api>/graphql เช่น https://example.com/api/cms/graphql รับ POST พร้อม { "query", "variables", "operationName" } และ GET พร้อม ?query= สำหรับ query (ไม่รับ mutation) เปิดใน browser นอก production จะได้ GraphiQL ถ้าล็อกอิน admin อยู่ จะอ่านได้ตามสิทธิ์ของคุณ

Schema

แต่ละ collection และ global ได้ type และ operation ตั้งชื่อตาม slug:

และ me คือผู้ใช้ที่ล็อกอินอยู่ (หรือเจ้าของ API key) collection ในตัวคือ User (user, users), Media (mediaItem, media) และ MediaFolder เมื่อเปิดโฟลเดอร์ API key และ collection ที่ Easy CMS ใช้ภายในไม่อยู่ใน schema

query Home($category: ID!) {
  posts(where: { category: { equals: $category } }, sort: [publishedAt_DESC], limit: 5, locale: en) {
    docs {
      id
      title
      cover { url alt sizes { thumbnail { url width height } } }
      category { name }
    }
    totalDocs
    hasNextPage
  }
  siteSettings { name }
}

field แปลงเป็น:

ทุก field เป็น null ได้ ยกเว้น id, createdAt และ updatedAt เพราะ field อาจถูกซ่อนด้วย สิทธิ์ระดับ field หรือว่างในบางภาษาแม้จะ required field ที่ hidden: true ไม่อยู่ใน schema collection ที่มี draft มี status

กรองและเรียง

where มี type ของแต่ละ collection ใช้ operator เดียวกับ REST: equals, not_equals, in, not_in, like, exists และ gt, gte, lt, lte สำหรับตัวเลขและวันที่ รวมเงื่อนไขด้วย AND และ OR field ใน group ซ้อนเข้าไปตามโครง

posts(where: {
  OR: [{ tags: { in: [news] } }, { views: { gte: 100 } }]
  seo: { noindex: { equals: false } }
}) { totalDocs }

sort รับ list เช่น [publishedAt_DESC, title_ASC] (ค่าเริ่มต้น: ใหม่สุดก่อน) limit 1 ถึง 100 (ค่าเริ่มต้น 10) page เริ่มที่ 1

ภาษาและ draft

เมื่อเปิด หลายภาษา query รับ locale และ fallbackLocale ความสัมพันธ์อ่านในภาษาเดียวกัน ถ้าต้องการหลายภาษาพร้อมกัน ใช้ alias:

{
  th: post(id: "1", locale: th) { title }
  en: post(id: "1", locale: en) { title }
}

draft: true รวม draft ด้วย เฉพาะผู้ใช้ที่ล็อกอินและ API key เหมือน REST

Mutation

mutation {
  createPost(data: { title: "Hello", body: "First paragraph\n\nSecond", category: "3" }, draft: true) {
    id
    status
  }
}

• create<Type>(data, locale, draft), update<Type>(id, data, locale, draft) และ delete<Type>(id) คืนเอกสาร global ใช้ update<Global>(data, locale, draft)
• draft: true บันทึกเป็น draft, draft: false เผยแพร่ ถ้าไม่ส่ง collection ทำตามปกติของมัน
• relationship และ upload รับ id, rich text รับเอกสาร Tiptap หรือข้อความธรรมดา (บรรทัดว่างขึ้นย่อหน้าใหม่), blocks รับแถวเป็น JSON ที่มี blockType
• field ที่ required ต้องส่งใน input ของ create ส่วน input ของ update เปลี่ยนเฉพาะที่ส่งมา
• ไฟล์อัปโหลดผ่าน REST แล้วใช้ id ส่วนการล็อกอิน, version และการตั้งเวลาก็ใช้ REST

ใครทำอะไรได้

ยืนยันตัวตนเหมือน REST: cookie session ของ admin, Authorization: Bearer กับ session token หรือ API key ซึ่งทำได้เฉพาะที่ระบุไว้ POST จาก browser ผ่าน CSRF check เดียวกับ REST

error อยู่ใน errors พร้อมรหัสใน extensions.code แยกแบบเดียวกับ REST:

เอกสารที่คุณไม่มีสิทธิ์เห็นเป็น null เหมือน REST ส่วน collection ที่อ่านไม่ได้เลยได้ UNAUTHORIZED หรือ FORBIDDEN query ที่ผิดรูปตอบ status 400 นอกนั้นตอบ 200 พร้อม errors

ขีดจำกัด

GraphQL ให้ client ขอได้มากใน request เดียว plugin จึงจำกัดไว้:

• ความลึก: field ซ้อนกันได้ไม่เกิน 7 ชั้น (ไม่นับ introspection)
• จำนวนเอกสาร: โหลดได้ไม่เกิน 2000 เอกสารต่อ request รวมความสัมพันธ์
• list: limit ไม่เกิน 100

ความสัมพันธ์โหลดเป็นชุด: บทความ 100 ชิ้นกับหมวดหมู่ของมันใช้ query เดียวสำหรับบทความ และอีกหนึ่งสำหรับหมวดหมู่

ตัวเลือก

ชื่ออาจชนกันได้ เช่น collection data ที่เอกพจน์ก็คือ data แอปจะหยุดตอนเริ่มทำงานและบอกว่าต้องตั้งชื่ออะไร

Field ของคุณเอง

extend เพิ่มเข้า schema ด้วย object ของ graphql-js resolver ได้ context ที่มี cms (Local API), user และ load(collection, id) ซึ่งโหลดเป็นชุดเหมือนความสัมพันธ์ในตัว:

import { GraphQLInt, GraphQLList, GraphQLNonNull, GraphQLString } from 'graphql'
 
graphqlPlugin({
  extend: ({ type }) => ({
    query: {
      search: {
        type: new GraphQLList(new GraphQLNonNull(type('Post'))),
        args: { text: { type: new GraphQLNonNull(GraphQLString) } },
        resolve: async (_root, { text }, { cms, user }) =>
          (await cms.find('posts', { user, overrideAccess: false, where: { title: { like: text } } })).docs,
      },
    },
    fields: {
      Post: {
        readingMinutes: {
          type: GraphQLInt,
          resolve: (post) => Math.ceil(JSON.stringify(post.body ?? '').length / 1500),
        },
      },
    },
  }),
})

ส่ง { user, overrideAccess: false } เพื่อให้ resolver ใช้กฎสิทธิ์ของผู้อ่าน

Codegen และ server อื่น

เขียน schema ลงไฟล์ให้ GraphQL Code Generator และเครื่องมืออื่นๆ:

npx easy-cms generate:graphql            # schema.graphql
npx easy-cms generate:graphql web/schema.graphql

คำสั่งนี้เปิดฐานข้อมูลเหมือนคำสั่งอื่น codegen อ่าน schema จาก endpoint ที่รันอยู่ก็ได้

ถ้าจะให้บริการ schema จาก GraphQL server ของคุณเอง (Apollo Server, Yoga, gateway) ให้สร้าง schema แล้วให้ context ต่อ request:

import { buildGraphQLSchema, createContext } from '@easy-cms/plugin-graphql'
 
const cms = await getEasyCMS()
const schema = buildGraphQLSchema(cms.config)
// ต่อ request:
const contextValue = createContext(cms, await cms.auth.userFromHeaders(request.headers))

ขั้นต่อไป

• REST API: อัปโหลด ล็อกอิน version และการตั้งเวลา
• Access control: กฎที่ใช้กับ GraphQL ด้วย
• API keys: key สำหรับ script และ server อื่น