Persisted Queries
Sử dụng các queries GraphQL để tạo các endpoint được định nghĩa sẵn như trong REST, đồng thời thu được lợi ích từ cả hai API.
Mô tả
Với REST, bạn tạo nhiều endpoint, mỗi endpoint trả về một tập dữ liệu được định nghĩa sẵn.
| Ưu điểm | Nhược điểm |
|---|---|
| ✅ Đơn giản | ❌ Tẻ nhạt khi phải tạo tất cả các endpoint |
✅ Truy cập qua GET hoặc POST | ❌ Dự án có thể gặp tắc nghẽn khi chờ các endpoint sẵn sàng |
| ✅ Có thể cache trên server hoặc CDN | ❌ Bắt buộc phải tạo tài liệu |
| ✅ Bảo mật: chỉ dữ liệu dự kiến mới được hiển thị | ❌ Có thể chậm (đặc biệt với ứng dụng di động), vì ứng dụng có thể cần nhiều request để lấy toàn bộ dữ liệu |
Với GraphQL, bạn cung cấp bất kỳ query nào tới một endpoint duy nhất, endpoint đó trả về chính xác dữ liệu được yêu cầu.
| Ưu điểm | Nhược điểm |
|---|---|
| ✅ Không lấy thiếu hoặc thừa dữ liệu | ❌ Chỉ truy cập được qua POST |
| ✅ Có thể nhanh, vì tất cả dữ liệu được lấy trong một request duy nhất | ❌ Không thể cache trên server hoặc CDN, khiến nó chậm hơn và tốn kém hơn mức cần thiết |
| ✅ Cho phép lặp vòng phát triển dự án nhanh chóng | ❌ Có thể phải tái tạo những thứ đã có sẵn, chẳng hạn như tải lên tệp hoặc caching |
| ✅ Có thể tự tài liệu hóa | ❌ Phải xử lý các phức tạp bổ sung, như vấn đề N+1 |
| ✅ Cung cấp trình soạn thảo cho query (GraphiQL) giúp đơn giản hóa công việc |
Persisted queries kết hợp 2 cách tiếp cận này lại với nhau:
- Sử dụng GraphQL để tạo và giải quyết các queries
- Nhưng thay vì chỉ hiển thị một endpoint duy nhất, nó hiển thị mỗi query được định nghĩa sẵn dưới endpoint riêng của nó
Do đó, chúng ta có được nhiều endpoint với dữ liệu được định nghĩa sẵn như trong REST, nhưng được tạo bằng GraphQL, thu được ưu điểm của từng cách và tránh được nhược điểm của chúng:
| Ưu điểm | Nhược điểm |
|---|---|
✅ Truy cập qua GET hoặc POST | |
| ✅ Có thể cache trên server hoặc CDN | |
| ✅ Bảo mật: chỉ dữ liệu dự kiến mới được hiển thị | |
| ✅ Không lấy thiếu hoặc thừa dữ liệu | |
| ✅ Có thể nhanh, vì tất cả dữ liệu được lấy trong một request duy nhất | POST |
| ✅ Cho phép lặp vòng phát triển dự án nhanh chóng | |
| ✅ Có thể tự tài liệu hóa | |
| ✅ Cung cấp trình soạn thảo cho query (GraphiQL) giúp đơn giản hóa công việc |
Thực thi Persisted Query
Sau khi persisted query được xuất bản, chúng ta có thể thực thi nó thông qua permalink của nó.
Persisted query có thể được thực thi trực tiếp trong trình duyệt, vì nó được truy cập qua GET, và chúng ta sẽ nhận được dữ liệu được yêu cầu ở định dạng JSON:
Tạo một Persisted Query
Nhấp vào liên kết Persisted Queries trong menu sẽ hiển thị danh sách tất cả các persisted queries đã được tạo:
Persisted query là một custom post type (CPT). Để tạo một persisted query mới, nhấp vào nút "Add New GraphQL persisted query", thao tác này sẽ mở trình soạn thảo WordPress:
Đầu vào chính là client GraphiQL, đi kèm với Explorer theo mặc định. Nhấp vào các trường ở bảng điều khiển bên trái sẽ thêm chúng vào query, và nhấp vào nút "Run" sẽ thực thi query:
Khi query đã sẵn sàng, hãy xuất bản nó, và permalink của nó sẽ trở thành endpoint. Liên kết tới endpoint (và tới nguồn) được hiển thị trên bảng điều khiển thanh bên "Persisted Query Endpoint Overview":
Thêm ?view=source vào permalink, nó sẽ hiển thị persisted query và cấu hình của nó (miễn là người dùng đã đăng nhập và vai trò người dùng có quyền truy cập):
Theo mặc định, endpoint của persisted query có đường dẫn /graphql-query/, và giá trị này có thể cấu hình thông qua Cài đặt:
Cấu hình schema
Việc định nghĩa schema chứa những phần tử nào và người dùng sẽ có quyền truy cập như thế nào được xác định trong cấu hình schema.
Vì vậy, chúng ta phải tạo một cấu hình schema, rồi chọn nó từ danh sách thả xuống:
Sắp xếp Persisted Queries theo danh mục
Trên bảng điều khiển thanh bên "Endpoint categories" chúng ta có thể thêm các danh mục để giúp quản lý Persisted Query:
Ví dụ, chúng ta có thể tạo các danh mục để quản lý các endpoint theo khách hàng, ứng dụng, hoặc bất kỳ thông tin cần thiết nào khác:
Trong danh sách Persisted Queries, chúng ta có thể xem các danh mục của chúng và khi nhấp vào bất kỳ liên kết danh mục nào, hoặc sử dụng bộ lọc ở trên cùng, sẽ chỉ hiển thị tất cả các mục thuộc danh mục đó:
Persisted queries riêng tư
Bằng cách đặt trạng thái của Persisted Query là private, endpoint chỉ có thể được truy cập bởi người dùng quản trị. Điều này ngăn dữ liệu của chúng ta bị chia sẻ không chủ ý với những người dùng không nên có quyền truy cập.
Ví dụ, chúng ta có thể tạo các Persisted Queries riêng tư để giúp quản lý ứng dụng, chẳng hạn như lấy dữ liệu để tạo báo cáo với các chỉ số của chúng ta.
Persisted queries được bảo vệ bằng mật khẩu
Nếu chúng ta tạo Persisted Query cho một khách hàng cụ thể, chúng ta có thể gán mật khẩu cho nó để cung cấp thêm một lớp bảo mật, đảm bảo chỉ khách hàng đó mới truy cập được endpoint.
Khi lần đầu tiên truy cập vào persisted query được bảo vệ bằng mật khẩu, chúng ta sẽ gặp màn hình yêu cầu nhập mật khẩu:
Sau khi mật khẩu được cung cấp và xác thực, lúc đó người dùng mới có thể truy cập endpoint dự kiến.
Làm cho persisted query động thông qua tham số URL
Giá trị của mỗi biến có thể được đặt thông qua tham số URL (với tên biến) khi thực thi persisted query. Nếu tùy chọn "Do URL params override variables?" được bật, thì tham số URL sẽ được ưu tiên. Ngược lại, giá trị được định nghĩa trong từ điển biến sẽ được ưu tiên (nếu có).
Ví dụ, trong query này, số lượng kết quả được kiểm soát thông qua biến $limit, với giá trị mặc định là 3:
Khi thực thi persisted query này, truyền ?limit=5 sẽ thực thi query và trả về 5 kết quả thay thế:
