Apollo Client Devtools: Extension GraphQL Trình Duyệt
Apollo Client Devtools là extension trình duyệt chính thức để kiểm tra một ứng dụng Apollo Client đang chạy, thêm tab Apollo bên cạnh Elements và Console. Nên dùng khi bạn đang truy tìm một cache bị stale hoặc một mutation gửi đi với variables sai — cache inspector giúp bạn khỏi phải rải console.log khắp nơi. Bỏ qua nếu ứng dụng của bạn vẫn dùng Apollo Client 2.x, vì đội ngũ maintainer không còn hỗ trợ phiên bản đó.
Apollo Client Devtools là gì?
Apollo Client Devtools là extension cho Chrome và Firefox, thêm một tab 'Apollo' vào devtools của trình duyệt, nằm cạnh Elements và Console. Nó có bốn panel: Explorer để chạy query GraphQL trực tiếp qua network interface của ứng dụng, một watched query inspector, một mutation inspector, và một cache inspector để tìm kiếm trong cache của Apollo Client theo tên field hoặc giá trị.
Các tính năng debug cốt lõi
- ✓Explorer: một bản Apollo Studio Explorer nhúng sẵn, chạy query lên GraphQL server qua network interface của chính ứng dụng, không cần cấu hình thêm.
- ✓Watched query inspector: liệt kê mọi query đang active cùng variables và kết quả đã cache, cho phép chạy lại từng query riêng lẻ.
- ✓Mutation inspector: hiển thị các mutation đã fire cùng variables, cho phép chạy lại từng mutation.
- ✓Cache inspector: trực quan hóa toàn bộ cache của Apollo Client và cho phép tìm kiếm theo tên field hoặc giá trị.
- ✓Nằm ngay trong tab 'Apollo' bên trong devtools có sẵn của trình duyệt, cạnh Elements và Console — không cần cửa sổ riêng.
- ✓Viết bằng TypeScript, test bằng Jest và React Testing Library theo cấu hình test của chính repo.
Bắt đầu: Cài đặt trình duyệt
Người dùng Chrome cài Apollo Client Devtools từ trang Chrome Web Store (extension ID là jdkknkkbebbapilgoeccciglkfbmbnfm). Người dùng Opera lấy extension này cũng qua Chrome Web Store bằng addon 'Download Chrome Extension' cho Opera. Người dùng Firefox cài từ Firefox Browser Add-ons. Muốn build bản local, clone repo rồi chạy `npm install`, sau đó `npm run build -- --env TARGET=chrome` hoặc `npm run build -- --env TARGET=firefox` — hoặc chạy `npm run dist:chrome` / `npm run dist:firefox` để tạo bản zip phân phối.
Bật Devtools trong ứng dụng của bạn
Ở môi trường dev, tab Apollo tự xuất hiện — Apollo Client tự gắn hook `window.__APOLLO_CLIENT__` vào global object mặc định, trừ khi `process.env.NODE_ENV` được set thành `production`. Ở bản production, hook này bị bỏ qua nên tab sẽ không xuất hiện trừ khi bạn làm một trong hai việc: truyền `connectToDevTools: true` vào constructor của ApolloClient, hoặc tự gắn instance client vào `window.__APOLLO_CLIENT__`. Truyền `connectToDevTools: false` nếu muốn tắt hẳn hook này kể cả ngoài production.
Ai nên dùng Devtools này?
Apollo Client Devtools dành cho bất kỳ ai xây dựng ứng dụng web trên Apollo Client 3.x và cần thấy client đang làm gì — query nào đang active, cache đang chứa gì, mutation nào vừa fire. Nó phù hợp với việc debug hằng ngày của chính developer hơn là quy trình QA hay support, vì dùng tốt công cụ này đòi hỏi hiểu model query/mutation/cache của Apollo Client, chứ không chỉ click qua một network panel chung chung.
Điểm mạnh
- ✓Chạy trực tiếp trên network interface thật, đã đăng nhập sẵn của ứng dụng trong panel Explorer, nên không cần copy-paste token sang một GraphQL client riêng.
- ✓Cache inspector cho tìm kiếm trong cache của Apollo Client theo tên field hoặc giá trị, thay vì phải dump cả object cache ra console.
- ✓Cài đặt chỉ một click từ Chrome Web Store hoặc Firefox Browser Add-ons — không cần bước build cho trường hợp thông thường.
- ✓Giấy phép MIT, do chính đội ngũ Apollo maintain, với repo GitHub công khai (1528 stars, 173 forks) chứ không phải bản fork cộng đồng.
Khả năng tương thích phiên bản Apollo Client
- △Không hỗ trợ Apollo Client 2.x — maintainer nói rõ họ không hỗ trợ phiên bản này với devtools.
- △Các bản Apollo Client 3.x cũ chỉ được hỗ trợ ở mức best-effort; cách khắc phục được khuyến nghị là nâng cấp lên bản minor mới nhất.
- △Ở production, devtools ẩn hoàn toàn trừ khi bạn chủ động expose `window.__APOLLO_CLIENT__` hoặc truyền `connectToDevTools: true` — dễ quên rồi thắc mắc sao tab Apollo không hiện.
- △Bốn panel (Explorer, watched query, mutation, cache) là cố định — README không nhắc đến hệ thống plugin hay extension để thêm panel tùy chỉnh.
Các lựa chọn debug GraphQL khác
Các câu hỏi thường gặp
Cài Apollo Client Devtools cho Chrome bằng cách vào trang Chrome Web Store của extension và bấm add to Chrome; người dùng Opera có thể lấy cùng extension này qua Chrome Web Store bằng addon Download Chrome Extension cho Opera.
Apollo Client Devtools có bản build riêng cho Firefox, cài từ Firefox Browser Add-ons thay vì Chrome Web Store.
Apollo Client Devtools hỗ trợ tích cực bản minor mới nhất của Apollo Client, cố gắng hỗ trợ ở mức best-effort các bản 3.x cũ hơn, và không hỗ trợ Apollo Client 2.x.
Bật Apollo Client Devtools ở production bằng cách truyền `connectToDevTools: true` vào constructor của ApolloClient, hoặc tự gắn instance client vào `window.__APOLLO_CLIENT__`, vì hook này mặc định bị bỏ qua ngoài môi trường dev.
Apollo Client Devtools có thể build local được: clone repo, chạy `npm install`, sau đó `npm run build -- --env TARGET=chrome` (hoặc `TARGET=firefox`), hoặc chạy `npm run dist:chrome` / `npm run dist:firefox` để tạo bản zip phân phối.
Apollo Client Devtools được phát hành theo giấy phép MIT, cùng loại giấy phép được ghi trong metadata của repo GitHub.
Vấn đề mà nó giải quyết
Khi một ứng dụng Apollo Client trả về sai dữ liệu, cách xử lý thông thường là console.log thủ công cache hoặc watched query của client rồi xóa các dòng đó trước khi commit. Apollo Client Devtools giải quyết việc này bằng cách cho GraphQL state — query đang active, kết quả đã cache, và mutation đã fire — một tab riêng trong devtools của trình duyệt, để developer có thể xem cache thay đổi theo thời gian thực thay vì đoán từ JSON trong tab network.
Trường hợp sử dụng tốt nhất
- •Truy tìm lý do một query trả về dữ liệu cũ bằng cách xem trực tiếp kết quả đã cache trong cache inspector.
- •Xác minh một mutation thực sự đã fire với đúng variables mong muốn, thay vì thêm tạm console.log.
- •Khám phá một GraphQL API chưa quen thuộc ngay trong ứng dụng đã đăng nhập sẵn, dùng network interface của panel Explorer.
- •Kiểm tra xem cache của Apollo Client có (hay không có) một field cụ thể trước khi viết hàm cập nhật cache.