Bộ công cụ GraphQL

Định dạng, rút gọn và kiểm tra thao tác GraphQL, duyệt schema, phát hiện thay đổi gây lỗi giữa hai phiên bản schema, rồi sinh kiểu TypeScript, truy vấn và đoạn mã gửi yêu cầu — tất cả trên một trang, ngay trong trình duyệt của bạn.

Các bước sử dụng

1. Ở tab Định dạng & kiểm tra, dán query, mutation, subscription hoặc fragment vào khung Thao tác, hoặc dùng Mở tệp hay Mẫu. Khung bên phải cập nhật ngay khi bạn gõ: lỗi cú pháp hiện dòng bị lỗi kèm dấu mũ dưới đúng cột, và mỗi vấn đề có liên kết dòng/cột để nhảy thẳng tới vị trí đó.
2. Nhấn Định dạng để trình bày lại tài liệu cho dễ đọc, hoặc Rút gọn để bỏ chú thích và khoảng trắng thừa. Bảng bên dưới liệt kê từng thao tác cùng các biến của nó, kèm danh sách fragment và Biến không dùng.
3. Để kiểm tra cả trường, tham số và kiểu, mở tab Xem schema và dán schema của bạn — định nghĩa kiểu SDL hoặc kết quả JSON của truy vấn introspection. Quay lại Định dạng & kiểm tra và giữ bật Kiểm tra theo schema.
4. Trong Xem schema, dùng Duyệt kiểu: các kiểu được nhóm thành object, interface, union, enum, input object, scalar và directive. Tìm theo tên kiểu, trường hoặc giá trị enum, nhấn vào tên kiểu bất kỳ để mở, và dùng Quay lại để trở về. Bật Hiện scalar và directive có sẵn để thấy cả String, @deprecated và các mục khác.
5. Ở phần Xuất, chuyển giữa SDL, JSON introspection và Truy vấn introspection, rồi Sao chép hoặc Tải xuống kết quả.
6. Ở tab So sánh schema, dán Schema cũ và Schema mới, hoặc điền một bên bằng Lấy từ Xem schema. Mỗi thay đổi được gắn nhãn Gây lỗi, Rủi ro hoặc An toàn. Bật Chỉ thay đổi gây lỗi và nhấn Sao chép báo cáo để dán danh sách vào pull request.
7. Ở tab Sinh mã, chọn Schema → TypeScript để có kiểu cho toàn bộ schema, Thao tác → TypeScript để có kiểu kết quả và kiểu biến cho các thao tác của bạn, hoặc Dựng truy vấn. Nếu schema có scalar tuỳ chỉnh, đặt kiểu TypeScript cho chúng trong Scalar tuỳ chỉnh → TypeScript.
8. Trong Dựng truy vấn, chọn loại thao tác và trường gốc, đặt Độ sâu, đánh dấu các trường trong Chọn trường, rồi nhấn Mở trong Định dạng & kiểm tra để tiếp tục sửa thao tác vừa tạo. Các biến của nó được điền sẵn ở bên dưới.
9. Ở tab Chuyển đổi, JSON → SDL biến một mẫu JSON thành các kiểu GraphQL, còn cURL / fetch biến thao tác đang chọn thành lệnh cURL, đoạn mã fetch và thân yêu cầu. Nhấn Điền theo kiểu biến để có khung biến mẫu.

Mẹo

• Việc định dạng dùng bộ in chuẩn của graphql-js, nên kết quả khớp với phần lớn công cụ GraphQL. Rút gọn không bao giờ đụng tới nội dung chuỗi hay block string, nên "a # b" vẫn nguyên vẹn.
• Khi chưa có schema, công cụ vẫn bắt được lỗi cú pháp, biến không dùng hoặc chưa khai báo, fragment không dùng hoặc không tồn tại, và tên thao tác bị trùng. Khi có schema, công cụ chạy mọi quy tắc validation của đặc tả GraphQL.
• Ô schema nhận kết quả introspection ở mọi dạng thường gặp: bọc trong data, object có __schema, hoặc chỉ riêng object __schema.
• Gây lỗi nghĩa là truy vấn hiện có có thể thất bại: xoá kiểu, trường, giá trị enum hoặc tham số, đổi kiểu, hoặc thêm tham số hay trường input bắt buộc. Rủi ro nghĩa là hành vi có thể thay đổi: thêm giá trị enum hoặc thành viên union, thêm tham số tuỳ chọn, hoặc đổi giá trị mặc định.
• TypeScript được sinh ra biến trường nullable thành T | null và cho tham số, trường input nullable hoặc có mặc định thành tuỳ chọn. Trong kiểu cho thao tác, alias trở thành khoá, fragment được gộp vào, lựa chọn trên union hoặc interface thành union phân biệt bằng __typename, và trường dưới @include hoặc @skip thành tuỳ chọn.
• Độ sâu giữ cho các kiểu đệ quy như User → posts → author → … không kéo dài vô tận. Trường gắn nhãn "vòng lặp" trả về một kiểu đã xuất hiện phía trên nó trong cây.
• JSON → SDL chỉ là điểm khởi đầu: hãy xem lại tên kiểu, và thay String bằng enum hoặc scalar tuỳ chỉnh khi phù hợp.

Mọi thứ chạy ngay trong trình duyệt — truy vấn, schema và token không bao giờ được tải lên, nên bạn có thể yên tâm dán schema nội bộ hoặc chưa phát hành.

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

Schema hoặc truy vấn của tôi có bị gửi đi đâu không?

Không. Việc phân tích, kiểm tra, so sánh và sinh mã đều diễn ra trên thiết bị của bạn, và trang không gửi bất kỳ yêu cầu mạng nào chứa dữ liệu bạn nhập.

Vì sao công cụ không chạy được truy vấn của tôi trên API của tôi?

Trang được thiết kế để không bao giờ gọi endpoint. Trình duyệt chặn yêu cầu khác nguồn trừ khi API gửi header CORS cho trang này, còn chuyển truy vấn qua proxy sẽ làm lộ token và dữ liệu của bạn. Hãy sao chép đoạn mã cURL hoặc fetch ở tab Chuyển đổi rồi chạy trong terminal hay trong ứng dụng, hoặc dùng client GraphQL như GraphiQL, Altair hay Insomnia.

Làm sao lấy schema của một API đang chạy?

Sao chép Truy vấn introspection ở phần Xuất của Xem schema, chạy nó bằng client của bạn kèm header xác thực, rồi dán kết quả JSON vào ô schema. Nếu introspection bị tắt trên production, hãy xuất SDL từ mã nguồn máy chủ.

Công cụ báo trường không tồn tại dù máy chủ của tôi có — vì sao?

Schema bạn dán cũ hơn hoặc khác với schema máy chủ đang chạy. Hãy dán kết quả introspection mới, hoặc tắt Kiểm tra theo schema để chỉ kiểm tra cú pháp.