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.
Truy cập vào tài liệu 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 dựa trên kinh nghiệm của các nhà phát triển khi làm việc với Apigee để triển khai các chương trình API thành công. Đây là một tài liệu đang được chỉnh sửa và sẽ được cập nhật theo thời gian.

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

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

Bình luận và tài liệu

  • Cung cấp nhận xét nội dòng trong cấu hình ProxyEndpoint và TargetEndpoint. Chú thích giúp tăng khả năng đọc cho một Luồng, đặc biệt là khi tên tệp chính sách không đủ mô tả để thể hiện chức năng cơ bản của Luồng.
  • Đảm bảo bình luận hữu ích. Tránh những bình luận hiển nhiên.
  • Sử dụng thụt lề, khoảng cách, căn chỉnh theo chiều dọc, v.v. một cách nhất quán.

Lập trình theo kiểu khung

Phương thức lập trình theo kiểu khung liên quan đến việc lưu trữ các 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 tính năng 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 của riêng họ.

  • Để bật DRY ("đừng lặp lại chính mình"), nếu có thể, cấu hình chính sách và tập lệnh phải triển khai các hàm chuyên biệt, có thể tái sử dụng. Ví dụ: một chính sách chuyên dụ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. Một chính sách chuyên biệt để chèn tiêu đề CORS có thể được gọi là AssignMessage.SetCORSHeaders. Sau đó, bạn có thể lưu trữ các chính sách đó trong hệ thống kiểm soát nguồn và thêm vào từng proxy API cần trích xuất các tham số hoặc đặt tiêu đề CORS mà không cần tạo các cấu hình dư thừa (và do đó khó quản lý hơn).
  • Dọn dẹp các chính sách và tài nguyên không dùng đến (JavaScript, Java, XSLT, v.v.) khỏi các proxy API, đặc biệt là những tài nguyên lớn có khả năng làm chậm quá trình nhập và triển khai.

Quy ước đặt tên

  • Thuộc tính Chính sách name và tên tệp chính sách XML phải giống nhau.
  • Thuộc tính Chính sách về tập lệnh và ServiceCallout name 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 đó trước đây.
  • Đặt tên cho các chính sách theo chức năng của chúng. Apigee khuyến nghị bạ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 các chính sách AssignMessage. Xem thêm công cụ apigeelint.
  • Sử dụng các tiện ích phù hợp cho tệp tài nguyên, .js cho JavaScript, .py cho Python và .jar cho 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 toàn bộ API proxy.
  • 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

Những điều cần cân nhắc khi thiết kế ban đầu

  • Để được hướng dẫn về thiết kế API RESTful, hãy tải sách điện tử Thiết kế API web: Mắt xích còn 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 các proxy API. Tránh mã hoá tất cả logic của proxy trong các tài nguyên JavaScript, Java hoặc Python.
  • Xây dựng các luồng một cách có tổ chức. Nhiều luồng, mỗi luồng có một điều kiện duy nhất, sẽ thích hợp hơn so với nhiều tệp đính kèm có điều kiện cho cùng một PreFlow và Postflow.
  • Để đảm bảo an toàn, hãy tạo một API proxy mặc định có ProxyEndpoint BasePath là /. Bạn có thể dùng phương thức này để chuyển hướng các yêu cầu API cơ bản đến một trang web của nhà phát triển, trả về một 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 phần Cân bằng tải trên các máy chủ phụ trợ.
  • Nếu bạn có nhiều RouteRule, hãy tạo một RouteRule làm "mặc định", tức là RouteRule không có điều kiện. Đảm bảo rằng RouteRule mặc định được xác định sau cùng trong danh sách các Tuyến đường có điều kiện. RouteRules được đánh giá từ trên xuống trong ProxyEndpoint.
    Xem Tài liệu tham khảo về cấu hình của API proxy.
  • Kích thước gói proxy API: Các gói proxy API không được lớn hơn 15 MB. Trong Apigee Edge cho Private Cloud, bạn có thể thay đổi giới hạn 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: Mắt xích còn thiếu.

Bật CORS

Trước khi xuất bản API, bạn cần bật CORS trên các proxy API để hỗ trợ các yêu cầu khác nguồn gốc ở phía máy khách.

CORS (Chia sẻ tài nguyên khác nguồn gốc) là một cơ chế tiêu chuẩn cho phép các lệnh gọi XMLHttpRequest (XHR) của JavaScript được thực thi trong một trang web để tương tác với các tài nguyên từ các miền khác 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 do tất cả các trình duyệt thực thi. Ví dụ: nếu bạn thực hiện một lệnh gọi XHR đến Twitter API từ mã JavaScript đang thực thi trong trình duyệt, thì lệnh gọi sẽ không thành công. Điều này là do miền phân phát trang cho trình duyệt của bạn không giống với miền phân phát API Twitter. CORS cung cấp một giải pháp cho vấn đề này bằng cách cho phép các máy chủ "chọn sử dụng" nếu muốn cung cấp tính năng chia sẻ tài nguyên khác nguồn gốc.

Để biết thông tin về cách bật CORS trên các proxy API trước khi xuất bản 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 của thông báo

Để ngăn các vấn đề về bộ nhớ trong Edge, kích thước tải trọng của thông báo bị giới hạn ở mức 10 MB. Nếu vượt quá 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ý kích thước thư lớn trong Edge:

  • Truyền trực tuyến các 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òn quyền truy cập vào nội dung tin nhắn. Xem Yêu cầu và phản hồi truyền trực tuyến.
  • Trong Edge cho Đám mây riêng tư phiên bản 4.15.07 trở xuống, hãy chỉnh sửa tệp http.properties của trình xử lý thông báo để tăng hạn mức trong tham số HTTPResponse.body.buffer.limit. Hãy nhớ kiểm thử trước khi triển khai thay đổi cho bản phát hành công khai.
  • Trong Edge for Private Cloud 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 đề Độ 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 một proxy API có tải trọng trống, bạn phải truyền Content-Length là 0.
  • Trong Edge 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 các giới hạn. Xem phần Đặt giới hạn kích thước thông báo trên Bộ định tuyến hoặc Trình xử lý thông báo để biết thêm thông tin.

    Cả hai thuộc tính đề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ý tất cả các lỗi. (Các chính sách RaiseFault được dùng để dừng quy trình thông báo và gửi quá trình xử lý đến quy trình FaultRules.)
  • Trong FaultRules Flow, hãy sử dụng các chính sách AssignMessage để tạo phản hồi lỗi, chứ không phải các chính sách RaiseFault. Thực thi có điều kiện các chính sách AssignMessage dựa trên loại lỗi xảy ra.
  • Luôn bao gồm một trình xử lý lỗi "chung" mặc định để các lỗi do hệ thống tạo có thể được ánh xạ đến 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 đảm bả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 thông báo lỗi dễ hiểu, có ý nghĩa và đề xuất giải pháp cho điều kiện lỗi.

Xem phần Xử lý lỗi.

Để biết các phương pháp hay nhất trong ngành, hãy xem bài viết Thiết kế phản hồi lỗi theo kiểu 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. Chúng không được thiết kế để trở thành một kho dữ liệu dài hạn.
  • Hãy cân nhắc hiệu suất khi sử dụng các 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ề các thao tác trên bản đồ khoá-giá trị.

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

  • Không điền sẵn 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à GET. Không được lưu vào bộ nhớ đệm các thao tác tạo, cập nhật và xoá. <SkipCachePopulation>response.status.code != 200 or request.verb != "GET"</SkipCachePopulation>
  • Điền vào bộ nhớ đệm bằng một loại nội dung nhất quán (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 hơn.
  • Đảm bảo rằng khoá lưu vào bộ nhớ đệm đủ để đáp ứng yêu cầu về việc 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.
  • Không thêm khoá API (client_id) vào khoá bộ nhớ đệm, trừ phi được yêu cầu một cách rõ ràng. Thông thường, các API chỉ được bảo mật bằng khoá sẽ trả về cùng một dữ liệu cho tất cả các ứng dụng cho một yêu cầu nhất định. Việc lưu trữ cùng một giá trị cho một số mục dựa trên khoá API là không hiệu quả.
  • Đặt khoảng thời gian hết hạn của bộ nhớ đệm thích hợp để tránh đọc dữ liệu không chính xác.
  • Bất cứ khi nào có thể, hãy cố gắng để chính sách bộ nhớ đệm phản hồi điền sẵn bộ nhớ đệm thực thi ở PostFlow phản hồi ProxyEndpoint muộn nhất có thể. Nói cách khác, hãy để nó thực thi sau các bước dịch và dàn xếp, bao gồm cả việc 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 được dàn xếp vào bộ nhớ đệm, bạn tránh được chi phí hiệu suất khi thực hiện bước dàn xếp mỗi lần truy xuất dữ liệu được lưu vào bộ nhớ đệm.

    Xin lưu ý rằng bạn có thể muốn lưu dữ liệu chưa được dàn xếp 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 nhau giữa các yêu cầu.

  • Chính sách bộ nhớ đệm phản hồi để tra cứu mục trong bộ nhớ đệm sẽ diễn ra trong PreFlow 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ẽ giảm thiểu.
  • Nhìn chung, bạn phải luôn giữ cho quá trình tra cứu bộ nhớ đệm phản hồi gần với yêu cầu của máy khách nhất có thể. Ngược lại, bạn nên giữ số lượng bộ nhớ đệm phản hồi càng gần với phản hồi của máy khách 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 hành vi 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ẽ giúp đảm bảo rằng chỉ một trong số 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 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 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 (khi có thể). Các chính sách của Apigee được củng cố, tối ưu hoá và hỗ trợ. Ví dụ: sử dụng các chính sách AssignMessage và ExtractVariables tiêu chuẩn 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 sử dụng Java thay vì JavaScript.

JavaScript

  • Sử dụng JavaScript nếu bạn thấy dễ hiểu hơn so với các chính sách của Apigee (ví dụ: khi đặt target.url cho nhiều kiểu kế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 một đối tượng JSON và mã hoá/giải mã Base64.
  • Chính sách JavaScript có giới hạn thời gian, vì vậy các 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.

Xem phần Lập trình các proxy API bằng JavaScript.

Java

  • Sử dụng Java nếu hiệu suất là ưu tiên cao nhất hoặc nếu không thể triển khai logic trong JavaScript.
  • Đưa tệp nguồn Java vào tính năng theo dõi mã nguồn.

Hãy xem phần Chuyển đổi phản hồi thành chữ hoa bằng lệnh gọi Java và Chính sách về lệnh gọi Java để biết thông tin về cách sử dụng Java trong các proxy API.

Python

  • Không sử dụng Python trừ phi thực sự cần thiết. Tập lệnh Python có thể gây ra tình trạng tắc nghẽn hiệu suất cho các hoạt động thực thi đơn giản, vì tập lệnh này được diễn giải trong thời gian chạy.

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

  • Sử dụng try/catch chung hoặc tương đương.
  • Đưa ra các ngoại lệ có ý nghĩa và nắm bắt những ngoại lệ này một cách thích hợp để sử dụng trong các phản hồi lỗi.
  • Phát hiện và xử lý các trường hợp ngoại lệ từ sớm. Không sử dụng try/catch chung để xử lý tất cả các ngoại lệ.
  • Thực hiện các bước 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 thực hiện việc này là khi truy xuất các biến luồng không bắt buộc.
  • Tránh đưa ra các yêu cầu HTTP/S bên trong chú thích tập lệnh. Thay vào đó, hãy sử dụng chính sách Apigee ServiceCallout vì chính sách này xử lý các kết nối một cách hợp lý.

JavaScript

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

Xem mô hình đối tượng JavaScript.

Java

  • Khi truy cập vào tải trọng thông báo, hãy thử sử dụng context.getMessage() thay vì 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 các 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 tệp JAR bằng API tài nguyên Apigee thay vì đưa chúng vào thư mục tài nguyên của API proxy. Điều này sẽ giảm thời gian triển khai và cho phép nhiều proxy API tham chiếu cùng một tệp JAR. Một lợi ích khác là khả năng 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).

Xem phần Chuyển đổi phản hồi thành chữ hoa bằng chú thích Java.

Python

  • Đưa ra các ngoại lệ có ý nghĩa và nắm bắt những ngoại lệ này một cách thích hợp để sử dụng trong các phản hồi lỗi của 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ệ để sử dụng tính năng liên kết proxy, trong đó bạn sử dụng lệnh gọi 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 các lệnh gọi đệ quy "vòng lặp vô hạn" trở lại 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 Liên kết các proxy API với nhau để biết thêm thông tin về cách triển khai một kết nối cục bộ giúp tránh tình trạng hao tổn mạng không cần thiết.

  • Tạo thông báo yêu cầu ServiceCallout bằng chính sách AssignMessage và điền đối tượng yêu cầu vào một biến thông báo. (Trong đó có việc thiết lập tải trọng, đường dẫn và phương thức yêu cầu.)
  • URL được định cấu hình trong chính sách yêu cầu chỉ định giao thức, tức là phần giao thức của URL (ví dụ: https://) không thể được chỉ định bằng một biến. Ngoài ra, bạn phải sử dụng các biến riêng biệt cho phần miền của URL và cho 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 ServiceCallout trong một biến thông báo riêng. Sau đó, bạn có thể phân tích biến thông báo và giữ nguyên tải trọng 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 các thực thể

Chính sách AccessEntity

  • Để có hiệu suất tốt hơn, hãy tìm ứng dụng theo uuid thay vì tên ứng dụng.

Xem Chính sách về thực thể truy cập.

Ghi nhật ký

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

Xem Chính sách MessageLogging.

Giám sát

Khách hàng sử dụng đám mây không bắt buộc phải kiểm tra từng thành phần của Apigee Edge (Bộ định tuyến, Bộ xử lý thông báo, v.v.). Nhóm Vận hành 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 các quy trình kiểm tra tình trạng API, dựa trên các yêu cầu kiểm tra tình trạng của khách hàng.

Apigee Analytics

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

Xem Trang tổng quan về số liệu phân tích.

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 cho việc 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 sản xuất của một API.

Xem phần Sử dụng công cụ Theo dõi.

Bảo mật