Phản mẫu: Sử dụng Chính sách RaiseFault trong điều kiện không phù hợp

Bạn đang xem tài liệu về Apigee Edge.
Chuyển đến tài liệu về Apigee X. thông tin

Chính sách RaiseFault cho phép nhà phát triển API bắt đầu một quy trình lỗi, đặt các biến lỗi trong thông báo nội dung phản hồi và đặt mã trạng thái phản hồi phù hợp. Bạn cũng có thể dùng chính sách RaiseFault để đặt các biến luồng liên quan đến lỗi, chẳng hạn như fault.name, fault.type và fault.category. Vì các biến này hiển thị trong dữ liệu phân tích và nhật ký truy cập của Bộ định tuyến dùng để gỡ lỗi, nên điều quan trọng là cần phải xác định chính xác lỗi.

Bạn có thể dùng chính sách RaiseFault để xem các điều kiện cụ thể là lỗi, ngay cả khi lỗi thực tế không xảy ra trong một chính sách khác hoặc trong máy chủ phụ trợ của proxy API. Ví dụ: nếu muốn proxy gửi thông báo lỗi tuỳ chỉnh đến ứng dụng khách bất cứ khi nào nội dung phản hồi phụ trợ chứa chuỗi unavailable, bạn có thể gọi chính sách RaiseFault như minh hoạ trong đoạn mã dưới đây: 

<!-- /antipatterns/examples/raise-fault-conditions-1.xml  -->
<TargetEndpoint name="default">
...
  <Response>
    <Step>
      <Name>RF-Service-Unavailable</Name>
      <Condition>(message.content Like "*unavailable*")</Condition>
   </Step>
  </Response>
...

Tên của chính sách RaiseFault hiển thị dưới dạng fault.name trong tính năng Giám sát API và có dạng x_apigee_fault_policy trong nhật ký truy cập của Bộ định tuyến và Analytics. Điều này giúp chẩn đoán nguyên nhân lỗi dễ dàng.

Phản mẫu

Sử dụng chính sách RaiseFault trong FaultRules sau khi một chính sách khác đã tạo ra lỗi

Hãy xem xét ví dụ bên dưới, trong đó chính sách OAuthV2 trong quy trình Proxy API không hoạt động kèm theo lỗi InvalidAccessToken. Khi không thành công, Edge sẽ đặt fault.name thành InvalidAccessToken, nhập vào luồng lỗi và thực thi mọi FaultRules đã xác định. Trong FaultRule có một chính sách RaiseFault tên là RaiseFault. Chính sách này sẽ gửi phản hồi lỗi tuỳ chỉnh bất cứ khi nào xảy ra lỗi InvalidAccessToken. Tuy nhiên, việc sử dụng chính sách RaiseFault trong FaultRule có nghĩa là biến fault.name sẽ bị ghi đè và che giấu nguyên nhân thực sự gây ra lỗi. 

<!-- /antipatterns/examples/raise-fault-conditions-2.xml  -->
<FaultRules>
  <FaultRule name="generic_raisefault">
    <Step>
        <Name>RaiseFault</Name>
        <Condition>(fault.name equals "invalid_access_token") or (fault.name equals "InvalidAccessToken")</Condition>
    </Step>
  </FaultRule>
</FaultRules>

Sử dụng chính sách RaiseFault trong FaultRule trong mọi điều kiện

Trong ví dụ bên dưới, chính sách RaiseFault có tên là RaiseFault sẽ thực thi nếu fault.name không phải là RaiseFault: 

<!-- /antipatterns/examples/raise-fault-conditions-3.xml  -->
<FaultRules>
    <FaultRule name="fault_rule">
        ....
        <Step>
            <Name>RaiseFault</Name>
            <Condition>!(fault.name equals "RaiseFault")</Condition>
        </Step>
    </FaultRule>
</FaultRules>

Như trong trường hợp đầu tiên, các biến lỗi chính fault.name, fault.code và fault.policy sẽ bị ghi đè bằng tên của chính sách RaiseFault. Hành vi này khiến bạn hầu như không thể xác định được chính sách nào thực sự gây ra lỗi nếu không truy cập vào tệp theo dõi cho thấy lỗi hoặc tái tạo vấn đề.

Sử dụng chính sách RaiseFault để trả về phản hồi HTTP 2xx bên ngoài luồng lỗi.

Trong ví dụ bên dưới, chính sách RaiseFault có tên là HandleOptionsRequest sẽ thực thi khi động từ yêu cầu là OPTIONS: 

<!-- /antipatterns/examples/raise-fault-conditions-4.xml  -->
<PreFlow name="PreFlow">
    <Request>
        …
        <Step>
            <Name>HandleOptionsRequest</Name>
            <Condition>(request.verb Equals "OPTIONS")</Condition>
        </Step>
        …
</PreFlow>

Mục đích là ngay lập tức trả về phản hồi cho ứng dụng API mà không cần xử lý các chính sách khác. Tuy nhiên, điều này sẽ dẫn đến dữ liệu phân tích sai lệch vì các biến lỗi sẽ chứa tên của chính sách RaiseFault, khiến proxy khó gỡ lỗi hơn. Cách chính xác để triển khai hành vi mong muốn là sử dụng Luồng có các điều kiện đặc biệt, như mô tả trong phần Thêm tính năng hỗ trợ CORS.

Mức độ tác động

Việc sử dụng chính sách RaiseFault như được mô tả ở trên sẽ ghi đè các biến lỗi chính bằng tên của chính sách RaiseFault thay vì tên của chính sách không đạt. Trong nhật ký Analytics và NGINX Access, các biến x_apigee_fault_code và x_apigee_fault_policy sẽ bị ghi đè. Trong mục Giám sát API, Fault Code và Fault Policy sẽ bị ghi đè. Hành vi này gây khó khăn cho việc khắc phục và xác định chính sách nào là nguyên nhân thực sự gây ra lỗi.

Trong ảnh chụp màn hình dưới đây của phần Giám sát API, bạn có thể thấy rằng chính sách Mã lỗi và Lỗi đã được ghi đè thành các giá trị RaiseFault chung, khiến không thể xác định nguyên nhân gốc rễ của lỗi trong nhật ký:

Phương pháp hay nhất

Khi chính sách Edge báo lỗi và bạn muốn tuỳ chỉnh thông báo phản hồi lỗi, hãy sử dụng chính sách composeMessage hoặc JavaScript thay vì chính sách RaiseFault.

Bạn nên sử dụng chính sách RaiseFault trong một quy trình không có lỗi. Tức là chỉ sử dụng RaiseFault để coi một điều kiện cụ thể là lỗi, ngay cả khi lỗi thực tế không xảy ra trong một chính sách hoặc trong máy chủ phụ trợ của Proxy API. Ví dụ: bạn có thể sử dụng chính sách RaiseFault để báo hiệu rằng các tham số đầu vào bắt buộc bị thiếu hoặc có cú pháp không chính xác.

Bạn cũng có thể dùng RaiseFault trong quy tắc lỗi nếu muốn phát hiện lỗi trong quá trình xử lý lỗi. Ví dụ: chính trình xử lý lỗi cũng có thể gây ra lỗi mà bạn muốn báo hiệu bằng cách sử dụng RaiseFault.

Tài liệu đọc thêm