Hệ sinh thái công cụ

GraphQL không phải là một sản phẩm duy nhất. Một hệ thống GraphQL thường ghép schema, runtime thực thi, HTTP transport, client, hạ tầng biên và công cụ kiểm thử, quan sát. Mỗi lớp trả lời một câu hỏi khác nhau: API cho phép gì, request được thực thi ra sao, ai gọi API, và team có kiểm soát được thay đổi trong production hay không.

Mục lục

• Đọc bản đồ hệ sinh thái
  • Một request đi qua những lớp nào
• Phân loại công cụ theo vai trò
  • Server và runtime
  • IDE và trình khám phá
  • Công cụ HTTP
  • Client phía frontend
  • Client Java và WebClient
  • Gateway federation và kho đăng ký schema
  • Quan sát hệ thống và kiểm thử
• Phân biệt những cặp dễ nhầm
  • Server không phải client
  • Spring for GraphQL và GraphQL Java
  • GraphiQL không phải GraphQL server
  • Gateway không phải schema registry
• Ma trận chọn công cụ
  • Chọn theo nhu cầu
  • Chọn theo tiêu chí đánh đổi
• Quy trình từ schema tới production
  • Từ SDL đến endpoint
  • Từ endpoint đến client
  • Từ client đến production
• Điểm rút ra thực hành
• Bước tiếp theo

Đọc bản đồ hệ sinh thái

GraphQL là gì? giải thích schema, operation và execution result. Kiến trúc GraphQL sẽ đặt client, server, resolver và data source vào cùng một flow. Trang này bổ sung lớp công cụ: công cụ nào đứng ở đâu và nên được đưa vào giai đoạn nào.

Một request đi qua những lớp nào

Một ứng dụng nhỏ không cần dùng toàn bộ hệ sinh thái. Luồng dưới đây cho thấy các lớp thường gặp và các lựa chọn có thể thay thế cho nhau trong cùng một vai trò:

Schema SDL + ownership + review
             │
             ├──────────────► schema checks / schema registry
             │
             ▼
GraphQL server application
Spring for GraphQL ──► graphql-java ──► resolver ──► data source
             │
             ▼
GraphQL endpoint trực tiếp hoặc qua gateway/router
             │
       ┌─────┼────────────┬─────────────────┐
       ▼     ▼            ▼                 ▼
   GraphiQL  curl      Postman      Apollo / urql / Java client
       │     │            │                 │
       └─────┴────────────┴─────────────────┘
             │
             ▼
authentication ── caching ── tests ── telemetry ── production policy

Sơ đồ dùng code block text để không phụ thuộc renderer. Repo chưa cấu hình Mermaid renderer, nên không giả định rằng một fence mermaid sẽ được dựng thành diagram khi build docs.

Có thể đọc sơ đồ theo hai chiều. Từ trên xuống, schema và ownership định hình contract, server thực thi contract, rồi các client gửi operation. Từ dưới lên, telemetry và test cung cấp bằng chứng rằng request thật phù hợp với contract và chính sách vận hành. Gateway, registry, cache hoặc code generation là các lớp bổ sung theo nhu cầu; chúng không tự biến một project chưa có server thành GraphQL API.

Phân loại công cụ theo vai trò

Server và runtime

Server là ứng dụng nhận request và áp dụng chính sách của hệ thống. Runtime là phần parse, validate và execute operation theo schema. Trong stack Java/Spring, hai tên thường xuất hiện cùng nhau nhưng không cùng một vai trò:

Với ứng dụng Spring Boot, spring-boot-starter-graphql thường cung cấp các dependency tương thích để Spring for GraphQL dùng GraphQL Java. Hãy để Spring Boot quản lý version qua parent hoặc BOM thay vì trộn các version riêng lẻ. Tích hợp Spring for GraphQL là nhóm bài đi sâu vào mapping, context và lifecycle.

Điểm quan trọng là Spring for GraphQL và graphql-java phối hợp để tạo phần GraphQL của server, nhưng vẫn cần web stack, schema, resolver, data source và chính sách ứng dụng. Thêm một thư viện runtime không tự tạo endpoint nghiệp vụ có dữ liệu. Ngược lại, một schema hợp lệ cũng chưa chứng minh resolver đã chạy.

IDE và trình khám phá

GraphiQL là một GraphQL IDE trên trình duyệt. Nó cung cấp editor, autocomplete, Docs explorer, ô variables, headers và vùng hiển thị execution result. GraphiQL thường gọi introspection để đọc metadata schema, nhờ đó người học có thể đi từ Query đến field mà không phải nhớ tên bằng tay.

GraphiQL phù hợp nhất cho:

• khám phá contract khi đang phát triển;
• thử một operation nhỏ và nhìn ngay data, errors;
• kiểm tra variables, headers và selection set;
• tái hiện lỗi validation hoặc execution trước khi viết test tự động.

GraphiQL phải gửi request đến một GraphQL endpoint đang tồn tại. Mở được trang /graphiql chỉ chứng minh UI được phục vụ; nó không chứng minh /graphql có resolver, data source hoặc quyền truy cập đúng. Introspection cũng chỉ cho biết schema có gì, không cấp quyền đọc dữ liệu. Xem GraphiQL và công cụ khám phá API để phân biệt URL giao diện với endpoint và cách đọc lỗi.

Trong production, GraphiQL và introspection cần policy rõ ràng. Có thể chỉ bật UI ở local, yêu cầu authentication, giới hạn mạng hoặc cung cấp tài liệu chọn lọc. Ẩn Docs explorer không thay thế authorization ở server.

Công cụ HTTP

curl và Postman đều là HTTP client. Chúng vận chuyển JSON envelope tới endpoint; chúng không phải GraphQL server và cũng không thay thế GraphQL execution engine.

Cả hai nên gửi tới /graphql hoặc path đã cấu hình, không gửi POST tới URL UI /graphiql. Body GraphQL thường có query, variables và operationName; authentication nằm ở HTTP headers. Header Authorization chỉ mang credentials tới server, không tự bật Spring Security hay tạo quyền cho request.

Bài Kiểm thử request bằng curl/Postman có các ví dụ envelope, negative case và smoke test. Không cần dùng Postman nếu curl đã đủ cho pipeline, cũng không cần dùng GraphiQL trong CI chỉ vì GraphiQL tiện khi khám phá.

Client phía frontend

Apollo Client và urql là thư viện phía frontend. Chúng quản lý việc gửi operation, variables, loading state, error state và việc đưa response vào state/cache của ứng dụng. Một số workflow còn dùng schema và operation để sinh TypeScript type, giúp phát hiện sai field ngay trong build.

• Apollo Client thường phù hợp khi team cần hệ sinh thái lớn, normalized cache, nhiều policy fetch/error và công cụ phát triển đã tích hợp. Đổi lại, cấu hình và mô hình cache có thể tạo thêm độ phức tạp.
• urql thiên về lõi nhỏ và pipeline có thể lắp ghép qua các exchange. Nó phù hợp khi team muốn tự chọn mức cache, persisted operation hoặc retry; capability thực tế phụ thuộc package và version được thêm vào project.

Hai thư viện này không execute resolver và không bảo vệ dữ liệu ở server. Client cache chỉ là bản sao ở phía gọi API; nó không thay thế cache/invalidation ở server, authorization, rate limit hoặc kiểm tra query complexity. Khi dùng code generation, hãy coi generated code là sản phẩm của pipeline schema và operation, không phải bằng chứng rằng runtime auth hoặc response lỗi một phần đã được xử lý.

Client Java và WebClient

Khi một ứng dụng Java gọi một GraphQL service khác, có hai hướng thường gặp:

1. Java GraphQL client có typing hoặc generated code: công cụ đọc schema và operation để tạo model, request builder hoặc response type. Hướng này giảm lỗi chính tả field và giúp thay đổi schema lộ ra ở bước build. Đổi lại, build phải tải schema đúng version và code sinh ra có thể tạo coupling với contract.
2. Spring WebClient: HTTP client bất đồng bộ, cho phép tự tạo JSON envelope và kiểm soát timeout, header, retry, connection pool cùng instrumentation. WebClient không tự hiểu schema GraphQL, không tự validate selection set và không tự biến errors trong body thành exception nghiệp vụ; application phải xử lý các phần đó hoặc kết hợp một thư viện GraphQL khác.

Chọn generated Java client khi schema ổn định, type safety đáng giá và team chấp nhận pipeline sinh code. Chọn WebClient khi cần kiểm soát transport, gọi nhiều API khác nhau hoặc muốn giữ lớp phụ thuộc mỏng. Dù chọn hướng nào, client service vẫn phải đọc cả HTTP status, data và errors, đặt timeout và truyền authentication theo policy. Client và tích hợp là bản đồ các bài về Spring WebClient và Java GraphQL client.

Gateway federation và kho đăng ký schema

Ba khái niệm này thường xuất hiện khi graph có nhiều service hoặc nhiều team. Chúng có liên quan nhưng không đồng nghĩa:

Một API gateway HTTP thông thường có thể chỉ route /graphql; nó không mặc nhiên compose schema. Federation cần router và implementation tương thích ở các subgraph; việc có Spring for GraphQL không tự bật federation. Schema registry cũng không phải server dữ liệu: registry có thể từ chối một schema breaking trong CI nhưng không resolve query cho client.

Federation có thể làm ownership theo domain rõ hơn, nhưng đổi lại là kế hoạch thực thi phân tán, latency giữa subgraph, auth xuyên service, cache và telemetry khó hơn. Stitching có thể hữu ích khi cần ghép các schema hiện hữu, nhưng mapping tên, lỗi và ownership dễ trở thành trách nhiệm tập trung ở gateway. Đọc Federation và schema stitching khi hệ thống thật đã có nhu cầu compose; không thêm lớp này chỉ vì một GraphQL endpoint hiện tại có nhiều type.

Quan sát hệ thống và kiểm thử

Observability là khả năng suy ra trạng thái bên trong từ log, metric và trace. Với GraphQL, một URL /graphql có thể mang nhiều operation shape, nên chỉ ghi method và URL là chưa đủ. Tùy mức instrumentation, telemetry nên liên kết được:

• operationName hoặc query hash đã normalize;
• thời gian tổng và lỗi theo operation;
• complexity, depth hoặc số node nếu server có tính;
• resolver/field chậm và downstream call;
• cache hit/miss, tenant hoặc user đã được làm mờ;
• correlation ID để nối request với log và trace.

Không log token, toàn bộ variables hoặc dữ liệu cá nhân vô điều kiện. Query text nguyên bản có thể làm metrics cardinality tăng mạnh; hash hoặc nhóm theo operation giúp dashboard ổn định hơn. Micrometer, OpenTelemetry và hệ thống log/trace của tổ chức chỉ là các lựa chọn instrumentation; repository này không tuyên bố đã cấu hình chúng.

Testing nên trải qua nhiều lớp thay vì giao hết cho một công cụ:

curl/Postman phù hợp cho smoke và tái hiện request. Chúng không thay thế integration test, schema compatibility check hoặc trace trong production. Chiến lược kiểm thử sẽ đặt các lớp này vào quy trình rộng hơn.

Phân biệt những cặp dễ nhầm

Server không phải client

Server sở hữu việc parse, validate, execute và bảo vệ dữ liệu. Client sở hữu việc chọn operation, truyền variables, hiển thị hoặc tiếp tục xử lý response. Một client có thể gửi query hợp lệ nhưng server vẫn trả lỗi resolver, timeout hoặc data một phần. Ngược lại, server có thể chạy tốt dù GraphiQL, Postman hoặc frontend client chưa được cài.

Khi chẩn đoán, hãy hỏi đúng lớp:

Spring for GraphQL và GraphQL Java

GraphQL Java là execution engine. Spring for GraphQL là lớp tích hợp giúp đưa engine đó vào lifecycle Spring Boot và kết nối resolver Java, transport, context cùng configuration. Có thể dùng GraphQL Java trong stack khác, nhưng GraphQL Java một mình không phải một ứng dụng Spring Boot hoàn chỉnh. Có Spring for GraphQL cũng không có nghĩa đã có schema nghiệp vụ, database hoặc authorization.

Phân biệt này giúp chọn đúng bài học: xem Kiến trúc Spring for GraphQL khi cần hiểu wiring trong Spring, và xem GraphQL là gì? khi cần quay lại contract/execution ở mức GraphQL.

GraphiQL không phải GraphQL server

GraphiQL có thể đọc introspection và gửi:

POST /graphql
Content-Type: application/json

{ "query": "query Health { __typename }", "operationName": "Health" }

Nhưng GraphiQL không tự xử lý __typename, không gọi resolver và không quyết định 401 hay 403. Nó chỉ hiển thị kết quả mà server trả về. Vì vậy, một trang GraphiQL có thể tải thành công trong khi endpoint bị sai path, schema chưa nạp hoặc resolver đang lỗi.

Gateway không phải schema registry

Gateway/router nằm trên đường đi của request runtime. Registry nằm trong quy trình quản lý contract và thường được gọi trong CI, review hoặc release. Gateway có thể trả 401, áp timeout hoặc chuyển request tới subgraph; registry có thể báo một field bị xóa là breaking change. Registry không thay thế gateway, và gateway không tự cho biết client nào còn dùng field deprecated nếu không có telemetry hoặc hệ thống usage tương ứng.

Ma trận chọn công cụ

Không nên bắt đầu bằng câu hỏi “thư viện nào tốt nhất”. Hãy bắt đầu bằng use case, owner và bằng chứng cần có. Một công cụ được chọn tốt là công cụ giải quyết trách nhiệm hiện tại mà không kéo theo nhiều lớp vận hành hơn mức team có thể sở hữu.

Chọn theo nhu cầu

Một app Spring Boot phục vụ một frontend có thể dừng ở bộ nhỏ: Spring for GraphQL, GraphQL Java, GraphiQL cho local, curl cho smoke test và Apollo hoặc urql cho frontend. Chỉ thêm gateway, federation hoặc registry khi có yêu cầu về boundary, ownership, composition hoặc governance mà app hiện tại không giải quyết được.

Chọn theo tiêu chí đánh đổi

Hãy ghi các câu trả lời này vào architecture decision hoặc README của service. Đừng xem “có autocomplete”, “có cache” hoặc “có federation” là tiêu chí đủ; cần ghi rõ ai sở hữu dữ liệu, policy nào bảo vệ request và tín hiệu nào chứng minh hệ thống đang khỏe.

Quy trình từ schema tới production

Workflow sau là một ví dụ thực hành cho một team Java xây dựng GraphQL API bằng Spring Boot. Đây là thứ tự trách nhiệm, không phải danh sách package bắt buộc.

Từ SDL đến endpoint

1. Viết schema và đặt owner. Bắt đầu bằng SDL, field cần công khai, nullability, pagination và quy tắc deprecation. Review schema như một contract độc lập với database. Nếu nhiều team cùng sửa graph, đưa schema check và ownership vào CI hoặc registry.
2. Dựng server runtime. Kết hợp Spring for GraphQL với GraphQL Java, web stack và schema resource. Nối root field với resolver, service và data source. Đặt authentication, authorization, timeout và giới hạn query ở lớp server hoặc edge phù hợp; không đẩy trách nhiệm đó sang GraphiQL.
3. Xác minh contract và execution. Khi có backend thật, dùng introspection hoặc GraphiQL để kiểm tra schema rồi chạy một query nhỏ. Tiếp theo, thử variables, field nullable và một negative case. Schema hiển thị đúng chưa đủ; cần kiểm tra resolver và response thật.

Từ endpoint đến client

4. Ghi lại request trên wire. Dùng curl để tạo request tối thiểu, giữ operationName, variables và headers rõ ràng. Nếu team cần workspace chia sẻ, chuyển request vào Postman collection với environment không chứa secret thật. Assert cả HTTP status, data và errors theo contract.
5. Chọn client theo caller. Frontend dùng Apollo hoặc urql khi cần quản lý state/cache và lifecycle UI. Một service Java dùng generated client khi ưu tiên typing, hoặc WebClient khi ưu tiên kiểm soát HTTP. Cả hai hướng đều phải xử lý timeout, retry có điều kiện, authentication và lỗi GraphQL trong body.
6. Đo trước khi tối ưu. So sánh payload, số round-trip, cache hit, p95 latency và số downstream call của operation đại diện. Client cache có thể làm UI nhanh hơn nhưng không chứng minh server rẻ hơn; một query GraphQL qua một HTTP request vẫn có thể gọi nhiều service phía sau.

Từ client đến production

7. Thêm lớp biên chỉ khi cần. Một app đơn có thể nhận request trực tiếp. Khi cần TLS, routing, rate limit, WAF, auth tập trung hoặc composition, thêm API gateway/router. Khi graph có nhiều subgraph, cân nhắc federation hoặc stitching cùng quy ước ownership và failure handling.
8. Đưa schema vào quy trình release. Chạy schema compatibility check, kiểm tra operation thật của client và đặt thời hạn cho field deprecated. Registry có thể lưu snapshot và usage, nhưng vẫn cần owner quyết định migration và rollback.
9. Gắn telemetry với test. Ghi operation name/hash, latency resolver, downstream error, cache và correlation ID đã làm sạch. Chạy schema, integration, contract và smoke test trong CI; đặt dashboard/SLO theo trải nghiệm client thay vì chỉ theo số request tới /graphql.

Điểm rút ra thực hành

• Server/runtime thực thi contract; client chỉ gọi contract. Spring for GraphQL là lớp tích hợp Spring, còn GraphQL Java là execution engine. Cả hai vẫn cần schema, resolver, data source và policy.
• GraphiQL dành cho khám phá, curl/Postman dành cho HTTP workflow. UI mở được không chứng minh endpoint nghiệp vụ đã chạy.
• Apollo/urql giải quyết trải nghiệm frontend. Java client và WebClient giải quyết service-to-service. Cache hoặc generated code không thay thế auth và error handling ở server.
• Gateway/router, federation và schema registry giải quyết bài toán quy mô khác nhau. Gateway xử lý đường đi/policy runtime, federation hoặc stitching xử lý composition, registry xử lý contract/version. Đừng gom chúng thành một “GraphQL server duy nhất”.
• Production cần bằng chứng. Schema checks, ownership, compatibility, telemetry, auth, cache policy và nhiều lớp test phải đi cùng nhau.

Nói ngắn gọn: chọn công cụ theo vị trí của nó trong flow và theo giai đoạn phát triển. Nếu chưa mô tả được owner, cache key, introspection policy, auth boundary, generated-code pipeline và telemetry cần xem, hãy trì hoãn việc thêm công cụ và làm rõ yêu cầu trước.

Bước tiếp theo

Để nối bản đồ công cụ với lộ trình học, đọc các trang sau: