Skip to content
smallPict
Bắt Đầu Miễn Phí

Kiến trúc SDK chính thức & Các nguyên tắc bất biến

Các nguyên tắc thiết kế thống nhất, bảo đảm an ninh và ngữ nghĩa chịu lỗi áp dụng trên toàn bộ 7 SDK chính thức của SmallPict.

SmallPict phát triển 7 SDK chính thức dành riêng cho các ngôn ngữ lập trình hiện đại, mang lại trải nghiệm phát triển nhất quán, tiện dụng và vững như bàn thạch trên mọi ngăn xếp công nghệ.

Giao diện 4 phương thức cốt lõi thống nhất

Bất kể ngôn ngữ lập trình hay quy ước đặt tên nào, mọi SDK SmallPict chính thức đều triển khai đầy đủ 4 thao tác nền tảng:

Tên phương thứcMô tả chức năng
optimize(source, options)Nén, chuyển đổi định dạng (AVIF, WebP, JPEG, PNG) và thay đổi kích thước tệp ảnh hoặc URL
getQuota()Lấy thông số byte đã xử lý theo thời gian thực, hạn ngạch tháng và băng thông CDN đã dùng
purgeCdn(urls, purgeType)Xóa ngay lập tức bộ nhớ đệm hình ảnh trên toàn bộ mạng lưới SmallPict Edge PoP toàn cầu
validateKey()Kiểm tra kết nối dịch vụ và xác minh tính hợp lệ của khóa xác thực
Phương thức phụ: getJobStatus(jobId)Truy vấn trạng thái và URL tải về của các tác vụ chuyển đổi ảnh bất đồng bộ ngầm

Cơ chế che giấu bí mật Zero-Leak (Zero-Leak Redaction)

Mọi SDK đều tích hợp sẵn bộ máy lọc biểu thức chính quy nghiêm ngặt. Khóa bí mật (sec_...) và khóa API (sp_sdk_..., sp_wp_..., sp_test_...) tuyệt đối không bao giờ bị in dưới dạng văn bản thuần trong stdout, trình gỡ lỗi hoặc stack trace của các ngoại lệ:

TEXT
Ví dụ nhật ký: "Request failed for key sp_sdk_9a8b...c4d3 and secret ***REDACTED***"

Ống dẫn yêu cầu kiên cường & Tính lũy đễ (Idempotency)

1. Thử lại với thuật toán Exponential Backoff và Jitter

Khi gặp sự cố mạng tạm thời, lỗi HTTP 429 (Quá nhiều yêu cầu) hoặc các lỗi máy chủ tạm thời 5xx, SDK sẽ tự động thử lại với độ trễ lũy thừa ngẫu nhiên (mặc định: tối đa 3 lần):

TEXT
delay = baseDelay * (2 ^ (attempt - 1)) + jitter

Nếu máy chủ phản hồi có kèm tiêu đề Retry-After, SDK sẽ tuân thủ chính xác khoảng thời gian yêu cầu đó.

2. Tự động đính kèm khóa Idempotency UUID v4

Mọi yêu cầu làm thay đổi trạng thái đều được SDK tự động gắn tiêu đề Idempotency-Key với giá trị UUID v4 độc nhất. Việc thử lại khi rớt mạng sẽ không bao giờ dẫn đến việc trừ trùng lặp hạn ngạch.

Các chế độ dự phòng sự cố (Fallback Modes)

Mọi SDK đều hỗ trợ tùy chọn fallbackMode:

  • Chế độ throw (Mặc định): Ném ra ngoại lệ định kiểu QuotaExceededError khi hết hạn ngạch để tầng ứng dụng xử lý.
  • Chế độ passthrough: Dành cho các dịch vụ cốt lõi coi trọng tính liên tục. Khi gặp lỗi HTTP 402 (Hết hạn ngạch), thay vì ném ra ngoại lệ làm ngừng dịch vụ, SDK sẽ trả về nguyên vẹn Buffer hình ảnh gốc chưa nén (đánh dấu savingsPercentage: 0.0), đảm bảo hệ thống không bao giờ bị gián đoạn.