Quản trị lược đồ GraphQL: Rà soát thay đổi phá vỡ trước khi phát hành

Tóm tắt nhanh

Quản trị schema GraphQL là kỷ luật phát hành giúp schema vẫn hữu ích khi thay đổi. Trước mỗi lần phát hành, hãy phân loại các chỉnh sửa schema, kiểm thử các thao tác đại diện của client, công bố lộ trình ngừng dùng và xác minh tài liệu. Một không gian làm việc chung như Apidog mang thiết kế, request, kiểm thử, tài liệu và công việc mock về một nơi.

Coi schema GraphQL là hợp đồng công khai, không phải chi tiết triển khai nội bộ.
Phát hiện thay đổi gây gián đoạn trước khi chúng đến tay client.
Thêm trường thay thế trước khi ngừng dùng trường cũ.
Kiểm thử các thao tác đã lưu với schema ứng viên và hợp đồng phản hồi.
Ghi lại quyền sở hữu, quyết định đánh giá, tác động đến người tiêu dùng và ngày loại bỏ.
Công bố ghi chú phát hành cho biết các nhóm client cần thay đổi gì và khi nào.

Giới thiệu

Quản trị schema GraphQL giúp các bản phát hành API không vô tình làm hỏng ứng dụng di động, client web, tích hợp và dịch vụ nội bộ mà không có cảnh báo. GraphQL giúp truy vấn của client linh hoạt, nhưng mỗi trường, đối số, giá trị enum, quy tắc nullable và đối tượng đầu vào vẫn trở thành một phần của hợp đồng một khi client phụ thuộc vào nó.

Hợp đồng đó thay đổi thường xuyên. Một nhóm sản phẩm đổi tên displayName. Một nhóm backend biến đầu vào tùy chọn thành bắt buộc. Một dịch vụ thanh toán xóa một giá trị enum. Mỗi chỉnh sửa có thể trông vô hại trong trình soạn thảo schema nhưng lại làm vô hiệu một thao tác đã lưu trong môi trường production.

Đặc tả GraphQL mô tả hệ thống kiểu, quy tắc xác thực và các vấn đề tiến hóa schema của GraphQL. Nó cung cấp cho các nhóm ngôn ngữ chung. Quản trị cung cấp quy trình phát hành: ai đánh giá thay đổi, các nhóm đánh giá tác động đến client như thế nào, họ kiểm thử ra sao và cách loại bỏ các trường cũ mà không gây sự cố bất ngờ.

Bài viết này tập trung vào kiểm soát phát hành thay vì giới thiệu GraphQL. Nếu nhóm của bạn trước tiên cần một quy trình ở cấp request, hãy xem cách kiểm thử API GraphQL trong Apidog. Bước tiếp theo là đưa các kiểm thử đó vào một quy trình thay đổi schema lâu dài.

Quản trị schema GraphQL là gì?

Quản trị schema GraphQL là một quy trình có thể lặp lại để đánh giá, kiểm thử, ghi tài liệu và phê duyệt các thay đổi schema trước khi phát hành. Quy trình này nhận diện các chỉnh sửa gây hỏng client, yêu cầu một lộ trình di chuyển được phê duyệt và duy trì quyền sở hữu rõ ràng. Mục tiêu là tiến hóa schema có thể dự đoán được: client có thời gian và hướng dẫn để chuyển đổi trước khi hợp đồng cũ biến mất.

Five questions GraphQL schema governance answers before release

Quản trị không có nghĩa là đóng băng schema. Một API GraphQL khỏe mạnh thay đổi cùng sản phẩm. Quy trình giúp nó thay đổi một cách an toàn.

Một chính sách quản trị hữu ích trả lời năm câu hỏi cho mỗi pull request hoặc ứng viên phát hành:

Schema đã thay đổi những gì?
Những thay đổi nào có thể khiến một thao tác client trước đây hợp lệ bị lỗi?
Ai sở hữu các trường bị ảnh hưởng và việc di chuyển client?
Những thao tác đã lưu và kiểm tra phản hồi nào chứng minh khả năng tương thích?
Khi nào có thể loại bỏ một trường hoặc giá trị enum đã ngừng dùng?

Những câu hỏi đó biến một yêu cầu mơ hồ về “đánh giá API” thành bằng chứng mà người đánh giá có thể kiểm tra.

Vì sao GraphQL cần một quy trình phát hành rõ ràng

Các client GraphQL tự tạo tập chọn của riêng chúng. Hai client có thể gọi cùng một query root nhưng dựa vào các trường, fragment, biến và alias hoàn toàn khác nhau. Dữ liệu đo từ server, truy vấn đã lưu và kiến thức của nhóm tiêu dùng đều hữu ích, nhưng không thứ nào tự nó chứng minh một chỉnh sửa là an toàn.

Một thay đổi cũng có thể vượt qua unit test của server nhưng lại làm client lỗi ở thời điểm xác thực. Việc xóa một trường khiến mọi thao tác chọn trường đó trở nên không hợp lệ. Việc thêm một trường đầu vào bắt buộc có thể làm vô hiệu các thao tác bỏ qua trường đó. Việc thay đổi một enum có thể khiến client được sinh tự động hoặc nhánh switch đầy đủ không thể xử lý phản hồi từ server. Việc thay thế kiểu trường nullable bằng một dạng khác có thể phá vỡ việc phân tích cú pháp hoặc giả định của UI.

Sự căng thẳng tương tự cũng xuất hiện trong công việc quản lý API. Một nền tảng quản lý API GraphQL nên giúp các nhóm giữ các quyết định hợp đồng, tài liệu và xác thực gần với API. Quản trị khiến những khả năng đó hữu ích trong lúc phát hành thay vì sau khi sự cố xảy ra.

Phân loại các chỉnh sửa schema trước khi tranh luận về chúng

Bắt đầu mọi thay đổi bằng một phân loại. Các nhãn không cần phức tạp. Chúng cần tạo ra đúng lộ trình đánh giá.

GraphQL schema change types by client risk

Loại thay đổi	Ví dụ	Rủi ro cho client	Hành động phát hành mặc định
Bổ sung	Thêm `Order.trackingUrl`	Thấp, trừ khi client từ chối các trường phản hồi không xác định	Ghi tài liệu và kiểm thử
Ngừng dùng	Đánh dấu `User.fullName` là ngừng dùng và thêm `User.displayName`	Trung bình	Công bố trường thay thế và ngày di chuyển
Gây gián đoạn	Xóa `User.fullName`	Cao	Chặn cho đến khi có bằng chứng di chuyển của người tiêu dùng
Hành vi	Giữ một trường nhưng thay đổi hành vi phân quyền hoặc phân trang	Cao	Coi đó là thay đổi hợp đồng và kiểm thử các đường dẫn bị ảnh hưởng
Mơ hồ	Thay đổi kiểu của một trường hoặc ngữ nghĩa đầu vào	Cao	Yêu cầu đánh giá thiết kế và kiểm thử tương thích

Bảng này là điểm khởi đầu. Một thay đổi được cho là bổ sung vẫn có thể quan trọng. Ví dụ, một số client được sinh tự động hoặc trình xác thực phản hồi nghiêm ngặt coi các trường không xác định là vấn đề. Cài đặt xác thực phản hồi của Apidog cho phép các thuộc tính bổ sung của đối tượng theo mặc định. Nếu chính sách của bạn cần kiểm tra các thuộc tính bất ngờ, hãy đặt additionalProperties thành Deny cho schema phản hồi liên quan hoặc thay đổi cài đặt dự án một cách có chủ đích.

Những thay đổi mặc định nên chặn phát hành

Một lần đánh giá nên yêu cầu phê duyệt rõ ràng khi bao gồm bất kỳ điều nào sau đây:

Xóa một trường, đối số, trường đầu vào, mutation, query, triển khai interface, thành viên union hoặc giá trị enum.
Đổi tên một trường thay vì thêm trường thay thế và ngừng dùng tên cũ.
Biến một đầu vào trước đây là tùy chọn thành bắt buộc.
Thay đổi kiểu của một trường, kỳ vọng nullable, định dạng, hành vi phân quyền, hành vi phân trang hoặc hợp đồng lỗi.
Tái sử dụng tên trường hiện có cho một ý nghĩa nghiệp vụ khác.
Thay đổi giá trị mặc định mà client cố ý bỏ qua.

Quy tắc rất đơn giản: nếu một truy vấn client hoặc giả định phía client hoạt động hôm qua và có thể lỗi vào ngày mai, hãy phân loại nó là gây gián đoạn cho đến khi có bằng chứng ngược lại.

Dùng việc ngừng dùng như một hợp đồng di chuyển

Việc ngừng dùng có hiệu quả khi nó chứa một lộ trình thực sự để tiến lên. “Ngừng dùng” mà không có trường thay thế, người sở hữu, thời hạn hoặc ghi chú di chuyển chỉ trì hoãn một thay đổi gây gián đoạn.

Hãy xem xét việc dọn dẹp tên khách hàng. Đừng đổi tên trường tại chỗ:

# Avoid removing fullName in the same release.
type Customer {
 fullName: String!
}

Thêm trường thay thế, giải thích lý do, rồi hỗ trợ cả hai trường trong suốt khoảng thời gian đã công bố:

type Customer {
 displayName: String!
 fullName: String! @deprecated(reason: "Use displayName. Removal planned after client migration.")
}

Trường thay thế cần nhiều hơn một chú thích schema. Hãy thêm nó vào tài liệu, cập nhật client của bên thứ nhất, xác định những người tiêu dùng có giá trị cao và theo dõi việc áp dụng. Chỉ xóa trường cũ sau khi đáp ứng tiêu chí kết thúc di chuyển.

Xây dựng quy trình quản trị schema GraphQL

Một quy trình có thể lặp lại có các điểm kiểm soát. Nó không phụ thuộc vào việc một người phải nhớ mọi chi tiết client trong một bản phát hành gấp gáp.

1. Thiết lập một nguồn chân lý và những người sở hữu được nêu tên

Hãy giữ một nguồn schema đã được phê duyệt và chỉ định người sở hữu cho từng khu vực có ranh giới rõ ràng, chẳng hạn như danh mục, thanh toán, danh tính hoặc thực hiện đơn hàng. Người sở hữu không cần viết mọi resolver. Họ cần trả lời các câu hỏi về hợp đồng và phê duyệt các thay đổi trong khu vực đó.

Ghi lại những chi tiết này cùng với thay đổi schema:

Khu vực schema và nhóm sở hữu.
Phân loại thay đổi.
Những người tiêu dùng được biết là sử dụng trường hoặc thao tác bị ảnh hưởng.
Trường thay thế hoặc hướng dẫn di chuyển.
Ngày loại bỏ sớm nhất.
Các kiểm thử chứng minh bản phát hành ứng viên hoạt động.

Hồ sơ này ngăn một trường trở thành bề mặt công khai bị bỏ hoang.

2. So sánh schema ứng viên và gán rủi ro

Tạo hoặc đánh giá một bản diff schema giữa bản phát hành hiện tại và bản ứng viên. Đừng dừng ở diff từng dòng. Hãy chuyển kết quả thành tác động đến client.

Với mỗi kiểu đã thay đổi, hãy hỏi liệu một truy vấn hiện có có thể trở nên không hợp lệ không, liệu một phản hồi JSON hiện có có thể thay đổi hình dạng không, và liệu hành vi có thay đổi mà không có thay đổi hệ thống kiểu không. Quy tắc xác thực là một ví dụ phổ biến. Schema có thể giữ nguyên trong khi một trường trước đây hiển thị bắt đầu trả về lỗi phân quyền hoặc null.

Dùng một hồ sơ thay đổi ngắn như sau:

change: remove Customer.fullName
type: breaking
owner: customer-platform
replacement: Customer.displayName
deprecated_since: 2026-08-21
planned_removal: 2026-11-21
known_consumers:
 - ios-storefront
 - partner-portal
release_checks:
 - saved-operation-suite
 - client-migration-confirmations
 - published-release-notes

Các ngày chỉ là ví dụ. Chính sách của bạn nên đặt khoảng thời gian ngừng dùng phù hợp với nhịp phát hành, tốc độ cập nhật của client và các cam kết hợp đồng.

3. Kiểm thử các thao tác thực tế, không chỉ cú pháp schema

Một schema có thể phân tích cú pháp thành công mà vẫn làm hỏng client. Hãy duy trì một bộ thao tác đại diện cho mỗi người tiêu dùng chính hoặc hành trình người dùng. Bao gồm fragment, biến, phân trang, ranh giới quyền, lỗi và các trường tùy chọn.

Đối với một storefront, bộ kiểm thử có thể bao gồm:

query ProductPage($sku: ID!, $first: Int!) {
 product(sku: $sku) {
 id
 displayName
 price {
 amount
 currency
 }
 relatedProducts(first: $first) {
 nodes {
 id
 displayName
 }
 }
 }
}

Chạy thao tác với môi trường ứng viên. Kiểm chứng trạng thái HTTP, lỗi GraphQL, giá trị phản hồi bắt buộc, kỳ vọng về kiểu và các quy tắc nghiệp vụ quan trọng với client. Một phản hồi có HTTP 200 và mảng errors không phải là một thao tác GraphQL thành công trong nhiều trường hợp sử dụng.

Sử dụng các fixture request bao phủ những trường hợp biên thực tế: danh sách rỗng, trường tùy chọn null, tài nguyên đã xóa, bị từ chối quyền, khác biệt locale và con trỏ cũ. Các thao tác đã lưu trở thành bằng chứng đằng sau quyết định phát hành.

4. Đưa tài liệu thành một phần của cổng kiểm soát

Tài liệu cần cùng ngày đánh giá như schema. Một trường tồn tại nhưng thiếu mô tả, ví dụ, ghi chú quyền hoặc hướng dẫn di chuyển buộc các nhóm client phải suy ngược ý định.

Với mỗi trường hoặc đầu vào bị ảnh hưởng, hãy kiểm tra:

Phần mô tả có giải thích ý nghĩa nghiệp vụ thay vì hành vi resolver không?
Kỳ vọng về nullable và giá trị mặc định có rõ ràng không?
Một trường đã ngừng dùng có nêu rõ trường thay thế của nó không?
Các ví dụ liên quan có sử dụng trường mới không?
Changelog có giải thích hành động, đối tượng và ngày loại bỏ không?

Đây cũng là nơi các nhóm ngăn chặn vấn đề phổ biến về một schema GraphQL chỉ hoạt động khi có introspection. Tài liệu tham chiếu đã công bố và ghi chú phát hành phải tự đứng vững cho các client bên ngoài và môi trường bị hạn chế.

5. Phát hành, quan sát và loại bỏ dựa trên bằng chứng

Công bố phân loại thay đổi và ghi chú di chuyển trước thời hạn loại bỏ. Theo dõi việc di chuyển client bằng dữ liệu đo nhận biết schema khi có thể, xác nhận từ đối tác đối với người tiêu dùng bên ngoài và bằng chứng hoàn thành từ các nhóm bên thứ nhất.

Khi ngày kết thúc đến, hãy chạy lại bộ thao tác đã lưu. Nếu các thao tác quan trọng vẫn dùng trường đã ngừng dùng, hãy hoãn việc loại bỏ. Một trường cũ tốn ít chi phí hơn một sự cố client có thể tránh được.

Dùng Apidog để làm cho việc đánh giá có thể lặp lại

Apidog mang đến cho các nhóm API một không gian làm việc cho thiết kế, gỡ lỗi, kiểm thử, tài liệu và mock. Đối với một quy trình quản trị GraphQL, mục tiêu hữu ích là một dấu vết đánh giá được chia sẻ, không phải một công cụ riêng cho từng bước phát hành.

Trong Apidog, hãy tạo một request GraphQL qua Body > GraphQL, sau đó dùng Fetch Schema để tải schema. Trình soạn thảo GraphQL sử dụng schema đã tải để gợi ý trường và kiểu, đồng thời kiểm tra truy vấn dựa trên đó. Đọc tài liệu request GraphQL chính thức trước khi cấu hình quy trình cho nhóm.

Một thiết lập phát hành thực tế trông như sau:

Lưu các query và mutation đại diện cho mỗi luồng quan trọng.
Đặt các biến đặc thù theo môi trường bên ngoài query để hình dạng thao tác giữ ổn định.
Thêm assertion cho trạng thái, header, hình dạng phản hồi JSON, trường bắt buộc, enum và hành vi lỗi.
Nhóm các kiểm tra thành một bộ kiểm thử phát hành cho môi trường ứng viên.
Xem xét các kiểm tra thất bại cùng diff schema và hồ sơ thay đổi trước khi phê duyệt.
Công bố tài liệu và ghi chú di chuyển từ cùng một hợp đồng API đã được phê duyệt.

Xác thực phản hồi kiểm tra trạng thái, định dạng và sự tuân thủ schema. Các kiểm tra được ghi tài liệu bao gồm trường bắt buộc, kiểu, nullable, giá trị enum, phạm vi và mẫu cho phản hồi JSON và XML. Điều đó khiến nó hữu ích cho phần thân phản hồi GraphQL vì phản hồi GraphQL dùng JSON. Nó không thay thế công cụ diff schema GraphQL hoặc bản kiểm kê người tiêu dùng. Hãy dùng nó cùng cả hai.

Nếu nhóm của bạn đang bắt đầu từ các kiểm thử ở cấp request, các công cụ kiểm thử và mock GraphQL có thể giúp định hình lớp kiểm thử. Quản trị bổ sung hồ sơ phát hành, quyền sở hữu và chính sách ngừng dùng xung quanh các kiểm thử đó.

Tải Apidog khi bạn muốn quy trình thiết kế, request, xác thực phản hồi, tài liệu và mock trong một không gian làm việc. Giữ chính sách quản trị trong repository của bạn và dùng không gian làm việc để cung cấp bằng chứng kiểm thử cụ thể cho mỗi lần đánh giá phát hành.

Kỹ thuật nâng cao cho các API GraphQL lớn hơn

Xác định các tầng người tiêu dùng

Không phải client nào cũng mang cùng mức rủi ro phát hành. Phân loại người tiêu dùng theo tác động và tốc độ nâng cấp:

Tầng người tiêu dùng	Ví dụ	Bằng chứng cần có trước khi loại bỏ gây gián đoạn
Tầng 1	Đường dẫn doanh thu, ứng dụng di động, tích hợp chịu quy định	Xác nhận di chuyển và các kiểm thử thao tác end-to-end đạt
Tầng 2	Ứng dụng web nội bộ hoặc tích hợp theo lịch	Các thao tác đã lưu đạt và phê duyệt của người sở hữu
Tầng 3	Client thử nghiệm hoặc người tiêu dùng sandbox	Thông báo ngừng dùng đã công bố và khoảng thời gian di chuyển hợp lý

Các tầng này ngăn một thử nghiệm nội bộ nhỏ áp đặt cùng gánh nặng phát hành như một luồng thanh toán. Chúng cũng ngăn một tích hợp bên ngoài quan trọng bị đối xử như một truy vấn không được theo dõi.

Theo dõi các thay đổi hành vi bên ngoài schema

Diff schema không thể phát hiện mọi thay đổi hợp đồng. Hãy thêm câu hỏi đánh giá cho:

Phân quyền và quyền truy cập ở cấp trường.
Thứ tự phân trang, vòng đời con trỏ và giới hạn kích thước trang.
Hành vi cache và thời điểm vô hiệu hóa.
Phần mở rộng lỗi và thông báo lỗi hiển thị cho người dùng.
Hành vi giới hạn tần suất và hướng dẫn thử lại.
Hiệu năng resolver biến một thao tác hợp lệ thành một thao tác không đáng tin cậy.

Viết một kiểm thử có mục tiêu cho mỗi thay đổi hành vi đã lên kế hoạch. Điều này ngăn nhãn hời hợt “không có thay đổi schema gây gián đoạn” trở thành một lần phát hành đạt.

Coi ranh giới federation là ranh giới hợp đồng

Nếu nhiều nhóm đóng góp subgraph, mọi thực thể, khóa và trường xuyên subgraph được chia sẻ đều cần quyền sở hữu rõ ràng. Một trường có thể trông như cục bộ với một nhóm trong khi một subgraph khác mở rộng hoặc tiêu thụ nó.

Yêu cầu danh sách subgraph bị ảnh hưởng trong hồ sơ thay đổi. Kiểm thử hành vi schema đã tổng hợp và một thao tác end-to-end vượt qua ranh giới. Một kiểm tra schema cục bộ sạch sẽ không chứng minh đồ thị đã tổng hợp hoạt động.

Thiết lập một lộ trình ngoại lệ

Việc loại bỏ khẩn cấp xảy ra khi một trường làm lộ dữ liệu, tạo ra vấn đề bảo mật hoặc gây tổn hại vận hành nghiêm trọng. Quản trị cần một lộ trình ngoại lệ để các nhóm không bỏ qua tài liệu và kiểm thử khi chịu áp lực.

Hồ sơ ngoại lệ nên nêu rõ rủi ro, người sở hữu phê duyệt, người tiêu dùng bị ảnh hưởng, biện pháp giảm thiểu và kế hoạch theo dõi tiếp. Thông báo trực tiếp cho người tiêu dùng khi không thể áp dụng khoảng thời gian ngừng dùng thông thường. Sau đó thêm một kiểm thử hồi quy để lỗi tương tự không quay lại.

Các lựa chọn thay thế và giới hạn

Sổ đăng ký schema, gateway federation, client được sinh tự động hoặc kiểm tra diff schema trong CI đều có thể hữu ích. Không thứ nào thay thế toàn bộ quy trình.

Cách tiếp cận	Điểm mạnh	Điều nó không chứng minh
Diff schema	Tìm thấy các chỉnh sửa cấu trúc	Liệu các thao tác client đang chạy và hành vi còn hoạt động không
Biên dịch client được sinh tự động	Bắt được một số lỗi kiểu của bên thứ nhất	Việc di chuyển của người tiêu dùng bên ngoài hoặc hành vi runtime
Bộ kiểm thử request	Kiểm tra các thao tác đại diện	Mọi người tiêu dùng không được theo dõi và quyết định sở hữu
Chỉ changelog	Truyền đạt công việc đã lên kế hoạch	Rằng một chỉnh sửa gây gián đoạn là an toàn để phát hành
Quy trình quản trị	Kết nối đánh giá, kiểm thử, quyền sở hữu và ngừng dùng	Nó vẫn cần công cụ và nhóm cung cấp bằng chứng

Chọn bộ công cụ nhỏ nhất tạo ra bằng chứng đáng tin cậy cho API của bạn. Nếu nhóm của bạn đang quyết định liệu GraphQL có phù hợp với một dịch vụ mới không, hãy so sánh mô hình truy vấn do client điều khiển của nó với REST và gRPC trong REST vs GraphQL vs gRPC. Việc chọn giao thức và quản trị phát hành là hai quyết định riêng biệt. Mọi hợp đồng công khai vẫn cần cả hai.

Các trường hợp sử dụng thực tế

Một ứng dụng di động cần đổi tên trường hồ sơ

Một nhóm hồ sơ muốn thay thế fullName bằng displayName vì tài khoản tổ chức dùng một mô hình đặt tên khác. Lộ trình quản trị không phải là một commit đổi tên rồi sau đó phát hành.

Thêm displayName, giữ fullName với lý do ngừng dùng, cập nhật truy vấn di động, kiểm thử cả hai trường trong giai đoạn chuyển đổi và thu thập dữ liệu áp dụng theo phiên bản ứng dụng. Chỉ xóa fullName sau khi các phiên bản ứng dụng được hỗ trợ không còn phụ thuộc vào nó hoặc khoảng thời gian hỗ trợ đã công bố kết thúc.

Một mutation thanh toán có yêu cầu đầu vào mới

Một nhóm thanh toán muốn CheckoutInput.taxRegion trở thành bắt buộc. Các phiên bản ứng dụng hiện có bỏ qua giá trị này. Việc biến đầu vào thành bắt buộc ngay lập tức có thể khiến các thao tác thanh toán vốn hợp lệ bị lỗi xác thực.

Giữ đầu vào là tùy chọn trong quá trình di chuyển, xác định hành vi dự phòng của server, công bố yêu cầu mới, cập nhật client và thêm các ca kiểm thử cho hình dạng request cũ và mới. Sau khi client chuyển đổi, hãy đặt quy tắc bắt buộc trong một bản phát hành gây gián đoạn đã lên kế hoạch.

Một đối tác thấy thay đổi trường không được ghi tài liệu

Một đối tác phân tích một trường phản hồi dưới dạng chuỗi, nhưng backend muốn trả về một đối tượng có cấu trúc. Ngay cả khi một client nội bộ đã chuyển đổi, đối tác vẫn có thể lỗi khi chạy.

Nhóm sở hữu ghi đối tác là người tiêu dùng Tầng 1, thêm trường thay thế thay vì thay đổi trường cũ tại chỗ, cung cấp cho đối tác một môi trường kiểm thử và xác minh một thao tác đã lưu của đối tác trước khi loại bỏ. Tài liệu và liên lạc trực tiếp là một phần của bằng chứng phát hành.

Bắt đầu với một danh sách kiểm tra phát hành

Hãy bắt đầu nhỏ. Chọn khu vực GraphQL có công việc client sôi động nhất và yêu cầu hồ sơ thay đổi cho mọi chỉnh sửa schema trong tháng này. Phân loại thay đổi, lưu các thao tác đại diện, ghi tài liệu ngừng dùng và yêu cầu một người phê duyệt được nêu tên cho việc loại bỏ.

Sau đó biến danh sách kiểm tra thành thói quen phát hành. Apidog có thể giữ request, xác thực phản hồi, tài liệu, kịch bản mock và bằng chứng kiểm thử cùng nhau trong khi repository của bạn vẫn là nguồn cho chính sách quản trị. Kết quả là ít rollback khẩn cấp hơn và kỳ vọng rõ ràng hơn cho mọi người tiêu dùng API.

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

Thế nào được coi là thay đổi schema GraphQL gây gián đoạn?

Một thay đổi là gây gián đoạn khi một thao tác client hợp lệ trước bản phát hành có thể lỗi sau đó. Xóa một trường hoặc đối số là ví dụ rõ ràng. Biến một đầu vào trước đây là tùy chọn thành bắt buộc, thay đổi kiểu mà không đánh giá tương thích, xóa một giá trị enum hoặc thay đổi hành vi của trường cũng có thể làm hỏng client.

Thêm một trường GraphQL có luôn an toàn không?

Thông thường, việc thêm một trường tùy chọn không làm vô hiệu các thao tác hiện có. Nó vẫn có thể ảnh hưởng đến các client từ chối nghiêm ngặt các thuộc tính phản hồi bất ngờ, mã được sinh tự động, quy trình tài liệu hoặc công cụ schema. Hãy phân loại việc bổ sung, ghi tài liệu và kiểm thử những người tiêu dùng sử dụng xác thực nghiêm ngặt.

Một trường GraphQL nên được ngừng dùng trong bao lâu?

Đặt khoảng thời gian dựa trên chu kỳ phát hành của client, cam kết hỗ trợ và rủi ro của người tiêu dùng. Một ứng dụng di động có tốc độ áp dụng chậm cần nhiều thời gian hơn một dịch vụ nội bộ được triển khai hàng ngày. Công bố thời hạn, xác định người tiêu dùng quan trọng và chỉ xóa trường sau khi bằng chứng di chuyển đã đầy đủ.

Introspection GraphQL có thể thay thế tài liệu không?

Không. Introspection giúp các công cụ khám phá schema, nhưng nó không thay thế mô tả rõ ràng, ví dụ, ghi chú phân quyền, changelog và hướng dẫn di chuyển. Môi trường bên ngoài hoặc bị khóa cũng có thể hạn chế introspection, vì vậy tài liệu tham chiếu đã công bố cần tự giải thích hợp đồng.

Làm thế nào để kiểm thử các thay đổi GraphQL gây gián đoạn trước production?

Chạy diff schema, sau đó thực thi các query và mutation đại diện đã lưu với môi trường ứng viên. Kiểm chứng lỗi GraphQL, dữ liệu bắt buộc, kiểu, giá trị enum, hành vi null, quyền và kết quả nghiệp vụ. Bao gồm các thao tác client có tác động cao thay vì chỉ các smoke test chung chung.

Xác thực phản hồi có bắt được mọi hồi quy GraphQL không?

Không. Nó bắt được hợp đồng phản hồi đã ghi tài liệu mà bạn chọn để xác thực. Nó không tự nhận diện mọi người tiêu dùng, so sánh toàn bộ schema GraphQL hoặc phát hiện các thay đổi hành vi không được ghi tài liệu. Hãy kết hợp xác thực phản hồi với kiểm thử thao tác, đánh giá schema, quyền sở hữu và quy trình ngừng dùng.