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

Ngoài các nguyên tắc ở đây, bạn cũng có thể thấy bài đăng trên Cộng đồng về Các mẫu chống Apigee Edge 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 cùng dòng trong cấu hình ProxyEndpoint và TargetEndpoint. Chú thích giúp tăng khả năng đọc của Flow, đặ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 Flow.
  • Viết bình luận hữu ích. Tránh các nhận xét rõ ràng.
  • Sử dụng khoảng thụt lề, khoảng cách, căn chỉnh theo chiều dọc, v.v. nhất quán.

Mã hoá theo kiểu khung

Việc lập trình theo 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 hệ thống quản lý nguồn để nhà phát triển có thể đồng bộ hoá với chính sách đó 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 ("don't repeat yourself" – "đừng lặp lại chính mình"), nếu có thể, các 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ể sử dụng lại. 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. Bạn có thể gọi một chính sách chuyên dụng để chèn tiêu đề CORS 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 tham số hoặc đặt tiêu đề CORS mà không cần tạo cấu hình 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 proxy API, đặc biệt là các tài nguyên lớn có khả năng làm chậm các quy 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 name của chính sách ServiceCallout và Script phải giống với tên của tệp tài nguyên.
  • 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 của chính sách đó. Apigee khuyên bạn nên thiết lập 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 đuôi tệp tài nguyên thích hợp, .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ộ 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

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

  • Để được hướng dẫn về cách thiết kế API RESTful, hãy tải sách điện tử Thiết kế API web: Mối 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 lập trình tất cả logic proxy trong tài nguyên JavaScript, Java hoặc Python.
  • Xây dựng Flow theo cách có tổ chức. Bạn nên sử dụng nhiều Flow, mỗi Flow có một điều kiện, thay vì nhiều tệp đính kèm có điều kiện cho cùng một PreFlow và Postflow.
  • Để "an toàn khi gặp sự cố", hãy tạo một proxy API mặc định có BasePath ProxyEndpoint 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ơ sở đến 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 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ợ hoạt động 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à một RouteRule không có điều kiện. Đảm bảo rằng RouteRule mặc định được xác định ở cuối danh sách Route 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 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 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.
  • 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 Phiên bản trong sách điện tử Thiết kế API web: Mối 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 proxy API để hỗ trợ các yêu cầu nhiều nguồn gốc phía máy khách.

CORS (Chia sẻ tài nguyên trên nhiều nguồn gốc) là một cơ chế 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ô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 mà tất cả trình duyệt đều thực thi. Ví dụ: nếu bạn thực hiện lệnh gọi XHR đến API Twitter 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 giải pháp cho vấn đề này bằng cách cho phép 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 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 proxy API.

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

Để ngăn các sự cố về bộ nhớ trong Edge, kích thước tải trọng của thông báo bị hạn chế ở 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 đề xuất để xử lý kích thước thư lớn trong Edge:

  • Yêu cầu và phản hồi của luồng. Xin lưu ý rằng khi bạn truyền trực tuyến, các chính sách sẽ không còn 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 for Private Cloud 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 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 lên môi trường chính thức.
  • 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 đề Content-Length 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 for Private Cloud 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. Hãy xem phần Đặt giới hạn kích thước thông báo trên Trình đị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 10MB:
    • 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ả lỗi. (Chính sách RaiseFault được dùng để dừng Flow thông báo và gửi quy trình xử lý đến Flow FaultRules.)
  • Trong quy trình FaultRules, hãy sử dụng chính sách AssignMessage để tạo phản hồi lỗi, chứ không phải 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 trình xử lý lỗi "thu thập tất cả" mặc định để có thể ánh xạ các lỗi do hệ thống tạo đế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 phản hồi lỗi khớp với mọi định dạng chuẩn có trong công ty hoặc dự án của bạn.
  • Sử dụng thông báo lỗi có ý nghĩa, dễ đọc 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 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ệp này không được thiết kế để lưu trữ dữ liệu lâu dài.
  • Hãy cân nhắc 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ề thao tác liên kết khoá-giá trị.

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

  • Không điề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 các thao tác tạo, cập nhật và xoá vào bộ nhớ đệm. <SkipCachePopulation>response.status.code != 200 or request.verb != "GET"</SkipCachePopulation>
  • Điền 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ụ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á bộ nhớ đệm đủ đáp ứng yêu cầu lưu vào bộ nhớ đệm. Trong nhiều trường hợp, bạn có thể sử dụng request.querystring làm giá trị nhận dạng duy nhất.
  • Không đưa khoá API (client_id) vào khoá bộ nhớ đệm, trừ phi yêu cầu rõ ràng. Trong hầu hết trường hợp, 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 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 nhập dựa trên khoá API là không hiệu quả.
  • Đặt khoảng thời gian hết hạn bộ nhớ đệm thích hợp để tránh tình trạng đọc không sạch.
  • Bất cứ khi nào có thể, hãy cố gắng đưa chính sách bộ nhớ đệm phản hồi vào để thực thi bộ nhớ đệm tại PostFlow phản hồi ProxyEndpoint muộn nhất có thể. Nói cách khác, hãy thực thi quy trình này sau các bước dịch và dàn xếp, bao gồm cả quy trình dàn xếp và chuyển đổi dựa trên JavaScript 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 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 có thể muốn lưu dữ liệu chưa dàn xếp vào bộ nhớ đệm nếu quá trình dàn xếp dẫn đến 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 nhập bộ nhớ đệm sẽ xảy ra trong yêu cầu PreFlow của 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 nhập 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 phải luôn giữ cho lượt tra cứu bộ nhớ đệm phản hồi gần với yêu cầu của ứng dụng nhất có thể. Ngược lại, bạn nên duy trì việc điền 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 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 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 tiên, 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 tăng cường, tối ưu hoá và được hỗ trợ. Ví dụ: sử dụng chính sách AssignMessage và ExtractVariables tiêu chuẩn thay vì JavaScript (khi có thể) để tạo tải trọng, trích xuất thông tin từ tải trọng (XPath, JSONPath), v.v.
  • Bạn nên sử dụng JavaScript thay vì Python và Java. Tuy nhiên, nếu hiệu suất là yêu cầu chính, bạn nên sử dụng Java thay vì JavaScript.

JavaScript

  • Sử dụng JavaScript nếu nó 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 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 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.
  • Thêm các 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 chú thích Java và Chính sách về chú thích Java để biết thông tin về cách sử dụng Java trong proxy API.

Python

  • Không sử dụng Python trừ khi thực sự cần thiết. Tập lệnh Python có thể gây ra nút thắt cổ chai về hiệu suất cho các lần 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.
  • Gửi các ngoại lệ có ý nghĩa và phát hiện các ngoại lệ này đúng cách để sử dụng trong phản hồi lỗi.
  • Gửi và phát hiện sớm các ngoại lệ. Không sử dụng try/catch toàn cục để xử lý tất cả ngoại lệ.
  • Thực hiện kiểm tra giá trị rỗng và không xác định khi cần. Ví dụ về thời điểm thực hiện việc này là khi truy xuất các biến flow không bắt buộc.
  • Tránh tạo 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 ServiceCallout của Apigee vì chính sách này xử lý các 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 Mô hình đối tượng JavaScript.

Java

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

  • Gửi các ngoại lệ có ý nghĩa và phát hiện các ngoại lệ này đúng cách để 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ệ để sử dụng tính năng tạo chuỗi proxy, trong đó bạn sử dụng một lời 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 tính năng tạo chuỗi proxy, hãy nhớ tránh các chú thích 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 Kết nối chuỗi các proxy API với nhau để biết thêm về cách triển khai kết nối cục bộ giúp tránh 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 biến thông báo. (Điều này bao gồm 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 thông số kỹ thuật giao thức, nghĩa là phần giao thức của URL, ví dụ: https://, không thể được chỉ định bằng 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 cú pháp 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 thực thể

Chính sách AccessEntity

  • Để có hiệu suất tốt hơn, hãy tra cứu ứ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 một chính sách syslog chung trên các gói và trong cùng một gói. Điều 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ề tính năng Ghi nhật ký thông báo.

Giám sát

Khách hàng sử dụng dịch vụ đám mây không bắt buộc phải kiểm tra từng thành phần của Apigee Edge (Trình định tuyến, Trình xử lý thông báo, v.v.). Nhóm vận hành toàn cầu của Apigee đang theo dõi kỹ lưỡng tất cả các thành phần, cùng với các yêu cầu kiểm tra tình trạng của API do khách hàng đưa ra.

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ệ phần trăm lỗi.

Xem Bảng điều khiển 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 trong 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 API.

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

Bảo mật