Kiểm thử Canary cho API: Phát hiện lỗi triển khai trước khi người dùng gặp phải

Kiểm thử Canary giúp phát hiện các bản phát hành API lỗi trên 5% lưu lượng truy cập, thay vì 100%. Tìm hiểu quy trình làm việc và kiểm soát các đợt triển khai bằng Apidog CLI ngay trong đường ống CI/CD của bạn.

Ashley Innocent

Ashley Innocent

15 tháng 6 2026

Kiểm thử Canary cho API: Phát hiện lỗi triển khai trước khi người dùng gặp phải

Apidog cho doanh nghiệp

Triển khai tại chỗ

SSO & RBAC

Tuân thủ SOC 2

Khám phá Apidog Enterprise

Bạn đã hợp nhất PR. CI vẫn xanh. Quá trình triển khai hoàn tất mà không có bất kỳ lỗi nào trong nhật ký. Hai mươi phút sau, các yêu cầu hỗ trợ bắt đầu đến: một điểm cuối thanh toán trả về lỗi 500 cho một nhóm khách hàng, và bạn không biết tại sao vì không có gì thất bại trong pipeline.

Đây chính là khoảng trống mà thử nghiệm Canary lấp đầy. Các bài kiểm tra đơn vị (unit tests) và kiểm tra tích hợp (integration tests) kiểm tra mã của bạn dựa trên những gì bạn mong đợi. Chúng không thể kiểm tra mã của bạn dựa trên thế giới thực: lưu lượng truy cập sản xuất, cơ sở dữ liệu thực tế, API của bên thứ ba đã âm thầm thay đổi giới hạn tỷ lệ vào thứ Ba tuần trước. Thử nghiệm Canary đẩy một bản phát hành mới tới một phần nhỏ lưu lượng truy cập thực tế trước, theo dõi cách nó hoạt động, và chỉ mở rộng triển khai khi các tín hiệu trông ổn định. Nếu có gì đó hỏng, nó sẽ hỏng đối với 2% người dùng trong hai phút thay vì 100% người dùng trong một giờ.

Cụ thể đối với API, bạn có thể làm tốt hơn việc chỉ theo dõi bảng điều khiển và hy vọng. Bạn có thể chạy một bộ kiểm tra thực sự đối với phiên bản canary ngay khi nó hoạt động, xác nhận mã trạng thái, lược đồ phản hồi và độ trễ, sau đó chặn quá trình triển khai dựa trên kết quả. Đó là quy trình làm việc mà hướng dẫn này sẽ trình bày, và chúng tôi sẽ kết nối nó từ đầu đến cuối với Apidog và trình chạy dòng lệnh của nó để toàn bộ quá trình nằm trong pipeline CI/CD hiện có của bạn.

button

Thử nghiệm Canary thực chất là gì

Tên gọi này bắt nguồn từ chim hoàng yến trong mỏ than. Thợ mỏ mang một con chim nhốt trong lồng xuống lòng đất vì nó phản ứng với khí độc rất lâu trước khi con người nhận ra. Nếu chim ngừng hót, bạn phải rời khỏi đó. Một bản phát hành canary hoạt động theo cách tương tự: một mẫu nhỏ, có thể chấp nhận rủi ro trước để phần còn lại của người dùng của bạn không bao giờ phải chịu rủi ro.

Trong thực tế, triển khai canary có nghĩa là chạy hai phiên bản dịch vụ của bạn cùng một lúc:

Một bộ cân bằng tải (load balancer), mạng lưới dịch vụ (service mesh) hoặc bộ điều khiển cổng vào (ingress controller) sẽ chia lưu lượng truy cập giữa chúng. Bạn theo dõi tỷ lệ lỗi, độ trễ và các chỉ số kinh doanh của phiên bản canary so với mức cơ bản ổn định. Nếu phiên bản canary hoạt động tốt, bạn sẽ dần chuyển thêm lưu lượng truy cập sang nó từng bước cho đến khi nó phục vụ 100% và trở thành phiên bản ổn định mới. Nếu nó suy giảm, bạn sẽ chuyển mọi thứ trở lại phiên bản ổn định và bản phát hành lỗi sẽ không bao giờ đến được với hầu hết người dùng của bạn.

Thử nghiệm Canary là phần chủ động của vòng lặp đó. Thay vì chờ đợi lưu lượng truy cập tự nhiên bộc lộ lỗi, bạn chủ động bắn một bộ yêu cầu API vào phiên bản canary và kiểm tra các phản hồi. Giám sát thụ động chỉ cho bạn biết điều gì đó đã sai sau khi người dùng gặp phải. Thử nghiệm canary chủ động cho bạn biết điều gì đó đã sai trước khi bạn mở rộng phạm vi ảnh hưởng.

Thử nghiệm Canary so với các loại kiểm thử bạn đã thực hiện

Thử nghiệm Canary không thay thế các bài kiểm thử khác của bạn. Nó nằm ở cuối chuỗi và phát hiện một loại lỗi khác.

Loại kiểm thử Chạy đối với Bắt được Bỏ lỡ
Unit tests (Kiểm thử đơn vị) Các hàm biệt lập Lỗi logic Bất cứ điều gì liên quan đến I/O thực tế
Integration tests (Kiểm thử tích hợp) Các thành phần được kết nối Hợp đồng bị lỗi giữa các dịch vụ Cấu hình sản xuất, hình dạng dữ liệu thực tế
Smoke tests (Kiểm thử khói) Một bản dựng đã triển khai Các lỗi cơ bản "có hoạt động không?" Sự suy giảm hành vi tinh vi
Canary testing (Kiểm thử Canary) Một bản phát hành trực tiếp trên cơ sở hạ tầng thực Cấu hình xấu, lệch môi trường, suy giảm hiệu suất, ngừng hoạt động một phần Các lỗi chỉ xuất hiện ở quy mô lớn

Lý do thử nghiệm canary xứng đáng có vị trí của nó: một phần lớn các sự cố sản xuất đến từ những thứ mà không môi trường tiền sản xuất nào có thể tái tạo hoàn toàn. Một biến môi trường bị thiếu. Một cài đặt nhóm kết nối cũ. Một chỉ mục cơ sở dữ liệu tồn tại trong staging nhưng không có trong sản xuất. Một phụ thuộc cấp dưới hoạt động khác dưới quyền xác thực thực tế. Mã của bạn là đúng; môi trường xung quanh nó thì không. Thử nghiệm canary là lần đầu tiên bản phát hành mới của bạn gặp môi trường đó, và bạn muốn gặp nó với hai phần trăm lưu lượng truy cập, chứ không phải toàn bộ.

Nếu bạn muốn biết thêm bối cảnh rộng hơn về vị trí của nó, hướng dẫn của chúng tôi về cách tự động hóa các bài kiểm thử API trong CI/CD bao gồm các giai đoạn thượng nguồn, và kiểm thử khói so với kiểm thử hồi quy giải thích hai loại kiểm thử mà phiên bản canary thường dựa vào nhất.

Những gì cần đo lường trên một Canary

Một phiên bản canary chỉ hữu ích nếu bạn biết "trạng thái ổn định" trông như thế nào. Chọn một tập hợp nhỏ các tín hiệu và so sánh phiên bản canary với đường cơ sở ổn định, không phải với một con số tuyệt đối. Tỷ lệ lỗi 1,2% có thể là bình thường đối với dịch vụ của bạn; điều quan trọng là liệu phiên bản canary có tệ hơn đáng kể so với phiên bản ổn định hiện tại hay không.

Bốn tín hiệu bao gồm hầu hết các trường hợp:

  1. Tỷ lệ lỗi: tỷ lệ phản hồi 5xx, và thường là 4xx không nên xảy ra, như một sự tăng đột biến trong 401 sau một thay đổi xác thực. Đây là chỉ số quan trọng nhất.
  2. Độ trễ: p95 và p99, không phải trung bình. Trung bình che giấu phần đuôi chậm nơi người dùng thực tế cảm thấy khó chịu. Một phiên bản canary chậm hơn 40ms ở p99 là một cảnh báo ngay cả khi giá trị trung bình trông ổn.
  3. Tính đúng đắn của phản hồi: phần thân phản hồi có còn khớp với lược đồ không? Một phản hồi 200 OK trả về sai định dạng còn tệ hơn một 500, vì hệ thống giám sát sẽ không gắn cờ nó.
  4. Tín hiệu kinh doanh: thanh toán thành công, đăng nhập thành công, mặt hàng được thêm vào giỏ hàng. Những tín hiệu này bắt được các lỗi logic mà về mặt kỹ thuật là các phản hồi HTTP "thành công".

Ba điều đầu tiên bạn có thể xác nhận trực tiếp trong một bài kiểm thử API. Đó là phần chúng ta sẽ tự động hóa.

Quy trình thử nghiệm Canary, từng bước một

Dưới đây là hình dạng của một bản triển khai canary được kiểm soát bằng các bài kiểm thử API tự động. Mỗi bước là thứ bạn có thể chạy từ một pipeline.

  1. Triển khai phiên bản mới dưới dạng canary cùng với phiên bản ổn định.
  2. Chuyển một phần nhỏ lưu lượng truy cập (ví dụ 5%) đến canary.
  3. Chạy một bộ kiểm thử API tự động chống lại điểm cuối canary.
  4. Theo dõi tỷ lệ lỗi và độ trễ trong một thời gian ngắn.
  5. Kiểm soát: nếu các kiểm thử vượt qua và các chỉ số nằm trong ngân sách cho phép, hãy chuyển thêm lưu lượng truy cập. Nếu không, hãy quay lại phiên bản trước.
  6. Lặp lại quá trình tăng dần (5% lên 25% lên 50% lên 100%), kiểm thử lại ở mỗi bước.
  7. Nâng cấp canary lên phiên bản ổn định, loại bỏ phiên bản cũ.

Hai phần đáng chú ý là bước 3 (bộ kiểm thử) và bước 5 (kiểm soát). Thực hiện đúng hai phần này và phần còn lại là việc cài đặt cơ bản mà nền tảng của bạn đã cung cấp.

Xây dựng bộ kiểm thử trong Apidog

Bộ kiểm thử là trái tim của thử nghiệm canary, và đây là nơi hầu hết các nhóm bỏ qua các bước quan trọng. Một "kiểm thử" canary chỉ ping `/health` và kiểm tra 200 cho bạn biết rằng quá trình đã bắt đầu. Nó không cho bạn biết liệu các điểm cuối thực tế của bạn có hoạt động hay không.

Một bộ canary thực sự thực hiện các đường dẫn quan trọng: xác thực, đọc, ghi và xác minh hình dạng phản hồi trên mỗi đường dẫn. Kịch bản kiểm thử của Apidog cho phép bạn xâu chuỗi các yêu cầu đó lại với nhau, truyền dữ liệu giữa chúng và xác nhận kết quả mà không cần viết mã kết nối.

Một kịch bản canary vững chắc cho một API thương mại điện tử trông như thế này:

Trong Apidog, bạn xây dựng mỗi yêu cầu một lần, sau đó thêm các xác nhận một cách trực quan. Đối với kiểm tra lược đồ, bạn có thể xác thực phản hồi dựa trên lược đồ OpenAPI mà bạn đã thiết kế, do đó một phần thân phản hồi bị sai lệch sẽ tự động làm kiểm tra thất bại. Đối với việc chuyển giao token xác thực, bạn trích xuất nó từ phản hồi của bước 1 và tham chiếu nó như một biến trong các bước sau. Không cần kịch bản cho các trường hợp phổ biến, và bạn có thể sử dụng các bộ xử lý sau bằng JavaScript khi bạn cần logic tùy chỉnh.

Phần thưởng là kịch bản này chạy theo ba cách từ một định nghĩa: thủ công trong khi bạn đang xây dựng nó, theo lịch trình như giám sát tổng hợp khi nó hoạt động, và từ dòng lệnh trong pipeline canary của bạn. Bạn chỉ viết các xác nhận một lần.

Chạy bộ kiểm thử từ dòng lệnh

Để kiểm soát việc triển khai, bộ kiểm thử phải chạy không giao diện (headless) trong CI. Apidog cung cấp một CLI cho chính mục đích này. Cài đặt nó trên tác nhân xây dựng của bạn:

npm install -g apidog-cli

Xuất dữ liệu kịch bản kiểm thử của bạn từ Apidog dưới dạng tệp định dạng CLI, hoặc trỏ trình chạy đến một kịch bản bằng ID sử dụng mã thông báo truy cập, sau đó chạy nó:

apidog run \
  --access-token "$APIDOG_ACCESS_TOKEN" \
  -t "$CANARY_SCENARIO_ID" \
  -e "$CANARY_ENV_ID" \
  -r cli,html,junit

Một vài cờ (flags) đáng biết cho công việc canary:

CLI sẽ thoát với mã không bằng không khi một xác nhận thất bại. Mã thoát đó chính là toàn bộ cơ chế kiểm soát: pipeline của bạn đã biết cách dừng ở bước thất bại, vì vậy một kiểm thử canary thất bại sẽ dừng quá trình triển khai miễn phí.

Để hiểu sâu hơn về cách chạy Apidog trong các pipeline, cách tự động hóa kiểm thử API trong GitHub Actionshướng dẫn tích hợp Jenkins bao gồm chi tiết các nền tảng đó.

Kết nối nó vào CI/CD

Đây là một công việc GitHub Actions được cắt gọn, triển khai một bản canary, kiểm thử nó và chỉ quảng bá khi thành công. Cấu trúc này có thể áp dụng cho GitLab CI, CircleCI hoặc Jenkins với những thay đổi cú pháp nhỏ.

name: canary-release

on:
  push:
    branches: [main]

jobs:
  canary:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Deploy canary (5% traffic)
        run: ./deploy.sh --canary --weight 5

      - name: Install Apidog CLI
        run: npm install -g apidog-cli

      - name: Test the canary
        run: |
          apidog run \
            --access-token "$APIDOG_ACCESS_TOKEN" \
            -t "$CANARY_SCENARIO_ID" \
            -e "$CANARY_ENV_ID" \
            -r cli,junit
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}
          CANARY_SCENARIO_ID: ${{ vars.CANARY_SCENARIO_ID }}
          CANARY_ENV_ID: ${{ vars.CANARY_ENV_ID }}

      - name: Bake and watch (2 min)
        run: sleep 120 && ./check-metrics.sh --service canary --max-error-rate 1.0

      - name: Promote canary to 100%
        run: ./deploy.sh --promote

      - name: Roll back on any failure
        if: failure()
        run: ./deploy.sh --rollback

Logic biến đây thành bản triển khai canary chứ không phải bản triển khai thông thường là thứ tự. Canary chiếm một phần lưu lượng truy cập trước khi kiểm thử chạy, do đó kiểm thử thực hiện một bản phát hành đã phục vụ các yêu cầu thực. Bước `if: failure()` là lưới an toàn: nếu bộ kiểm thử thoát với mã không bằng không, hoặc kiểm tra chỉ số bị kích hoạt, công việc sẽ thất bại và quá trình khôi phục sẽ chạy trước khi lưu lượng truy cập vượt quá 5%.

Giữ cho `CANARY_ENV_ID` trỏ đến một môi trường Apidog mà URL cơ sở của nó nhắm mục tiêu đến canary. Khi bạn muốn chạy cùng một bộ kiểm thử như một kiểm thử khói sản xuất sau triển khai, bạn thay thế bằng ID môi trường sản xuất và không thay đổi bất cứ điều gì khác. Việc tái sử dụng đó là điểm chính: một bộ kiểm thử, nhiều giai đoạn.

Những lỗi phổ biến khiến thử nghiệm Canary trở nên vô dụng

Kiểm thử sai điểm cuối. Nếu kiểm thử của bạn truy cập URL công khai được cân bằng tải, yêu cầu có thể đến một instance ổn định thay vì canary. Hãy định tuyến kiểm thử rõ ràng đến canary, thông qua một tiêu đề mà mesh định tuyến, một hostname canary chuyên dụng hoặc một môi trường có URL cơ sở là địa chỉ của canary.

Thời gian "nấu" bằng không. Một số lỗi chỉ xuất hiện dưới tải liên tục: rò rỉ bộ nhớ, cạn kiệt nhóm kết nối, bộ đệm đầy. Chạy kiểm thử, sau đó theo dõi trong vài phút trước khi quảng bá. Một canary vượt qua ngay lập tức và được quảng bá trong mười giây thì gần như không phải là canary.

Không có tự động rollback. Nếu con người phải nhận ra lỗi và nhấp vào rollback, bạn đã giữ lại phần chậm nhất của phản ứng sự cố trong vòng lặp. Toàn bộ giá trị là pipeline tự động rollback. Kết nối rollback với điều kiện lỗi và kiểm tra xem rollback có hoạt động không.

Ngưỡng tuyệt đối thay vì so sánh. "Thất bại nếu tỷ lệ lỗi trên 1%" sẽ hỏng vào ngày tỷ lệ lỗi cơ bản của bạn hợp lý là 1,5%. So sánh canary với phiên bản ổn định hiện tại, và kích hoạt cổng khi canary tệ hơn đáng kể, không phải khi nó vượt qua một con số bạn đã chọn từ nhiều tháng trước.

Các xác nhận mỏng. Một phản hồi 200 với phần thân bị định dạng sai sẽ vượt qua kiểm tra chỉ mã trạng thái và gây lỗi cho người dùng của bạn. Hãy xác nhận dựa trên lược đồ phản hồi, không chỉ mã. Đây là lúc việc thiết kế hợp đồng API của bạn trước và xác thực phản hồi dựa trên lược đồ phát huy hiệu quả trực tiếp: kiểm thử canary của bạn thừa hưởng hợp đồng miễn phí.

Phạm vi của Canary nên rộng đến đâu và trong bao lâu?

Không có câu trả lời chung, nhưng một mặc định khả thi cho hầu hết các nhóm:

Các dịch vụ có lưu lượng truy cập cao có thể di chuyển nhanh hơn vì chúng tích lũy tín hiệu nhanh chóng. Một API thanh toán xử lý hàng nghìn yêu cầu mỗi giây có đủ dữ liệu để đánh giá một canary trong một phút. Một API quản trị nội bộ chỉ có vài yêu cầu mỗi giờ cần thời gian "nấu" lâu hơn hoặc tải kiểm thử tổng hợp nặng hơn để đưa ra phán quyết.

Thử nghiệm Canary phù hợp ở đâu trong chiến lược phát hành của bạn

Thử nghiệm Canary kết hợp tự nhiên với các cờ tính năng (feature flags) và triển khai blue-green, và điều quan trọng là phải hiểu rõ sự khác biệt. Blue-green chuyển toàn bộ lưu lượng truy cập từ một môi trường đầy đủ sang môi trường khác cùng một lúc; việc rollback nhanh chóng, nhưng không có sự tiếp xúc dần dần. Cờ tính năng chuyển đổi hành vi cho người dùng được chọn mà không cần triển khai lại. Phát hành Canary dần dần chuyển đổi lưu lượng truy cập thực và kiểm soát dựa trên các tín hiệu trực tiếp.

Hầu hết các nhóm phát triển trưởng thành đều sử dụng cả ba: blue-green để hoán đổi cơ sở hạ tầng, canary để tăng dần lưu lượng truy cập với các cổng tự động, và cờ tính năng để kiểm soát chi tiết hơn khi mã đã hoạt động. Điểm chung là không có công cụ nào loại bỏ nhu cầu kiểm thử bản phát hành đối với môi trường sản xuất. Chúng kiểm soát mức độ người dùng của bạn tiếp xúc trong khi bạn thực hiện.

Đó là điều quan trọng nhất cần ghi nhớ. Thử nghiệm Canary không phải là một công cụ bạn mua; đó là một kỷ luật: triển khai nhỏ, kiểm thử bản phát hành trực tiếp với các xác nhận thực, theo dõi các tín hiệu và kiểm soát quá trình triển khai dựa trên kết quả. Các công cụ hiện có để tự động hóa từng bước này. Với Apidog, bạn xây dựng bộ kiểm thử một lần, chạy nó từ CLI bên trong bất kỳ pipeline nào và để mã thoát quyết định liệu bản phát hành có tiếp tục hay không. Các bản phát hành lỗi sẽ dừng ở 5% lưu lượng truy cập và người dùng của bạn sẽ không bao giờ thấy lỗi 500.

Tải Apidog để xây dựng kịch bản kiểm thử canary đầu tiên của bạn, trỏ một môi trường đến điểm cuối canary của bạn và thêm một bước CLI vào pipeline của bạn. Lần hợp nhất lỗi tiếp theo sẽ chỉ gây ảnh hưởng đến một số ít yêu cầu thay vì tất cả.

button

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

Thử nghiệm Canary có giống với triển khai Canary không? Triển khai Canary là cơ chế phát hành: phục vụ một phiên bản mới cho một phần nhỏ lưu lượng truy cập. Thử nghiệm Canary là những gì bạn làm trong khoảng thời gian đó, chủ động chạy các kiểm thử và xác nhận phản hồi thay vì chỉ theo dõi các bảng điều khiển. Bạn cần triển khai để thực hiện kiểm thử, nhưng chính kiểm thử là thứ biến một quá trình triển khai rủi ro thành một quá trình được kiểm soát.

Tôi có cần một service mesh để thực hiện thử nghiệm Canary không? Không. Một service mesh như Istio hoặc Linkerd giúp việc chia tách lưu lượng truy cập dễ dàng hơn, nhưng bạn có thể chạy canaries bằng cách sử dụng trọng số cân bằng tải đơn giản, các chú thích canary của bộ điều khiển cổng vào (ingress controller), hoặc thậm chí là trọng số DNS. Phần kiểm thử và kiểm soát của quy trình làm việc, mà hướng dẫn này tập trung vào, hoạt động tương tự bất kể cách bạn chia tách lưu lượng truy cập.

Điều này khác với việc kiểm thử khói (smoke testing) sau triển khai như thế nào? Kiểm thử khói thường chạy một lần đối với một bản phát hành đã được triển khai hoàn chỉnh để xác nhận nó đã hoạt động. Thử nghiệm Canary chạy đối với một bản phát hành chỉ phục vụ một phần nhỏ lưu lượng truy cập thực, và nó kiểm soát quá trình tăng tốc. Các xác nhận có thể giống hệt nhau; sự khác biệt là thời gian và hậu quả. Một kiểm thử khói thất bại có nghĩa là phải khôi phục thứ gì đó đã hoạt động cho tất cả mọi người; một kiểm thử canary thất bại có nghĩa là dừng một quá trình triển khai ở 5%. Để biết sự khác biệt giữa các bộ kiểm thử khói và hồi quy, hãy xem hướng dẫn so sánh của chúng tôi.

Tôi có thể sử dụng lại các bài kiểm thử API hiện có của mình làm kiểm thử Canary không? Thường là có. Nếu bạn đã có các kịch bản kiểm thử Apidog với các xác nhận thực, bạn chỉ cần trỏ chúng đến một môi trường mà URL cơ sở là Canary và chạy chúng bằng CLI. Công việc là đảm bảo các bài kiểm thử của bạn xác nhận nội dung phản hồi chứ không chỉ mã trạng thái, và định tuyến chúng đến Canary thay vì URL công khai được cân bằng tải.

Điều gì xảy ra khi một kiểm thử Canary thất bại trong CI? CLI của Apidog thoát với mã không bằng không khi bất kỳ xác nhận nào thất bại. Pipeline của bạn sẽ xử lý điều đó giống như bất kỳ bước thất bại nào: công việc dừng lại, bước quảng bá bị bỏ qua và bước khôi phục if: failure() của bạn sẽ chạy. Không cần có người phải theo dõi để quá trình khôi phục xảy ra.

Thực hành thiết kế API trong Apidog

Khám phá cách dễ dàng hơn để xây dựng và sử dụng API