GraphQL — ano ito, wika ng query at aplikasyon sa mga mobile project

Ano ang GraphQL?

GraphQL — ay isang specifikasyon at runtime environment para sa API na nagbibigay sa kliyente ng buong kontrol sa natatanggap na data. Binuo ng mga inhinyero ng Facebook upang malutas ang mga problema ng mobile app na News Feed, ang specifikasyon ay inilathala bilang isang bukas na pamantayan noong 2015. Mula noong 2018, ang GraphQL ay nasa ilalim ng pamamahala ng GraphQL Foundation na may suporta ng Linux Foundation at mga kumpanya tulad ng Apollo, AWS, GitHub, SAP at iba pa.

Hindi tulad ng REST, kung saan ang bawat endpoint ay nagbabalik ng nakapirming istruktura ng data, ang GraphQL ay gumagamit ng iisang endpoint na tumatanggap ng string ng query. Inilalarawan ng kliyente sa query kung anong mga field ang kailangan, at ibinabalik ng server ang mga ito nang eksakto. Halimbawa, ang query na { user(id: “1”) { name email } } ay magbabalik lamang ng name at email ng user, nang walang dagdag na field tulad ng address, phone o createdAt na kailangang makuha sa REST.

Ang GraphQL ay hindi nakatali sa anumang partikular na database o wika. Ang specifikasyon ay tumutukoy lamang sa format ng mga query at tugon. Mayroong mga implementasyon ng server sa Node.js (graphql-js, Apollo Server), Kotlin (graphql-kotlin, Netflix DGS Framework), Python (Graphene, Strawberry), Ruby (graphql-ruby) at iba pang mga wika. Ang mga library ng kliyente ay magagamit para sa lahat ng pangunahing platform, kabilang ang Apollo Client para sa iOS, Android at web.

Paano gumagana ang GraphQL

Ang arkitektura ng GraphQL ay binubuo ng tatlong pangunahing bahagi: iskema (Schema), resolver (Resolvers) at engine ng pagpapatupad (GraphQL Engine). Tinutukoy ng iskema kung anong mga uri ng data ang magagamit, anong mga query ang maaaring isagawa at anong mga argumento ang tinatanggap. Ang mga resolver ay mga function sa server na nagbabalik ng data para sa bawat field ng iskema. Ang engine ng pagpapatupad ay tumatanggap ng papasok na query, bini-validate ito laban sa iskema, tinatawagan ang mga kaukulang resolver at binubuo ang tugon.

Ang proseso ng pagproseso ng query ay ganito:

• Ang kliyente ay nagpapadala ng POST request sa /graphql na may JSON body { “query”: “...” }
• Ang server ay nagpa-parse ng query, gumagawa ng AST (Abstract Syntax Tree) at bini-validate ito laban sa iskema
• Ang engine ay tumatawid sa AST, tinatawagan ang mga resolver para sa bawat field at nangongolekta ng data
• Ang tugon ay ibinabalik sa format na JSON, na eksaktong tumutugma sa istruktura ng query

Ang pangunahing bentahe ng arkitektura ng GraphQL ay resolusyon sa antas ng field. Sa REST, ang developer ay maaaring makakuha ng lahat ng field ng resource (posibleng may labis) o gumamit ng mga extension tulad ng ?fields=name,email. Sa GraphQL, ang ganitong pagsasala ay naka-embed sa wika: bawat query ay tahasang tumutukoy kung anong mga field ang kailangan, at ibinabalik ng server ang mga ito nang eksakto. Ito ay lalong mahalaga para sa mga mobile application, kung saan ang dami ng ipinadalang data ay direktang nakakaapekto sa bilis ng pag-load at pagkonsumo ng data.

Query, Mutation at Subscription

GraphQL ay tumutukoy sa tatlong uri ng operasyon, na ang bawat isa ay tumutugma sa isang partikular na senaryo ng interaksyon. Query — para sa pagbasa ng data, kahalintulad ng GET sa REST. Mutation — para sa pagbabago ng data (paglikha, pag-update, pagtanggal), kahalintulad ng POST/PUT/DELETE. Subscription — para sa real-time na mga update sa pamamagitan ng WebSocket, na walang direktang kahalintulad sa klasikong REST (nangangailangan ng karagdagang solusyon tulad ng WebSocket o Server-Sent Events).

Ang pangunahing syntax ng mga query ay madaling maunawaan:

// Simpleng query na may argumento
query {
    user(id: "42") {
        name
        email
        avatarUrl
    }
}

// Mutation na may pagbabalik ng binagong data
mutation {
    updateProfile(name: "Ivan") {
        id
        name
        updatedAt
    }
}

// Subscription — nakikinig sa real-time na mga update
subscription {
    newMessage(chatId: "chat_1") {
        id
        text
        sender { name }
    }
}

Query ay isinasagawa nang parallel — lahat ng field sa parehong antas ay na-load nang sabay-sabay. Pinapayagan nito na mag-load ng kaugnay na data (user at kanyang mga post) sa isang query nang walang maraming round-trip. Mutation ay isinasagawa nang sunud-sunod — ang mga mutation sa isang query ay isinasagawa nang isa-isa ayon sa pagkakasunud-sunod ng deklarasyon. Subscription ay nagtatag ng isang permanenteng koneksyon sa pamamagitan ng WebSocket, kung saan nagpapadala ang server ng data kapag may naganap na kaganapan.

Ang mga operasyon ay maaaring tumanggap ng mga variable upang paghiwalayin ang data mula sa query, mga direktiba (@include, @skip) para sa kondisyonal na pagsasama ng mga field at mga fragment para sa muling paggamit ng mga set ng field. Ang mga kakayahang ito ay ginagawang flexible at reusable ang mga GraphQL query, na lalong mahalaga sa malalaking proyekto na may maraming screen at component.

Iskema at sistema ng uri ng GraphQL

Sa puso ng GraphQL ay ang sistema ng uri, na naglalarawan ng lahat ng posibleng data at operasyon ng API. Ang iskema (Schema) ay isang paglalarawan ng mga uri na maaaring ibalik ng server at ng mga query na tinatanggap nito. Ang iskema ay isinulat sa wikang Schema Definition Language (SDL) at nagsisilbing kontrata sa pagitan ng kliyente at server. Maaaring makuha ng kliyente ang iskema sa pamamagitan ng introspection — isang espesyal na query na __schema na nagbabalik ng kumpletong paglalarawan ng API.

Halimbawa ng iskema para sa isang blog:

// SDL — Schema Definition Language
type User {
    id: ID!
    name: String!
    email: String
    posts: [Post!]!
}

type Post {
    id: ID!
    title: String!
    content: String
    author: User!
}

type Query {
    user(id: ID!): User
    posts(page: Int): [Post!]!
}

Tandang padamdam (!) ay nangangahulugang non-null field — garantisadong naroroon sa tugon. Ang mga square bracket [ ] ay nagpapahiwatig ng listahan. Sinusuportahan ng GraphQL ang mga scalar na uri (Int, Float, String, Boolean, ID), mga uri ng object, enum, union, interface at input-type (para sa mga argumento ng mutation). Ang mahigpit na pag-type ay nagdodokumento ng API sa sarili nito at pinapayagan ang mga tool ng kliyente na bumuo ng code: mga uri ng TypeScript, mga data class ng Kotlin, mga istruktura ng Swift.

Introspection — isang natatanging kakayahan ng GraphQL na wala sa REST. Maaaring magpadala ang kliyente ng query sa iskema at makatanggap ng kumpletong paglalarawan ng lahat ng uri, field, argumento at direktiba. Ito ang batayan ng mga tool tulad ng GraphiQL at Apollo Studio, na awtomatikong bumubuo ng dokumentasyon at autocomplete para sa mga developer. Ang introspection ay nagbibigay-daan din sa pagsulat ng mga automated na test na sumusuri sa pagsunod ng iskema sa inaasahang istruktura.

Paghahambing ng GraphQL sa REST

Ang pagpili sa pagitan ng GraphQL at REST ay isa sa mga pangunahing tanong sa arkitektura kapag nagdidisenyo ng API. Ang parehong approach ay may kani-kaniyang lakas at kahinaan, at ang pagpili ay depende sa mga partikular na pangangailangan ng proyekto. Ang REST ay nananalo sa pagiging simple at unibersalidad, ang GraphQL naman sa flexibility at kahusayan ng query. Tingnan natin ang comparative table.

Ang pangunahing disbentahe ng GraphQL ay ang hirap ng caching. Sa REST, ang HTTP caching ay gumagana sa antas ng URL: isang request sa /api/users/42 ay palaging nagbabalik ng parehong istruktura, at ang tugon ay maaaring i-cache ayon sa URL. Sa GraphQL, lahat ng request ay pumupunta sa isang endpoint, ang istruktura ng tugon ay depende sa body ng request. Upang malutas ang problemang ito, ang Apollo Client ay gumagamit ng normalized cache sa client-side na naghahati ng mga tugon sa magkakahiwalay na entity ayon sa id at awtomatikong ina-update ang mga ito kapag nakatanggap ng bagong data.

Ang isa pang mahalagang aspeto ay ang problema sa N+1. Kapag humihiling ng nested data (halimbawa, mga post ng user at mga komento sa bawat post), ang GraphQL ay maaaring magsagawa ng hiwalay na SQL query para sa bawat elemento ng listahan. Ito ay nalulutas gamit ang DataLoader — isang utility para sa batching at caching ng mga database query na nag-grupo ng mga indibidwal na query sa isang batch query. Sa REST, ang problemang ito ay hindi gaanong halata dahil kontrolado ng developer ang istruktura ng tugon sa server.

Mga halimbawa ng GraphQL query

Tingnan natin ang mga praktikal na halimbawa ng paggamit ng GraphQL sa isang mobile application sa Kotlin gamit ang Apollo Client. Ang mga halimbawa ay nagpapakita ng mga tipikal na senaryo: pag-load ng data para sa screen ng profile (query), paglikha ng bagong post (mutation) at pag-subscribe sa mga bagong komento (subscription). Ang bawat halimbawa ay may kasamang GraphQL query at code sa client-side.

Query: pag-load ng profile na may mga post

Isang GraphQL query ang naglo-load ng user, kanyang mga huling post at kabuuang bilang ng mga follower. Sa REST, kakailanganin ng hindi bababa sa 2-3 request: /users/42, /users/42/posts, /users/42/stats. Pinagsasama ng GraphQL ang mga ito sa isang round-trip, binabawasan ang oras ng pag-load ng screen sa mabagal na koneksyon.

// GraphQL query (sa .graphql file)
query ProfileScreen($userId: ID!) {
    user(id: $userId) {
        name
        bio
        avatarUrl
        posts(limit: 10) {
            id
            title
            createdAt
        }
        followersCount
        followingCount
    }
}

// Tawag sa client-side (Apollo Client + Kotlin)
val response = apolloClient
    .query(ProfileScreenQuery(userId = "42"))
    .execute()
binding.nameText.text = response.data?.user?.name

Mutation: paglikha ng bagong post

Hindi lamang nilikha ng mutation ang resource, kundi ibinabalik din ang kasalukuyang data nito para sa pag-update ng UI. Ang field na __typename ay ginagamit ng Apollo Client para sa normalization ng cache — awtomatikong ina-update ng kliyente ang Post record sa cache kapag nakatanggap ng matagumpay na tugon ng mutation.

// GraphQL mutation
mutation CreatePost($input: CreatePostInput!) {
    createPost(input: $input) {
        id
        title
        createdAt
        author {
            id
            name
        }
    }
}

// Tawag ng mutation na may input-type
val input = CreatePostInput(
    title = "Bagong post tungkol sa GraphQL",
    content = "Pinapasimple ng GraphQL ang pagtatrabaho sa API..."
)
val result = apolloClient
    .mutation(CreatePostMutation(input))
    .execute()

Isang mahalagang bentahe ng GraphQL kumpara sa REST sa konteksto ng mobile development ay awtomatikong pagbuo ng code. Ang Apollo Client para sa Kotlin (Apollo GraphQL) ay bumubuo ng type-safe na mga klase mula sa .graphql file sa yugto ng build. Kung babaguhin ng server ang iskema, hindi mabubuo ang proyekto hanggang sa ma-update ang mga query. Pinipigilan nito ang mga runtime error na karaniwan sa REST, kung saan ang pagbabago sa istruktura ng tugon ay maaaring hindi mapansin sa panahon ng development.

Ekosistema: Apollo, Relay at mga tool

Ang ekosistema ng GraphQL ay may kasamang ilang pangunahing library at tool na nagpapasimple sa development at operasyon. Apollo Client — ang pinakasikat na client library, na sumusuporta sa React, iOS, Android at Kotlin Multiplatform. Relay mula sa Facebook — isang alternatibo para sa React application na may natatanging approach sa pamamahala ng data at caching. Ang pagpili sa pagitan ng Apollo at Relay ay depende sa platform at mga pangangailangan sa performance.

Sa server-side, nangunguna ang Apollo Server (Node.js), Netflix DGS Framework (Kotlin/Java) at graphql-ruby. Para sa pag-develop ng iskema at pag-test ng query, ginagamit ang GraphiQL — isang interactive na IDE na naka-embed sa browser. Ang Apollo Studio ay nagbibigay ng performance metrics, pagsubaybay ng query at pamamahala ng iskema para sa production environment. Hiwalay, dapat banggitin ang GraphQL Code Generator — isang tool na bumubuo ng TypeScript, Kotlin, Swift at Dart na mga uri mula sa SDL schema.

Para sa mobile development, partikular na interesante ang Apollo Kotlin (Apollo GraphQL) — isang library na ganap na nakasulat sa Kotlin na may suporta para sa coroutine, Flow at Multiplatform. Pinapayagan nito ang paggamit ng parehong GraphQL query para sa Android at iOS sa mga Kotlin Multiplatform project. Ang Apollo Kotlin ay nagno-normalize ng cache, sumusuporta sa mga error sa antas ng field (partial errors) at awtomatikong bumubuo ng mga modelo ng data mula sa .graphql file. Ginagawa nitong ang GraphQL ang piniling choice para sa malalaking mobile project kung saan mahalaga ang bilis ng development at kaligtasan ng uri.