Code Structure
TÀI LIỆU KỸ THUẬT: CODE STRUCTURE - PROXY SERVICE TOOL
I. CÂY THƯ MỤC MÃ NGUỒN (DIRECTORY LAYOUT)
tool/
├── src/
│ ├── index.ts # Entry Point: Gắn kết Database, khởi động HTTP Server và Cron.
│ │
│ ├── api/ # Tầng Giao tiếp HTTP (Phân tách theo Domain).
│ │ ├── index.ts # Ghép nối toàn bộ Route dưới tiền tố /api và /webhook.
│ │ ├── auth/ # Module: Đăng nhập & Đăng ký.
│ │ ├── user/ # Module: Quản trị thông tin Người dùng.
│ │ ├── proxy/ # Module: Cốt lõi thao tác Proxy.
│ │ │ ├── proxy.controller.ts # Tuyến đường HTTP CRUD.
│ │ │ ├── proxy.service.ts # Trái tim logic: getOneFree, ReturnProxy (Sử dụng Mutex).
│ │ │ ├── proxy.cron.ts # Tiến trình xoay vòng IP (Rotation).
│ │ │ ├── proxy.model.ts # Typegoose Schema.
│ │ │ └── proxy.dto.ts # Khai báo cấu trúc kiểm duyệt dữ liệu.
│ │ │
│ │ ├── proxy_package/ # Module: Quản lý Gói dịch vụ Proxy.
│ │ ├── proxy_provider/ # Module: Quản lý Đối tác cung cấp Proxy.
│ │ ├── get-proxy/ # Module: API Cấp phát cho Consumer (IP Whitelisted).
│ │ ├── webhook/ # Module: API Thu hồi từ Consumer (IP Whitelisted).
│ │ └── test/ # Module: Endpoint phục vụ kiểm thử.
│ │
│ ├── services/ # Tầng Xử lý Hạ tầng chung.
│ │ ├── check-proxy/ # Tiện ích: Xác thực IP Public (checkIP) và Vị trí (checkRegion).
│ │ └── webhook/ # Tiện ích: Gọi Callback báo cáo kết quả.
│ │
│ ├── config/ # Tầng Thiết lập Môi trường tĩnh.
│ │ └── database/
│ │ └── mongodb.config.ts # Khởi tạo kết nối Mongoose.
│ │
│ └── utils/ # Tầng Công cụ Hỗ trợ (Shared Utilities).
│ ├── env.ts # Phân tích cú pháp (Parser) cho tệp .env.
│ ├── createElysia.ts # Factory tạo Elysia instance theo từng cấp độ Auth.
│ ├── logger.ts # Hệ thống ghi log có cấu trúc.
│ ├── error.middleware.ts # Khối xử lý lỗi tập trung.
│ ├── file/ # Xử lý tệp tin cục bộ.
│ └── number/ # Tính toán toán học phụ trợ.
│
├── .docker/ # Cấu hình chứa tệp Dockerfile.
├── storage/ # Lưu trữ log sinh ra trong quá trình Runtime.
├── package.json # Quản lý thư viện phụ thuộc.
├── tsconfig.json # Thiết lập TypeScript & Aliases (@api, @utils).
└── docker-compose.yml # Cấu hình Stack MongoDB + Redis.II. CÁC MẪU THIẾT KẾ QUAN TRỌNG (KEY DESIGN PATTERNS)
| Pattern | Vị trí ứng dụng | Mục đích kỹ thuật |
|---|---|---|
| Mutex Lock | proxy.service.ts | Khóa bất đồng bộ (async-mutex) trên các hàm getOneFree() và ReturnProxy() để đảm bảo tính nhất quán dữ liệu khi nhiều Consumer cùng xin Proxy tại một thời điểm. |
| Factory Functions | utils/createElysia.ts | Đóng gói logic khởi tạo Elysia để tránh lặp code. Cung cấp 3 mức độ: Không bảo mật, JWT Bearer, và API Key. |
| Decorator Schema | *.model.ts | Áp dụng Typegoose Decorators để khai báo cấu trúc MongoDB, tự động nội suy thành TypeScript Interface mà không cần khai báo 2 lần. |
| Service Singleton | Dưới cùng *.service.ts | Xuất trực tiếp Instance (Ví dụ: export const proxyServices = new ProxyServices()) để chia sẻ bộ nhớ trên toàn tiến trình. |
| Co-located Cron | proxy.controller.ts | Lồng ghép khởi chạy Cron ngay tại Controller quản lý nghiệp vụ đó, giúp đóng gói hoàn toàn vòng đời của một miền Logic (Domain-Driven). |
Ngày cập nhật 2026-03-30 03:11:30