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.
Truy cập vào tài liệu 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 thích hợp. Bạn cũng có thể sử 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 xuất hiện trong dữ liệu phân tích và nhật ký truy cập Router được dùng để gỡ lỗi, nên bạn cần xác định chính xác lỗi.

Bạn có thể sử dụng chính sách RaiseFault để coi các điều kiện cụ thể là lỗi, ngay cả khi lỗi thực tế chưa 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 bạn muốn proxy gửi một 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, thì 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 xuất hiện dưới dạng fault.name trong API Monitoring và dưới dạng x_apigee_fault_policy trong nhật ký truy cập Analytics và Router. Điều này giúp bạn dễ dàng chẩn đoán nguyên nhân gây ra lỗi.

Antipattern

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

Hãy xem xét ví dụ bên dưới, trong đó chính sách OAuthV2 trong quy trình API Proxy không thành công với lỗi InvalidAccessToken. Khi thất bại, Edge sẽ đặt fault.name thành InvalidAccessToken, chuyển sang quy trình lỗi và thực thi mọi FaultRule đã xác định. Trong FaultRule, có một chính sách RaiseFault có tên là RaiseFault. Chính sách này sẽ gửi một 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ự của 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 gần như không thể xác định chính sách nào thực sự gây ra lỗi nếu không truy cập vào một tệp theo dõi cho thấy lỗi hoặc tái hiện 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à trả về phản hồi cho ứng dụng API ngay lập tức 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 gây hiểu lầm vì các biến lỗi sẽ chứa tên của chính sách RaiseFault, khiến việc gỡ lỗi cho proxy trở nên khó khăn hơn. Cách triển khai đúng hành vi mong muốn là sử dụng các Luồng có điều kiện đặc biệt, như mô tả trong phần Thêm tính năng hỗ trợ CORS.

Tác động

Việc sử dụng chính sách RaiseFault như mô tả ở trên sẽ dẫn đến việc 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 thành công. Trong nhật ký truy cập Analytics và NGINX, các biến x_apigee_fault_code và x_apigee_fault_policy sẽ bị ghi đè. Trong API Monitoring (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 sự 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 bên dưới từ API Monitoring, bạn có thể thấy rằng Fault Code và Fault policy đã bị ghi đè thành các giá trị RaiseFault chung, khiến bạn không thể xác định nguyên nhân gốc của lỗi từ nhật ký:

Phương pháp hay nhất

Khi một chính sách Edge gây ra 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 AssignMessage 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 luồng 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ế chưa xảy ra trong chính sách hoặc trong máy chủ phụ trợ của API Proxy. 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ể sử dụng RaiseFault trong một 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ủa bạn 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