Chuyển tới nội dung chính

Scripting (Góc nhìn nhà phát triển)

Script trước khi gửi / sau phản hồi là con dao đa năng của Quick Request: ký động, mã hóa & giải mã, assertion có điều kiện và chuyển giá trị chéo yêu cầu — tất cả nằm ở đây. Script viết bằng JavaScript và chạy trên engine QuickJS tích hợp sẵn.

Trang này chỉ nói về những gì bạn có thể thêm trong UI và script có thể làm gì; chữ ký JavaScript API đầy đủ xem Tài liệu tham khảo API Script.


Một yêu cầu có hai "Chuỗi Hành Động"​

Trang trình bày yêu cầu cho phép bạn thêm nhiều bước vào các chuỗi trước khi gửi và sau phản hồi; chúng chạy theo thứ tự. Mỗi bước là một trong các loại:

Loại bướcBạn làm gì trong UIDùng điển hình
ScriptViết một đoạn JavaScriptĐổi header/body, ký, giải mã, logic có điều kiện
Script thư việnTham chiếu một script chia sẻ đã lưuTái sử dụng "chèn token", "logging thống nhất" ở nhiều nơi
Trích xuấtLấy một giá trị từ phản hồi và lưu thành biếnChuyển token đăng nhập cho yêu cầu tiếp theo
AssertionThêm một phép kiểm tra vào phản hồiMã trạng thái = 200, một trường tồn tại
ChờTạm dừng vài milli giâyGiới hạn tần suất, khoảng dò hỏi

Cách viết script: hai điểm vào​

Engine script tìm các hàm vào quen thuộc trong script của bạn:

// Pre-send: can change "the request that is about to go out"
async function onRequest(context, url, request) {
// e.g. inject a header
request.headers.set('X-Trace-Id', $uuid.v4());
return request; // you must return the request
}

// Post-response: can read and change "the response you received"
async function onResponse(context, url, response) {
// e.g. rewrite an encrypted response back to plaintext for humans
return response;
}
  • Viết onRequest trong chuỗi trước khi gửi, onResponse trong chuỗi sau phản hồi.
  • Tên hàm phải chính xác như vậy, nếu không script bị coi là "không có điểm vào" và bị bỏ qua.
  • await được hỗ trợ.

Script có thể thay đổi gì​

Thay đổi yêu cầu (đối tượng request trong onRequest)​

Bạn muốnCách làm
Đặt / ghi đè headerrequest.headers.set('Authorization', 'Bearer ' + tok)
Thêm / đổi tham số truy vấnrequest.queries.set('ts', String(Date.now()))
Đọc body thôvar text = request.body.parseText() hoặc request.body.parseJSON()
Viết lại toàn bộ bodyrequest.body = the new string (gán thuần túy)

Đọc / thay đổi phản hồi (đối tượng response trong onResponse)​

Bạn muốnCách làm
Đọc mã trạng tháiresponse.statusCode
Đọc header phản hồiresponse.headers.get('Set-Cookie')
Đọc bodyresponse.body.parseJSON() / .parseText()
Viết lại toàn bộ body phản hồiresponse.body = the new string — giao diện UI/kết quả hiển thị nội dung đã viết lại (đã xác minh)

Năng lực tích hợp — đừng phát minh lại bánh xe​

Script có sẵn một loạt công cụ tích hợp (sdk.*) và năng lực gốc có tiền tố $: mã hóa, hàm băm, mã hóa ký tự, ngẫu nhiên và JSONPath đều được phủ:

Năng lựcDùng gì
Đọc / ghi biến (chuyển chéo yêu cầu)sdk.env.get(name) / sdk.env.set(name, value)
Kiểm tra khai báosdk.test('status should be 200', function(){ sdk.expect(response.statusCode).toBe(200) })
Truy vấn JSONPathsdk.jsonPath('$.data.id')
Mã hóa / giải mã AES$crypto.encryptAES(plaintext, key[, iv]) / $crypto.decryptAES(ciphertext, key[, iv])
Băm MD5 / SHA (ký)$hash.md5(...) / $hash.sha256(...) (trả hex, chuẩn & tương thích)
UUID$uuid.v4()
Base64 trên chuỗisdk.utils.base64Encode(str) / base64Decode(str)

⚠️ Engine là QuickJS: không có crypto.subtle kiểu trình duyệt, và crypto.getRandomValues không hoạt động trong engine này (không điền mảng truyền vào) — dùng $crypto cho AES, và crypto.randomUUID / $uuid cho ngẫu nhiên. Đừng tìm tới WebCrypto. Chữ ký và lưu ý đầy đủ: Tài liệu tham khảo API Script.


Tải thư viện script bằng require()​

Logic chia sẻ cũng có thể được tải bằng require() kiểu CommonJS thay vì thêm như một bước. Khóa luôn là @libs/<key>, được phân giải theo thứ tự:

  1. Định danh thư viện script — khớp chính xác, ổn định qua việc đổi tên (khuyến nghị)
  2. Tên thư viện script — dễ đọc, nhưng đổi tên thư viện làm hỏng tham chiếu (tên trùng mơ hồ bị bỏ qua)
  3. Thư viện tích hợp — kèm theo ứng dụng

Thư viện tích hợp​

KhóaXuấtGhi chú
@libs/base64encode(str) / decode(text)Base64 an toàn UTF-8 (tiếng Trung & emoji an toàn); decode bỏ qua khoảng trắng, chuỗi không hợp lệ giữ dưới dạng Latin-1
@libs/hexencode(str) / decode(text)Hex chữ thường an toàn UTF-8; decode bỏ qua ký tự không phải hex, độ dài lẻ ném ngoại lệ

Cả hai cũng được phơi bày như bí danh toàn cục (base64.encode(...) / hex.encode(...)) — require chỉ cung cấp kiểu import tường minh.

const { encode } = require('@libs/base64');
encode('hello 中文'); // 'aGVsbG8g5Lit5aSp'

Thư viện script của riêng bạn​

Lưu các hàm tái sử dụng dưới dạng thư viện script (xuất qua module.exports, không cần hàm vào) và tải nó từ bất kỳ script trước/sau nào:

// script library "sign-lib"
function sign(method, path, body, secret) {
return $hmac.sha256(method + path + body, secret);
}
module.exports = { sign };
// any request script
async function onRequest(context, url, request) {
const { sign } = require('@libs/sign-lib');
request.headers.set('X-Sign', sign('POST', request.path, request.body.parseText(), sdk.env.get('secret')));
return request;
}
  • Dùng Copy require statement trong trình quản lý thư viện để lấy dạng định danh ổn định.
  • Thư viện có thể require thư viện khác — toàn bộ bao đóng phụ thuộc được đóng gói tự động (vòng lặp được phân giải theo kiểu Node, không vòng lặp vô hạn).
  • Bộ nhớ đệm mô-đun được dựng lại mỗi lần thực thi: thư viện không bao giờ mang trạng thái giữa các yêu cầu.
  • Để tái sử dụng một gói npm, hãy đóng gói nó thành một tệp trước (ví dụ esbuild --format=iife, hoặc Browserify/Webpack), import tệp đó như một thư viện script, rồi require('@libs/<name>'). Chọn bản dựng JS thuần không phụ thuộc Node (Buffer/fs/crypto/process) hay DOM.
  • Khóa thiếu ném Error: require: 未找到库 [...] — thất bại trước khi gửi làm ngắt yêu cầu, thất bại sau phản hồi giữ nguyên phản hồi gốc. Các lời gọi require trong chú thích bị bỏ qua.

Ngữ nghĩa require đầy đủ: Tài liệu tham khảo API Script.


Nhiều script cộng tác thế nào​

Khi một yêu cầu có nhiều script, chúng chia sẻ cùng một globalThis (đã xác minh). Nhờ đó bạn có thể:

Lợi ích: mỗi script có một trách nhiệm duy nhất và có thể bật/tắt độc lập. "Script thư viện" cũng là một script đầy đủ (với onRequest/onResponse riêng) — thêm nó như một bước để chạy cả chuỗi, hoặc giữ các hàm thuần trong đó bằng module.exports và tải bằng require('@libs/<key>') (xem Tải thư viện script bằng require()).

Các ví dụ chuỗi cụ thể (đăng nhập lấy token, vòng lặp AES) xem recipes.