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ước | Bạn làm gì trong UI | Dùng điển hình |
|---|---|---|
| Script | Viết một đoạn JavaScript | Đổi header/body, ký, giải mã, logic có điều kiện |
| Script thư viện | Tham chiếu một script chia sẻ đã lưu | Tái sử dụng "chèn token", "logging thống nhất" ở nhiều nơi |
| Trích xuất | Lấy một giá trị từ phản hồi và lưu thành biến | Chuyển token đăng nhập cho yêu cầu tiếp theo |
| Assertion | Thêm một phép kiểm tra vào phản hồi | Mã trạng thái = 200, một trường tồn tại |
| Chờ | Tạm dừng vài milli giây | Giớ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
onRequesttrong chuỗi trước khi gửi,onResponsetrong 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ốn | Cách làm |
|---|---|
| Đặt / ghi đè header | request.headers.set('Authorization', 'Bearer ' + tok) |
| Thêm / đổi tham số truy vấn | request.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ộ body | request.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ốn | Cách làm |
|---|---|
| Đọc mã trạng thái | response.statusCode |
| Đọc header phản hồi | response.headers.get('Set-Cookie') |
| Đọc body | response.body.parseJSON() / .parseText() |
| Viết lại toàn bộ body phản hồi | response.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ực | Dù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áo | sdk.test('status should be 200', function(){ sdk.expect(response.statusCode).toBe(200) }) |
| Truy vấn JSONPath | sdk.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ỗi | sdk.utils.base64Encode(str) / base64Decode(str) |
⚠️ Engine là QuickJS: không có
crypto.subtlekiểu trình duyệt, vàcrypto.getRandomValueskhông hoạt động trong engine này (không điền mảng truyền vào) — dùng$cryptocho AES, vàcrypto.randomUUID/$uuidcho 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ự:
- Định danh thư viện script — khớp chính xác, ổn định qua việc đổi tên (khuyến nghị)
- 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)
- Thư viện tích hợp — kèm theo ứng dụng
Thư viện tích hợp
| Khóa | Xuất | Ghi chú |
|---|---|---|
@libs/base64 | encode(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/hex | encode(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ể
requirethư 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ồirequire('@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ọirequiretrong 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.