Các phương pháp hay nhất để thiết kế và phát triển proxy API

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

Mục đích của tài liệu này là cung cấp một bộ tiêu chuẩn và các phương pháp hay nhất để phát triển bằng Apigee Edge. Các chủ đề được đề cập ở đây bao gồm thiết kế, lập trình, sử dụng chính sách, giám sát và gỡ lỗi. Thông tin này được thu thập từ kinh nghiệm của các nhà phát triển đang làm việc với Apigee nhằm triển khai các chương trình API thành công. Đây là tài liệu đang hoạt động và sẽ được cập nhật tuỳ từng thời điểm.

Ngoài các nguyên tắc tại đây, bạn cũng có thể thấy bài đăng trên thẻ Cộng đồng Apigee Edge Antipatterns hữu ích.

Tiêu chuẩn phát triển

Nhận xét và tài liệu

  • Cung cấp nhận xét cùng dòng trong cấu hình ProxyEndpoint và TargetEndpoint. Bình luận giúp dễ đọc hơn đối với một Flow, đặc biệt là khi tên tệp chính sách không được mô tả đầy đủ để thể hiện chức năng cơ bản của Flow.
  • Viết bình luận hữu ích. Tránh nhận xét rõ ràng.
  • Sử dụng thụt lề, giãn cách, căn dọc, v.v. nhất quán.

Mã hoá theo kiểu khung

Mã hoá kiểu khung bao gồm việc lưu trữ tài nguyên proxy API trong hệ thống quản lý phiên bản của riêng bạn để sử dụng lại trên các môi trường phát triển cục bộ. Ví dụ: để sử dụng lại một chính sách, hãy lưu trữ chính sách đó trong chế độ kiểm soát nguồn để nhà phát triển có thể đồng bộ hoá và sử dụng chính sách đó trong môi trường phát triển proxy riêng.

  • Để bật DRY ("không lặp lại"), nếu có thể, các cấu hình và tập lệnh chính sách phải triển khai các hàm chuyên biệt, có thể sử dụng lại. Ví dụ: một chính sách dành riêng để trích xuất tham số truy vấn từ thông báo yêu cầu có thể được gọi là ExtractVariables.ExtractRequestParameters. Chính sách chuyên dụng để chèn các tiêu đề CORS có thể được gọi là AssignMessage.SetCORSHeaders. Sau đó, các chính sách đó có thể được lưu trữ trong hệ thống kiểm soát nguồn và thêm vào mỗi proxy API cần trích xuất tham số hoặc đặt tiêu đề CORS mà không yêu cầu bạn tạo cấu hình thừa (và do đó ít dễ quản lý hơn).
  • Xoá các chính sách và tài nguyên không dùng đến (JavaScript, Java, GCC, v.v.) khỏi các proxy API, đặc biệt là các tài nguyên lớn có nguy cơ làm chậm các quy trình nhập và triển khai.

Quy ước đặt tên

  • Thuộc tính name của Chính sách và tên tệp chính sách XML phải giống nhau.
  • Thuộc tính name của chính sách Tập lệnh và Chú thích dịch vụ và tên của tệp tài nguyên phải giống nhau.
  • DisplayName phải mô tả chính xác chức năng của chính sách cho người chưa từng làm việc với proxy API đó.
  • Đặt tên cho chính sách theo chức năng. Apigee khuyên bạn nên thiết lập một quy ước đặt tên nhất quán cho các chính sách của mình. Ví dụ: sử dụng tiền tố ngắn, theo sau là một chuỗi các từ mô tả được phân tách bằng dấu gạch ngang. Ví dụ: AM-xxx cho chính sáchassignMessage. Xem thêm công cụ apigeelint.
  • Sử dụng phần mở rộng phù hợp cho các tệp tài nguyên, .js cho JavaScript, .py cho python và .jar cho các tệp JAR Java.
  • Tên biến phải nhất quán. Nếu bạn chọn một kiểu, chẳng hạn như camelCase hoặc Under_score, hãy sử dụng kiểu đó trong suốt proxy API.
  • Sử dụng tiền tố biến (nếu có thể) để sắp xếp các biến dựa trên mục đích của chúng, ví dụ: Consumer.username và Consumer.password.

Phát triển proxy API

Các cân nhắc ban đầu về thiết kế

  • Để xem hướng dẫn về thiết kế API RESTful, hãy tải sách điện tử Thiết kế API web: Đường liên kết bị thiếu xuống.
  • Tận dụng các chính sách và chức năng của Apigee Edge bất cứ khi nào có thể để tạo proxy API. Tránh mã hoá tất cả logic proxy trong các tài nguyên JavaScript, Java hoặc Python.
  • Xây dựng Flow một cách có tổ chức. Nhiều luồng, mỗi luồng có một điều kiện, nên có nhiều tệp đính kèm có điều kiện vào cùng một PreFlow và Postflow.
  • Để sử dụng trạng thái "failsafe", hãy tạo một proxy API mặc định bằng ProxyEndpoint BasePath là /. Bạn có thể dùng lệnh này để chuyển hướng các yêu cầu API cơ sở đến một trang web của nhà phát triển, để trả về phản hồi tuỳ chỉnh hoặc thực hiện một thao tác khác hữu ích hơn so với việc trả về messaging.adaptors.http.flow.ApplicationNotFound mặc định.
  • Sử dụng tài nguyên TargetServer để tách cấu hình TargetEndpoint khỏi các URL cụ thể, hỗ trợ việc quảng bá trên nhiều môi trường.
    Xem nội dung Cân bằng tải trên các máy chủ phụ trợ.
  • Nếu bạn có nhiều quy tắc, hãy tạo một quy tắc làm "mặc định", tức là quy tắc định tuyến (routeRule) không có điều kiện. Đảm bảo rằng Tuyến đường mặc định được xác định cuối cùng trong danh sách Tuyến đường có điều kiện. Tuyến Quy tắc được đánh giá từ trên xuống trong ProxyEndpoint.
    Xem Tài liệu tham khảo về cấu hình proxy API.
  • Kích thước gói proxy API: Gói proxy API không được lớn hơn 15 MB. Trong Apigee Edge dành cho đám mây riêng tư, bạn có thể thay đổi giới hạn về kích thước bằng cách sửa đổi thuộc tính thrift_framed_transport_size_in_mb ở các vị trí sau: cassandra.yaml (trong Cassandra) và conf/apigee/management-server/repository.properties.
  • Tạo phiên bản API: Để biết ý kiến và đề xuất của Apigee về việc tạo phiên bản API, hãy xem phần Tạo phiên bản trong sách điện tử Thiết kế API web: Đường liên kết bị thiếu.

Bật CORS

Trước khi phát hành API, bạn cần bật CORS trên các proxy API của mình để hỗ trợ các yêu cầu trên nhiều nguồn gốc phía máy khách.

CORS (Chia sẻ tài nguyên nhiều nguồn gốc) là một cơ chế tiêu chuẩn cho phép các lệnh gọi JavaScript XMLHttpRequest (XHR) được thực thi trên một trang web tương tác với các tài nguyên từ các miền không phải nguồn gốc. CORS là một giải pháp thường được triển khai cho chính sách cùng nguồn gốc được thực thi trên tất cả các trình duyệt. Ví dụ: nếu bạn thực hiện lệnh gọi XHR đến API Twitter từ việc thực thi mã JavaScript trong trình duyệt, thì lệnh gọi sẽ không thành công. Lý do là miền phân phát trang đến trình duyệt không giống với miền phân phát trang Twitter API. CORS cung cấp giải pháp cho vấn đề này bằng cách cho phép các máy chủ "chọn tham gia" nếu muốn cung cấp tính năng chia sẻ tài nguyên trên nhiều nguồn gốc.

Để biết thông tin về cách bật CORS trên proxy API trước khi phát hành API, hãy xem phần Thêm tính năng hỗ trợ CORS vào một proxy API.

Kích thước tải trọng thư

Để tránh vấn đề về bộ nhớ trong Edge, kích thước tải trọng thư được giới hạn ở mức 10 MB. Nếu vượt quá các kích thước đó, bạn sẽ gặp lỗi protocol.http.TooBigBody.

Vấn đề này cũng được thảo luận trong bài đăng này trên Cộng đồng Apigee.

Sau đây là các chiến lược được đề xuất để xử lý thông báo có kích thước lớn trong Edge:

  • Tạo luồng yêu cầu và phản hồi. Xin lưu ý rằng khi bạn phát trực tiếp, các chính sách sẽ không có quyền truy cập vào nội dung tin nhắn đó nữa. Xem phần Yêu cầu và phản hồi truyền trực tuyến.
  • Trong Edge dành cho đám mây riêng tư phiên bản 4.15.07 trở về trước, hãy chỉnh sửa tệp http.properties của trình xử lý thông báo để tăng giới hạn trong tham số HTTPResponse.body.buffer.limit. Hãy nhớ kiểm thử trước khi triển khai thay đổi cho phiên bản chính thức.
  • Trong Edge dành cho đám mây riêng tư phiên bản 4.16.01 trở lên, các yêu cầu có tải trọng phải bao gồm tiêu đề Content-Length (Độ dài nội dung) hoặc trong trường hợp truyền trực tuyến tiêu đề "Transfer-Encoding: chunked". Đối với yêu cầu POST đến proxy API có tải trọng trống, bạn phải chuyển Content-Length là 0.
  • Trong Edge dành cho đám mây riêng tư phiên bản 4.16.01 trở lên, hãy đặt các thuộc tính sau trong /opt/apigee/router.properties hoặc message-processor.properties để thay đổi giới hạn. Hãy xem bài viết Đặt giới hạn kích thước thông báo trên Bộ định tuyến hoặc Bộ xử lý thư để biết thêm thông tin.

    Cả hai tài sản đều có giá trị mặc định là "10m" tương ứng với 10 MB:
    • conf_http_HTTPRequest.body.buffer.limit
    • conf_http_HTTPResponse.body.buffer.limit

Xử lý lỗi

  • Tận dụng FaultRules để xử lý mọi lỗi. (Các chính sách RaiseFault được dùng để dừng Luồng thông báo và gửi quá trình xử lý đến Luồng thông báo FaultRules.)
  • Trong Luồng lỗi FaultRules, hãy sử dụng các chính sách composeMessage để tạo phản hồi lỗi, chứ không phải chính sách RaiseFault. Thực thi các chính sáchassignMessage có điều kiện dựa trên loại lỗi xảy ra.
  • Luôn bao gồm một trình xử lý lỗi "toàn bộ" mặc định để các lỗi do hệ thống tạo ra có thể được liên kết với các định dạng phản hồi lỗi do khách hàng xác định.
  • Nếu có thể, hãy luôn tạo các phản hồi lỗi khớp với mọi định dạng tiêu chuẩn có trong công ty hoặc dự án của bạn.
  • Sử dụng các thông báo lỗi có ý nghĩa, mà con người có thể đọc được để đề xuất giải pháp cho tình trạng lỗi.

Hãy xem phần Xử lý lỗi.

Để biết các phương pháp hay nhất trong ngành, hãy xem phần Thiết kế phản hồi lỗi RESTful.

Khả năng lưu trữ dài lâu

Bản đồ khoá/giá trị

  • Chỉ sử dụng bản đồ khoá/giá trị cho các tập dữ liệu có giới hạn. Các tài sản này không được thiết kế để trở thành nơi lưu trữ dữ liệu dài hạn.
  • Hãy xem xét hiệu suất khi sử dụng bản đồ khoá/giá trị vì thông tin này được lưu trữ trong cơ sở dữ liệu Cassandra.

Xem Chính sách về hoạt động bản đồ khoá giá trị.

Lưu phản hồi vào bộ nhớ đệm

  • Đừng điền sẵn vào bộ nhớ đệm phản hồi nếu phản hồi không thành công hoặc nếu yêu cầu không phải là một GET. Các tác vụ tạo, cập nhật và xoá không được lưu vào bộ nhớ đệm. <SkipCachePopulation>response.status.code != 200 or request.verb != "GET"</SkipCachePopulation>
  • Điền một loại nội dung nhất quán vào bộ nhớ đệm (ví dụ: XML hoặc JSON). Sau khi truy xuất một mục responseCache, hãy chuyển đổi sang loại nội dung cần thiết bằng JSONtoXML hoặc XMLToJSON. Điều này sẽ ngăn việc lưu trữ dữ liệu gấp đôi, gấp ba hoặc nhiều dữ liệu hơn.
  • Đảm bảo rằng khoá bộ nhớ đệm đủ đáp ứng yêu cầu lưu vào bộ nhớ đệm. Trong nhiều trường hợp, request.querystring có thể được dùng làm giá trị nhận dạng duy nhất.
  • Đừng đưa khoá API (client_id) vào khoá bộ nhớ đệm, trừ phi được yêu cầu rõ ràng. Thông thường, các API chỉ được bảo mật bằng một khoá sẽ trả về cùng một dữ liệu cho tất cả ứng dụng đối với một yêu cầu nhất định. Sẽ không hiệu quả nếu lưu trữ cùng một giá trị cho một số mục nhập dựa trên khoá API.
  • Hãy đặt khoảng thời gian hết hạn thích hợp của bộ nhớ đệm để tránh việc đọc dữ liệu sửa đổi.
  • Bất cứ khi nào có thể, hãy cố gắng thiết lập chính sách bộ nhớ đệm phản hồi để điền vào bộ nhớ đệm sẽ thực thi tại PostFlow phản hồi ProxyEndpoint càng muộn càng tốt. Nói cách khác, hãy yêu cầu nó thực thi sau các bước dịch và dàn xếp, bao gồm cả hoạt động dàn xếp dựa trên JavaScript và chuyển đổi giữa JSON và XML. Bằng cách lưu dữ liệu đã dàn xếp vào bộ nhớ đệm, bạn sẽ tránh được chi phí hiệu suất khi thực thi bước dàn xếp mỗi khi truy xuất dữ liệu đã lưu vào bộ nhớ đệm.

    Xin lưu ý rằng bạn nên lưu dữ liệu chưa qua trung gian vào bộ nhớ đệm nếu hoạt động dàn xếp dẫn đến một phản hồi khác với yêu cầu đối với yêu cầu.

  • Chính sách bộ nhớ đệm phản hồi để tra cứu mục bộ nhớ đệm sẽ diễn ra trong PreFlow của yêu cầu ProxyEndpoint. Tránh triển khai quá nhiều logic, ngoài việc tạo khoá bộ nhớ đệm, trước khi trả về một mục trong bộ nhớ đệm. Nếu không, lợi ích của việc lưu vào bộ nhớ đệm sẽ bị giảm thiểu.
  • Nhìn chung, bạn nên duy trì hoạt động tra cứu bộ nhớ đệm phản hồi càng gần với yêu cầu ứng dụng càng tốt. Ngược lại, bạn nên giữ tập hợp bộ nhớ đệm phản hồi càng gần với phản hồi của ứng dụng càng tốt.
  • Khi sử dụng nhiều chính sách bộ nhớ đệm phản hồi khác nhau trong một proxy, hãy làm theo các nguyên tắc sau để đảm bảo hoạt động riêng biệt cho từng chính sách:
    • Thực thi từng chính sách dựa trên các điều kiện loại trừ lẫn nhau. Điều này sẽ đảm bảo rằng chỉ một trong nhiều chính sách bộ nhớ đệm phản hồi được thực thi.
    • Xác định các tài nguyên bộ nhớ đệm khác nhau cho từng chính sách bộ nhớ đệm phản hồi. Bạn sẽ chỉ định tài nguyên bộ nhớ đệm trong phần tử <CacheResource> của chính sách.

Xem Chính sách về bộ nhớ đệm của phản hồi.

Chính sách và mã tuỳ chỉnh

Chính sách hay mã tuỳ chỉnh?

  • Trước hết, hãy sử dụng các chính sách tích hợp sẵn (khi có thể). Chúng tôi củng cố, tối ưu hoá và hỗ trợ các chính sách của Apigee. Ví dụ: sử dụng các chính sách chuẩnassignMessage và ExtractVariables thay vì JavaScript (nếu có thể) để tạo tải trọng, trích xuất thông tin từ tải trọng (XPath, JSONPath), v.v.
  • JavaScript được ưu tiên hơn Python và Java. Tuy nhiên, nếu hiệu suất là yêu cầu chính, thì bạn nên dùng Java thay vì JavaScript.

JavaScript

  • Sử dụng JavaScript nếu ngôn ngữ này trực quan hơn các chính sách của Apigee (ví dụ: khi đặt target.url cho nhiều tổ hợp URI khác nhau).
  • Phân tích cú pháp tải trọng phức tạp, chẳng hạn như lặp lại thông qua đối tượng JSON và mã hoá/giải mã Base64.
  • Chính sách JavaScript có giới hạn thời gian, nên vòng lặp vô hạn sẽ bị chặn.
  • Luôn sử dụng các bước JavaScript và đặt tệp vào thư mục tài nguyên jsc. Loại Chính sách JavaScript biên dịch trước mã tại thời điểm triển khai.

Hãy xem phần Lập trình proxy API bằng JavaScript.

Java

  • Dùng Java nếu hiệu suất là mức độ ưu tiên cao nhất hoặc nếu logic không thể triển khai trong JavaScript.
  • Bao gồm các tệp nguồn Java trong theo dõi mã nguồn.

Vui lòng xem bài viết Chuyển đổi phản hồi sang chữ hoa bằng chú thích Java và Chính sách về chú thích Java để biết thêm thông tin về cách sử dụng Java trong proxy API.

Python

  • Đừng dùng Python trừ phi thực sự bắt buộc. Tập lệnh Python có thể gây ra nút thắt cổ chai về hiệu suất cho các quá trình thực thi đơn giản, vì điều này được diễn giải trong thời gian chạy.

Chú thích cho tập lệnh (Java, JavaScript, Python)

  • Sử dụng quy trình thử/nắm bắt trên toàn cầu hoặc phiên bản tương đương.
  • Gửi những ngoại lệ có ý nghĩa và phát hiện đúng cách để sử dụng trong phản hồi lỗi.
  • Phát hiện và phát hiện sớm các ngoại lệ. Không sử dụng try/catch chung để xử lý mọi ngoại lệ.
  • Kiểm tra giá trị rỗng và không xác định khi cần thiết. Ví dụ về thời điểm nên làm việc này là khi truy xuất các biến luồng không bắt buộc.
  • Tránh thực hiện yêu cầu HTTP/S bên trong chú thích theo tập lệnh. Thay vào đó, hãy sử dụng chính sách Chú thích dịch vụ Apigee vì chính sách này xử lý các mối kết nối một cách linh hoạt.

JavaScript

  • JavaScript trên Nền tảng API hỗ trợ XML thông qua E4X.

Xem phần Mô hình đối tượng JavaScript.

Java

  • Khi truy cập vào các gói dữ liệu thư, hãy thử sử dụng context.getMessage() so với context.getResponseMessage hoặc context.getRequestMessage. Điều này đảm bảo rằng mã có thể truy xuất tải trọng, trong cả luồng yêu cầu và phản hồi.
  • Nhập thư viện vào tổ chức hoặc môi trường Apigee Edge và không đưa các thư viện này vào tệp JAR. Điều này giúp giảm kích thước gói và cho phép các tệp JAR khác truy cập vào cùng một kho lưu trữ thư viện.
  • Nhập các tệp JAR bằng API tài nguyên Apigee thay vì đưa các tệp này vào thư mục tài nguyên proxy API. Điều này sẽ làm giảm thời gian triển khai và cho phép cùng một tệp JAR được tham chiếu qua nhiều proxy API. Một lợi ích khác là cô lập trình tải lớp.
  • Không sử dụng Java để xử lý tài nguyên (ví dụ: tạo và quản lý nhóm luồng).

Vui lòng xem phần Chuyển đổi phản hồi sang chữ hoa bằng chú thích Java.

Python

  • Gửi những ngoại lệ có ý nghĩa và phát hiện đúng cách những ngoại lệ này để sử dụng trong phản hồi lỗi Apigee

Xem Chính sách về tập lệnh Python.

ServiceCallouts

  • Có nhiều trường hợp sử dụng hợp lệ trong việc tạo chuỗi proxy, trong đó bạn dùng chú thích dịch vụ trong một proxy API để gọi một proxy API khác. Nếu bạn sử dụng chuỗi proxy, hãy nhớ tránh sử dụng chú thích đệ quy "vô hạn" lần nữa vào cùng một proxy API.

    Nếu bạn đang kết nối giữa các proxy trong cùng một tổ chức và môi trường, hãy nhớ xem phần Chuỗi proxy API với nhau để biết thêm thông tin về cách triển khai kết nối cục bộ nhằm tránh hao tổn mạng không cần thiết.

  • Tạo thông báo yêu cầu Service bằng cách sử dụng chính sách tasksMessage và điền sẵn đối tượng yêu cầu trong một biến thông báo. (Việc này bao gồm cả việc đặt trọng tải, đường dẫn và phương thức yêu cầu.)
  • URL được định cấu hình trong chính sách này phải có quy cách giao thức, nghĩa là một biến không thể chỉ định phần giao thức của URL (ví dụ: https://). Ngoài ra, bạn phải sử dụng các biến riêng cho phần miền của URL và phần còn lại của URL. Ví dụ: https://{domain}/{path}
  • Lưu trữ đối tượng phản hồi cho một Chú thích dịch vụ trong một biến thông báo riêng. Sau đó, bạn có thể phân tích cú pháp biến thông báo và giữ nguyên phần tải thông báo ban đầu để các chính sách khác sử dụng.

Xem Chính sách về chú thích dịch vụ.

Truy cập vào thực thể

Chính sách AccessEntity

  • Để đạt được hiệu suất cao hơn, hãy tra cứu ứng dụng theo uuid thay vì tên ứng dụng.

Hãy xem Chính sách về thực thể truy cập.

Ghi nhật ký

  • Sử dụng một chính sách nhật ký hệ thống chung trên các gói và trong cùng một gói. Việc này sẽ giúp duy trì một định dạng ghi nhật ký nhất quán.

Xem Chính sách về việc ghi nhật ký thư.

Giám sát

Khách hàng Google Cloud không bắt buộc phải kiểm tra các thành phần riêng lẻ của Apigee Edge (Bộ định tuyến, Bộ xử lý tin nhắn, v.v.). Nhóm Hoạt động toàn cầu của Apigee đang giám sát kỹ lưỡng tất cả các thành phần, cùng với quy trình kiểm tra tình trạng API, theo yêu cầu kiểm tra tình trạng của khách hàng.

Số liệu phân tích của Apigee

Analytics có thể cung cấp dữ liệu giám sát API không quan trọng khi đo lường tỷ lệ phần trăm lỗi.

Xem trang tổng quan của Analytics.

Trace

Công cụ theo dõi trong Giao diện người dùng quản lý API Edge rất hữu ích khi gỡ lỗi các vấn đề về API thời gian chạy, trong quá trình phát triển hoặc hoạt động chính thức của một API.

Hãy xem bài viết Sử dụng công cụ Theo dõi.

Bảo mật