Kiến trúc hoạt động hai lớp và cơ chế bảo vệ khoá kết nối
Mở rộngBản Mở rộngCập nhật
Mục lục
Mỗi lời gọi hàm trong vnstock thế hệ 6 được thực thi qua ba bước xử lý ngay trên máy của bạn. Mọi yêu cầu truy xuất dữ liệu đều xuất phát từ máy bạn và đi thẳng tới cổng Open API của nguồn đã chọn (hoặc đi qua máy chủ proxy do chính bạn cấu hình).
- Bước 1 — Kết nối và lấy phản hồi gốc (
vnstock-oapi): đọc khoá Open API của bạn từ Keyring hệ điều hành, tệp.envhoặc biến môi trường; quản lý phiên đăng nhập; gửi yêu cầu tới cổng Open API của nguồn và tự động lật trang khi kết quả kéo dài qua nhiều trang. - Bước 2 — Đóng gói thành phong bì chuẩn (
Envelope): mỗi phản hồi từ nguồn được bọc vào một cấu trúc phong bì thống nhất chứa dữ liệu gốc kèm tên nguồn, tên thao tác, tham số đã truyền và thời điểm lấy. Phong bì này hoàn toàn không chứa khoá hay token xác thực. - Bước 3 — Chuẩn hoá thành bảng dữ liệu (
vnstock): phần lõi củavnstockđọc phong bì và ánh xạ sang lược đồ cột chuẩn của hàm: đồng nhất tên cột, quy đổi đơn vị giá, chuyển mã phân loại riêng của nguồn về bộ từ vựng chung, gán múi giờ chuẩn, kiểm tra dải giá hợp lý và loại bỏ các dòng trùng lặp. Bước chuẩn hoá này xử lý thuần tuý trên bộ nhớ máy, không thực hiện bất kỳ kết nối mạng nào.
Khoá kết nối của bạn được bảo vệ như thế nào
- Khoá Open API của nguồn: chỉ được đọc cục bộ trên máy của bạn bởi
vnstock-oapivà chỉ gắn vào yêu cầu gửi tới đúng nguồn dữ liệu tương ứng. - Tách biệt với tài khoản Vnstock: thông tin đăng nhập tài khoản Vnstock tại
vnstocks.comđược quản lý ở một luồng riêng, không bao giờ dùng thay cho khoá nguồn hay gửi sang nguồn dữ liệu bên thứ ba. - An toàn khi lưu trữ ngoại tuyến: khi bạn xuất phong bì dữ liệu ra tệp để lưu trữ hoặc tái lập kết quả, tệp phong bì không bao giờ lưu kèm khoá bí mật. Thậm chí, nếu phát hiện một phong bì có dấu hiệu vô tình chứa chuỗi khoá hoặc token, phần lõi của
vnstocksẽ từ chối đọc ngay lập tức và báo lỗiVNSTOCK_ENVELOPE_SECRET.
Lợi ích của việc tách riêng lớp kết nối (vnstock-oapi) và lớp chuẩn hoá (vnstock)
- Dễ dàng kiểm chứng tính minh bạch:
vnstock-oapiđược công bố mã nguồn để bạn có thể trực tiếp kiểm tra cách phần mềm đọc khoá và giao tiếp mạng; trong khi khi một nguồn thay đổi chi tiết kỹ thuật kết nối, bạn chỉ cần cập nhật góivnstock-oapimà không làm xáo trộn cấu trúc bảng dữ liệu đầu ra. - Hỗ trợ lưu trữ và chuẩn hoá ngoại tuyến (Offline): bạn có thể thu thập phản hồi bằng
vnstock-oapi(hoặc bằng đoạn mã riêng của bạn), lưu thành tệp phong bì.jsonl, rồi dùng lớpConnectorcủavnstockđể chuẩn hoá lại bất kỳ lúc nào mà không cần gọi lại mạng (Lưu trữ và chuẩn hoá ngoại tuyến bằng Connector). - Tái lập kết quả nghiên cứu chính xác: vì bước chuẩn hoá tách rời khỏi bước gọi mạng, cùng một tệp phong bì đầu vào kết hợp với cùng một phiên bản
vnstocksẽ luôn cho ra bảng kết quả giống hệt nhau để bạn đối chiếu.
Cơ chế đồng nhất một cấu trúc bảng từ nhiều nguồn khác nhau
Mỗi hàm trong vnstock được định nghĩa một lược đồ cột chuẩn cố định. Đối với từng nguồn dữ liệu, thư viện khai báo rõ trường nào của nguồn sẽ điền vào cột chuẩn nào và quy đổi đơn vị ra sao. Nhờ kiến trúc này:
- Việc bạn đổi giá trị
source=sang nguồn khác không làm thay đổi tên cột hay kiểu dữ liệu khi dùng chế độ mặc địnhcolumns="standard"; - Những trường thông tin đặc thù chỉ một nguồn mới có vẫn lấy thêm được dễ dàng khi bật
columns="all"; - Xem chi tiết các tuỳ chọn bộ cột và hồ sơ đầu ra tại trang Chuẩn hoá và bộ cột dữ liệu.
