✈️GraphQL API

GraphQLdocumentation

GraphQL là gì?

GraphQL là một cú pháp mô tả cách yêu cầu lấy dữ liệu, và thường được dùng để load data từ một server cho client.

GRAPHQL BAO GỒM 3 ĐIỂM ĐẶC TRƯNG BAO GỒM CHO PHÉP CLIENT XÁC ĐỊNH CHÍNH XÁC NHỮNG GÌ DỮ LIỆU HỌ CẦN, LÀM CHO VIỆC TỔNG HỢP DỮ LIỆU TỪ NHIỀU NGUỒN DỄ DÀNG HƠN VÀ NÓ SỬ DỤNG MỘT TYPE SYSTEM ĐỂ MÔ TẢ DỮ LIỆU.

Vấn đề

GraphQL bắt đầu từ ông lớn Facebook, thế nhưng ngay cả những app đơn giản đôi khi vẫn gặp phải trường hợp “nghẽn cổ chai” do sự hạn chế của REST APIs.

THÍ DỤ BẠN MUỐN HIỂN THỊ MỘT LIST POSTS, VÀ Ở DƯỚI MỖI POST LÀ MỘT LIST LIKE, BAO GỒM CẢ TÊN NGƯỜI DÙNG VÀ AVATAR. CÁCH GIẢI QUYẾT ĐƠN GIẢN LÀ THAY ĐỔI API CỦA ‘POSTS’ ĐỂ NÓ BAO GỒM A ‘LIKE’ ARRAY CHỨA THÔNG TIN VỀ NGƯỜI DÙNG.

Thế nhưng khi làm như vậy cho các app mobile thì bạn sẽ phát hiện ra tốc độ của chúng chạy quá chậm. Vì thế mà giờ đây bạn sẽ cần tới 2 endpoints, một với likesvà một thiếu chúng.

Giờ thì còn có thêm một vấn đề khác xuất hiện: trong khi postsđược lưu trữ trong một MySQL database thì likes lại được lưu tại Redis store! Bạn biết mình phải làm gì trong trường hợp nào không?

MỞ RỘNG VẤN ĐỀ TRÊN RA VỚI VIỆC FACEBOOK PHẢI QUẢN LÍ VÔ SỐ DATA SOURCE VÀ API CLIENTS THÌ CŨNG LÀ ĐIỀU DỄ HIỂU KHI REST APIS BỊ ĐÁNH GIÁ LÀ CŨ KĨ BỞI NHỮNG HẠN CHẾ CỦA NÓ.

Giải pháp

Giải pháp mà Facebook đưa ra đến từ một ý tưởng rất đơn giản: Thay vì có đến hàng tá “endpoint” ngu ngốc, sao lại không dùng chỉ một “endpoint” thông minh với khả năng tiếp thu những Query phức tạp rồi đưa ra output data với loại type tùy theo yêu cầu của client.

Thế tế mà nói, GraphQL như là một layer nằm giữa client và data source, sau khi nhận yêu cầu của client thì nó sẽ kiếm những thông tin cần từ các data source và đưa lại cho client theo format họ muốn. Vẫn chưa hiểu? Thế thì đến lúc dùng ví dụ ẩn dụ rồi đây!

Như bạn thấy đấy, REST model cũ giống y như việc bạn đặt cái bánh Pizza, rồi gọi ship hàng online và kêu bên tiệm giặt ủi đem đồ đến cho bạn. Tất cả diễn ra với 3 cuộc gọi và 3 cửa hàng.

GraphQL mặt khác lại giống như là thư kí riêng của bạn vậy: Sau khi bạn đưa địa chỉ của 3 cửa hàng và nói yêu cầu của bạn thì GraphQL sẽ làm hết mọi chuyện còn lại trong khi bạn chỉ việc chờ chúng được chuyển đến cho mình.

Nói cách khác GraphQL tạo ra một ngôn ngữ chuẩn (standard language) để thực hiện những công việc này.

GraphQL API được tạo ra từ 3 phần chính: schema, queries, và resolvers

Queries

Những yêu cầu bạn đặt ra cho thư kí của mình, GraphQL, được gọi là query và nó giống như thế này:

query {
  stuff
}

Chúng ta tuyên bố một ‘query’ mới sử dụng keyword query , và đặt tên cho field đó là stuff. Điều thú vị của GraphQLquery là có support các nested fields. Thế nên chúng ta có thể đi sâu vào hơn:

query {
  stuff {
    eggs
    shirt
    pizza
  }
}

Như bạn thấy đấy, client khi đưa ra những yêu cầu và tạo ra query sẽ không cần lo data đến từ source nào. Chỉ việc hỏi và GraphQLserver sẽ lo hết mọi thứ khác.

Cũng đáng lưu ý là việc các query field còn có khả năng chỉ đến các array

query {
  posts { # this is an array
    title
    body
    author { # we can go deeper!
      name
      avatarUrl
      profileUrl
    }
  }
}

Query field còn support cả argument. Nếu bạn muốn đưa ra một post riêng, thì chỉ cần thêm id argument cho post field.

query {
  post(id: "123foo"){
    title
    body
    author{
      name
      avatarUrl
      profileUrl
    }
  }
}

Cuối cùng, nếu bạn còn muốn id argument đó đặc biệt hơn, bạn có thể tạo ra một variable và tái sử dụng chúng bên trong query (nhớ là ta phải đặt tên cái query đó luôn)

query getMyPost($id: String) {
  post(id: $id){
    title
    body
    author{
      name
      avatarUrl
      profileUrl
    }
  }
}

Một cách thực hành khá tốt là sử dụng GitHub’s GraphQLAPI Explorer. Hãy thử query sau:

query {
  repository(owner: "graphql", name: "graphql-js"){
    name
    description
  }
}

Bạn sẽ thấy rằng việc bạn thử đặt tên cho một field ở bên dưới description, IDE sẽ tự động gợi ý cho bạn những tên field có sẵn hoặc tự tạo bởi chính GraphQLAPI ! Khá hay đúng không?

Resolvers

Cho dù có là thư ký giỏi nhất quả đất cũng không thể đi lấy quần áo cho bạn nếu không có địa chỉ của tiệm giặt đồ.

Tương tự vậy, GraphQLserver sẽ không biết phải làm gì với query bạn đưa ra trừ khi nó biết được resolver.

RESOLVER NÓI CHO GRAPHQL BIẾT NƠI VÀ CÁCH THỨC ĐỂ LẤY DATA CẦN THIẾT CHO FIELD CỦA QUERY MÀ BẠN YÊU CẦU. SAU ĐÂY LÀ MỘT RESOLVER CHO FIELD `POST` Ở TRÊN (SỬ DỤNG APOLLO’S GRAPHQL-TOOLS SCHEMA GENERATOR):

Query: {
  post(root, args) {
    return Posts.find({ id: args.id });
  }
}

Ta đặt resolver ngay trong Query bởi vì ta muốn query cho post ngay lập tức. Tuy nhiên, bạn vẫn có thể dùng resolver trong sub-field, như author field của post

Query: {
  post(root, args) {
    return Posts.find({ id: args.id });
  }
},
Post: {
  author(post) {
    return Users.find({ id: post.authorId})
  }
}

Nhớ lưu ý rằng resolver sẽ không bị giới hạn bởi trong số lượng thông tin được đưa về nên bạn sẽ muốn thêm commentsCount cho Post type:

Post: {
  author(post) {
    return Users.find({ id: post.authorId})
  },
  commentsCount(post) {
    return Comments.find({ postId: post.id}).count() 
  }
}

Điều quan trong bạn cần hiểu ở đây là với GraphQL, API schema của bạn và database schema sẽ bị chia ra riêng biệt. Nói cách khác, có thể sẽ không có bất kì author và commentsCount nào trong database của mình nhưng ta vẫn có thể “mô phỏng” chúng nhờ vào resolver.

Bạn có thể viết bất kì code gì trong resolver, vì thế mà bạn có thể dùng chúng để sửa đổi nội dung của database, vốn còn được gọi là mutation resolver.

Schema

Tất cả mọi thứ hay ho trên đều nhờ vào hệ thống GraphQL’s typed schema.

Schema trong GraphQL là một phần rất quan trọng, nó định nghĩa các loại kiểu dữ liệu, các truy vấn (query) và thao tác (mutation) có sẵn. Schema giúp bạn định nghĩa cách các truy vấn và dữ liệu sẽ được trao đổi giữa client và server. Nó đóng vai trò như một bản mô tả cho hệ thống GraphQL và cung cấp cho client một loạt các truy vấn và kiểu dữ liệu mà client có thể truy xuất thông tin.

Schema bao gồm ba phần chính:

Khai báo các kiểu dữ liệu (Type Definitions): Định nghĩa các loại dữ liệu có thể được truy vấn hoặc trả về. Đây bao gồm các kiểu tự định nghĩa (custom types) và các kiểu vô hướng (scalar types) như String, Int, Float, và Boolean.
Truy vấn (Query): Đây là điểm bắt đầu để lấy dữ liệu từ API GraphQL. Bạn định nghĩa các truy vấn mà client có thể thực hiện và dữ liệu trả về tương ứng với mỗi truy vấn. Truy vấn (query) trong GraphQL thường chỉ dùng để đọc dữ liệu từ server.
Thao tác (Mutation): Nếu bạn muốn thay đổi (cập nhật, thêm mới, xóa) dữ liệu trên server thông qua GraphQL, bạn cần sử dụng thao tác. Thao tác (mutation) cho phép bạn định nghĩa các hành động mà client có thể thực hiện để thay đổi dữ liệu.

Ví dụ về một schema đơn giản trong GraphQL:

type Author {
  id: ID!
  name: String!
  posts: [Post!]!
}

type Post {
  id: ID!
  title: String!
  body: String!
  author: Author!
}

type Query {
  getAuthor(id: ID!): Author
  getPosts: [Post!]!
}

type Mutation {
  createPost(title: String!, body: String!, authorId: ID!): Post!
  updatePost(id: ID!, title: String, body: String): Post
  deletePost(id: ID!): Boolean!
}

schema {
  query: Query
  mutation: Mutation
}

GraphQLdocumentation

https://graphql.org/learn/schema/

Trong ví dụ trên, chúng ta có hai kiểu tự định nghĩa là Author và Post, một số truy vấn và thao tác liên quan đến việc lấy thông tin tác giả (getAuthor), danh sách bài viết (getPosts), tạo mới bài viết (createPost), cập nhật bài viết (updatePost), và xóa bài viết (deletePost).

Câu hỏi thường gặp

Mối quan hệ giữa GraphQL và graph database là như thế nào?

Thật ra là chẳng nhiều, như họ hàng rất xa ấy, GraphQL chả có dính dáng gì tới graph database như Neo4j. Phần “graph” đến từ ý tưởng theo dõi API graph bằng field và subfield trong khi “QL” ám chỉ cho “query language”

Rest vẫn còn tốt chán, sao lại phải chuyển qua GraphQL?

Nếu như bạn vẫn chưa bị phiền bởi sự hạn chế của Rest thì tốt thôi! Bởi việc dùng GraphQL thay vì REST chắc cũng sẽ không ảnh hưởng đến trải nghiệm người dùng từ app của bạn thế nên việc thay đổi cũng không phải mang tính sống còn hay gì. Tuy vậy, tôi vẫn khuyến khích bạn thử GraphQL trong một project nhỏ nếu có cơ hội.

Liệu tôi có thể dùng GraphQL mà không cần tới React/Relay/Các loại library?

Tất nhiên là được! Bởi GraphQL chỉ đơn giản là một kỹ thuật, bạn có dùng nó trên bất cứ library và platform nào bạn thích cùng với client hoặc tự tạo ra một GraphQL server.

GraphQL tạo ra bởi Facebook mà tôi thì chả tin vào Facebook

Lần nữa, GraphQL chỉ là một kĩ thuật, điều đó có nghĩa là bạn có thể dùng những ứng dụng của GraphQL mà không phải chạy bất kì một dòng code nào của Facebook.

Đồng thời với sự giúp đỡ của Facebook quả là một điểm cộng cho ecosystem của GraphQL, tại thời điểm này tôi tin rằng cộng đồng phát triển đã đủ lớn để GraphQL tiếp tục sống cho dù Facebook có ngưng xài nó.

Cả cái mô hình kinh doanh “để client yêu cầu data mà họ cần” nghe có vẻ không an toàn….

Tại bạn là người viết ra resolver, nó hoàn toàn phụ thuộc vào bạn để đưa ra những cách thức an ninh.

NẾU BẠN CHO PHÉP CLIENT ĐƯỢC PHÉP TRUY CẬP MỘT SỐ CÁC THÔNG TIN ĐẶC BIỆT THÌ BẠN SẼ MUỐN HẠN CHẾ SỐ LƯỢNG NHẰM TRÁNH VIỆC CLIENT YÊU CẦU QUÁ NHIỀU.

Vậy tôi nên bắt đầu từ đâu đây?

Thông thường mà nói, bạn sẽ cần 2 thứ sau để có thể chạy một app tạo ra từ GraphQL:

một GraphQL server với mục đích phục vụ cho API của bạn
một GraphQL client để kết nối với endpoint của bạn

GraphQL Servers

Điều đầu tiên bạn cần là một GraphQL server. Bản thân GraphQL chỉ là một kĩ thuật thế nên vẫn còn nhiều khoảng trống cho việc cải thiện.

(Node)

Vốn là nguồn tham khảo để cải thiện cho GraphQL. Bạn có dùng nó kèm với express-graphql để tạo ra API server cho mình.

(Node)

Nhóm Apollo có riêng hẳn một GraphQL server implementation, tuy là không được biết đến nhiều như bản chính nhưng vẫn phát triển cực kì nhanh.

GraphQL.org có hẳn một list về các implementation của GraphQL trên các platform khác nhau

GraphQL Clients

Relay là bộ GraphQL toolkit của chính Facebook. Tôi vẫn chưa xài đến nó, nhưng theo những gì nghe được thì có vẻ Relay được tạo ra dựa trên những yêu cầu của Facebook thế nên nó có vẻ hơi đòi hỏi quá mức kĩ thuật so với đại đa số người dùng.

Dù chỉ mới xuất hiện nhưng đã nhanh chóng soán ngôi bá chủ, Apollo client thường bao gồm 2 yếu tố sau:

Apollo Client, dùng để chạy GraphQL query trên các trình duyệt web cũng như lưu trữ data của họ.
Một kết nối cho front-end framework của bạn (React-Apollo, Angular-Apollo, etc.)

Cần nhớ rằng nếu để ở chế độ default, Apollo-client sẽ lưu dữ liệu của nó bằng Redux, một library khá tốt với hệ ecosystem đa dạng.

Một số GraphQL Tool khác

GraphiQL cực kì hữu dụng cho trong trình duyệt IDE cho query GraphQL endpoints

Bởi vì các GraphQLquery kết nối với nhau như mạng lưới, một query cũng có khả năng kích hoạt hàng loạt các database call khiến cho performance bị giảm mạnh do lag spike.

ĐỂ TRÁNH TRƯỜNG HỢP ĐÓ, BẠN CÓ THỂ SỬ DỤNG NHỮNG LIBRARY DATALOADER, VỐN ĐƯỢC PHÁT TRIỂN BỞI CHÍNH FACEBOOK.

Create GraphQL Server là một command line utility nhằm giúp triển khai nhanh một GraphQLserver nhờ vào Node server và Mongo database.

Tương tự như Create GraphQLServer, GraphQL-up cho phép bạn tạo ra GraphQL back-end cực nhanh nhờ vào GraphCool.

GraphQL Services

Cuối cùng, hiện tại đã có một số công ty thuộc dạng chuyên cung cấp “GraphQL-backend” dịch vụ sẽ lo cho bạn phần server nhờ đó mà việc tham gia vào

GraphQLecosystem cũng trở nên đáng để thử hơn.

Một backend platform khá linh hoạt với sự kết hợp giữa GraphQL và AWS Lambda.

Thêm một dịch vụ GraphQLbackend với nhiều tính năng tương tự như Graphcool.

Sau khi đã trang bị cho mình những kiến thức về GraphQL thì bạn sẽ dùng chúng như thế nào? Hãy thử một số combo sau:

Nếu bạn đã làm quen với Next.js và React, ví dụ sau sẽ cho phép bạn set up một GraphQLendpoint nhờ vào Graphcool rồi query nó nhờ vào Apollo.

Vulcan tutorial sẽ hướng dẫn bạn cách tạo ra một GraphQLdata layer đơn giản, trên cả server và client. Do Vulcan là một all-in-one platform, cách tốt nhất là bắt đầu từ số 0. Nếu bạn cần sự giúp đỡ thì đừng ngại gì mà hãy vào đây.

Chroma blog bao gồm 6 phần hướng dẫn cách tạo ra một React/GraphQL app dựa trên cách tiếp cận phát triển theo từng thành phần.

via: TopDev