Spaces:
Sleeping
Download README.vi.md from dangkhoa2016/Nodejs-JSON-API-Server: direct link, hf CLI and curl.
- Browser
- Download file 18.2 kB
-
https://huggingface.co/spaces/dangkhoa2016/Nodejs-JSON-API-Server/resolve/42e30c2fc13d198cc76d79446c2a4308bbca4162/README.vi.md
- Command line
-
hf download hf://spaces/dangkhoa2016/Nodejs-JSON-API-Server@42e30c2fc13d198cc76d79446c2a4308bbca4162/README.vi.md
-
curl -L -o README.vi.md https://huggingface.co/spaces/dangkhoa2016/Nodejs-JSON-API-Server/resolve/42e30c2fc13d198cc76d79446c2a4308bbca4162/README.vi.md
json-api-server
🌐 Language / Ngôn ngữ: English | Tiếng Việt
Một REST API tương thích JSONPlaceholder, được xây dựng chủ yếu bằng Node.js built-ins — dependency runtime duy nhất là argon2 dùng để băm mật khẩu admin. Dùng node:sqlite để lưu trữ và một Redis client tự xây dựng trên giao thức RESP qua TCP sockets.
Công nghệ sử dụng
- Node.js >= 22 — runtime với
node:sqlite,node:http,node:nettích hợp sẵn - node:sqlite — cơ sở dữ liệu SQLite (tích hợp sẵn)
- node:http — HTTP server (tích hợp sẵn, không dùng Express/Fastify)
- node:net — TCP sockets cho Redis client RESP tự xây dựng (tích hợp sẵn)
- argon2 — băm mật khẩu an toàn cho xác thực admin (dependency runtime duy nhất)
- RESP protocol — Redis client tự xây dựng, triển khai Redis Serialization Protocol qua TCP
- dotenv — tải file môi trường (chỉ là dev dependency, bỏ qua trong production)
- vitest — trình chạy kiểm thử với vùng phủ V8 gốc (dev dependency)
Yêu cầu
- Node.js >= 22 (dùng
node:sqlitetích hợp sẵn) - Redis (không bắt buộc — giới hạn tốc độ fallback về in-memory nếu không có)
Bắt đầu nhanh
git clone <repo-url>
cd json-api-server
npm run db:setup # tạo bảng + dữ liệu mẫu (cần chạy trước lần đầu)
npm start # khởi động server
# hoặc với file watching cho phát triển:
npm run dev
Docker
Build
docker build -t json-api-server .
Chạy
docker run -d -p 3000:3000 -v ./storage:/app/storage --name json-api-server json-api-server
Entrypoint tự động chạy npm run db:setup (migrate + seed) khi container khởi động.
Biến môi trường
docker run -d -p 3000:3000 \
-e PORT=3000 \
-e ADMIN_KEY=my-secret-key \
-e REDIS_HOST=redis \
-v ./storage:/app/storage \
--name json-api-server json-api-server
Ghi chú
- Container chạy với user
app(không phải root). - File database được lưu trong
/app/storage(khai báo làVOLUME). NODE_ENV=productionđược đặt mặc định — dotenv bị bỏ qua, do đó mọi cấu hình phải được truyền qua biến môi trường (xem bên dưới).- File
.envvà.env.*bị loại trừ bởi.dockerignorevà không được copy vào image. - Entrypoint chạy
npm run db:setupkhi container khởi động.
Cấu hình môi trường
Container chạy với NODE_ENV=production, khi đó src/config/load-env.js bỏ qua hoàn toàn dotenv. Kết hợp với .dockerignore loại trừ mọi file .env*, bạn bắt buộc phải truyền cấu hình qua biến môi trường Docker.
Khuyến nghị: truyền biến trực tiếp:
docker run -d -p 3000:3000 \
-e PORT=3000 \
-e ADMIN_KEY=my-secret-key \
-e REDIS_HOST=redis \
-e SEED_API_BASE_URL=https://jsonplaceholder.typicode.com \
-v ./storage:/app/storage \
--name json-api-server json-api-server
Cách khác — mount file env (chỉ hoạt động với NODE_ENV=production-local):
docker run -d -p 3000:3000 \
-e NODE_ENV=production-local \
-v ./.env.prod:/app/.env.prod \
-v ./storage:/app/storage \
--name json-api-server json-api-server
Lưu ý: Node 22 có thể hiển thị cảnh báo rằng
node:sqliteđang ở giai đoạn thử nghiệm. Điều này vô hại.
Cấu hình
File môi trường được tải bởi src/config/load-env.js (tự động chạy qua src/config/index.js). Tất cả file hiện có trong chuỗi đều được tải với override: false — giá trị process.env và file trước có quyền cao hơn file sau. Biến môi trường hệ thống luôn có quyền cao nhất (ví dụ: PORT=5000 npm start).
NODE_ENV mặc định là development nếu không được đặt. Trong môi trường production, dotenv hoàn toàn bị bỏ qua — hãy đặt biến môi trường thông qua môi trường triển khai của bạn (systemd, Docker, Kubernetes, v.v.).
| NODE_ENV | dotenv | Chuỗi fallback (thử theo thứ tự) |
|---|---|---|
development |
✅ | .env ← .env.dev ← .env.development |
production-local |
✅ | .env.prod ← .env.production |
test |
✅ | .env.test |
production |
❌ bỏ qua | (dùng biến môi trường hệ thống) |
Biến
| Biến | Mặc định | Mô tả |
|---|---|---|
PORT |
3000 |
Cổng server |
DB_PATH |
./storage/data.db |
Đường dẫn file SQLite |
REDIS_URL |
(không) | URL kết nối Redis (ưu tiên cao hơn). Định dạng: redis://user:password@host:port/db |
REDIS_HOST |
127.0.0.1 |
Redis host |
REDIS_PORT |
6379 |
Redis port |
REDIS_DB |
0 |
Chỉ mục database Redis |
REDIS_PASSWORD |
(không) | Mật khẩu Redis (cho AUTH) |
RATE_LIMIT_ENABLED |
true |
Bật/tắt giới hạn tốc độ |
RATE_LIMIT_MAX |
100 |
Số request tối đa trong một khoảng thời gian |
DEBUG_SQL |
false |
Ghi log tất cả truy vấn SQL ra stderr (true/false) |
RATE_LIMIT_WINDOW_MS |
60000 |
Khoảng thời gian tính bằng mili giây (mặc định 1 phút) |
SEED_API_BASE_URL |
https://jsonplaceholder.typicode.com |
URL gốc cho API dữ liệu mẫu |
MAX_BODY_SIZE |
1048576 |
Kích thước body request tối đa tính bằng byte (tối thiểu 1) |
DEFAULT_PAGE_SIZE |
10 |
Số kết quả mặc định mỗi trang cho phân trang _page/_limit |
ADMIN_KEY |
(không) | Khóa chính để xác thực request admin API (Bearer token) |
| Cập nhật runtime | — | Patching RATE_LIMIT_ENABLED, RATE_LIMIT_MAX, RATE_LIMIT_WINDOW_MS, REDIS_URL, REDIS_HOST, REDIS_PORT, REDIS_DB, hoặc REDIS_PASSWORD qua admin API áp dụng thay đổi ngay lập tức — không cần khởi động lại server |
API Endpoints
Tài nguyên
| Method | Path | Mô tả |
|---|---|---|
GET |
/api/users |
Danh sách tất cả user |
GET |
/api/users/:id |
Lấy user theo ID |
GET |
/api/users/:id/posts |
Bài viết của user |
GET |
/api/users/:id/albums |
Album của user |
GET |
/api/users/:id/todos |
Việc cần làm của user |
GET |
/api/posts |
Danh sách tất cả bài viết |
GET |
/api/posts/:id |
Lấy bài viết theo ID |
GET |
/api/posts/:id/comments |
Bình luận của bài viết |
GET |
/api/comments |
Danh sách tất cả bình luận |
GET |
/api/albums |
Danh sách tất cả album |
GET |
/api/albums/:id/photos |
Ảnh trong album |
GET |
/api/photos |
Danh sách tất cả ảnh |
GET |
/api/todos |
Danh sách tất cả việc cần làm |
POST |
/api/:table |
Tạo tài nguyên mới |
PUT |
/api/:table/:id |
Thay thế toàn bộ tài nguyên |
PATCH |
/api/:table/:id |
Cập nhật một phần |
DELETE |
/api/:table/:id |
Xóa tài nguyên |
Xóa tầng (cascade): Xóa
usersẽ xóaposts,albums, vàtodoscủa họ. Xóapostsẽ xóacommentscủa nó. Xóaalbumsẽ xóaphotoscủa nó.
Lọc theo query string và phân trang
# Lọc bài viết theo userId
GET /api/posts?userId=1
# Lọc việc cần làm theo userId và trạng thái hoàn thành
GET /api/todos?userId=1&completed=false
# Lọc bình luận theo postId
GET /api/comments?postId=1
Các cột có thể lọc khác nhau theo bảng (ví dụ: title, email, username). Trường completed chấp nhận chuỗi true/false.
Phân trang
| Tham số | Mô tả | Ví dụ |
|---|---|---|
_page |
Số trang (bắt đầu từ 1), dùng với _limit |
?_page=1&_limit=10 |
_limit |
Số mục mỗi trang (mặc định: DEFAULT_PAGE_SIZE) |
?_page=2&_limit=5 |
_start |
Chỉ số bắt đầu để cắt | ?_start=10&_end=20 |
_end |
Chỉ số kết thúc (không bao gồm) để cắt | ?_start=0&_end=5 |
Tìm kiếm
Tìm kiếm trên các cột văn bản bằng tham số q. Các cột có thể tìm kiếm khác nhau theo bảng:
| Bảng | Cột có thể tìm kiếm |
|---|---|
users |
name, username, email |
posts |
title, body |
comments |
name, email, body |
albums |
title |
photos |
title |
todos |
title |
# Tìm bài viết theo tiêu đề hoặc nội dung
GET /api/posts?q=first
# Kết hợp tìm kiếm với bộ lọc
GET /api/posts?q=Post&userId=1
# Tìm việc cần làm
GET /api/todos?q=groceries
Sắp xếp
| Tham số | Giá trị | Mô tả |
|---|---|---|
_sort |
tên cột | Cột để sắp xếp |
_order |
asc / desc |
Hướng sắp xếp (mặc định: asc) |
# Sắp xếp bài viết theo tiêu đề tăng dần
GET /api/posts?_sort=title&_order=asc
# Sắp xếp bài viết theo tiêu đề giảm dần
GET /api/posts?_sort=title&_order=desc
# Kết hợp sắp xếp với phân trang
GET /api/posts?_sort=id&_order=desc&_limit=2
Endpoint hệ thống
| Path | Mô tả |
|---|---|
GET / |
Thông tin API với các endpoint có sẵn |
GET /api |
Thông tin API (giống như trên) |
GET /health |
Trạng thái server (Redis, bảng, cấu hình giới hạn tốc độ) |
GET /api/health |
Giống như trên |
GET /api/admin/settings |
Danh sách tất cả cài đặt (yêu cầu xác thực) |
PATCH /api/admin/settings/:key |
Cập nhật giá trị cài đặt — thay đổi rate-limit & Redis có hiệu lực ngay lập tức (yêu cầu xác thực) |
POST /api/admin/reset-database |
Xóa bảng dữ liệu và seed lại từ JSONPlaceholder (yêu cầu xác thực) |
Admin API
Các endpoint admin được bảo vệ bằng xác thực Bearer token sử dụng biến môi trường ADMIN_KEY. Giá trị cài đặt được lưu trong bảng settings của database.
# Danh sách tất cả cài đặt
curl http://localhost:3000/api/admin/settings \
-H "Authorization: Bearer my-secret-key"
# Cập nhật cài đặt
curl -X PATCH http://localhost:3000/api/admin/settings/NODE_ENV \
-H "Authorization: Bearer my-secret-key" \
-H "Content-Type: application/json" \
-d '{"value": "production"}'
# Đặt lại database (xóa toàn bộ dữ liệu và tải lại từ JSONPlaceholder)
curl -X POST http://localhost:3000/api/admin/reset-database \
-H "Authorization: Bearer my-secret-key" \
-H "Content-Type: application/json" \
-d '{"confirm": true}'
ADMIN_KEY được băm bằng argon2 trước khi lưu trữ. Khi cập nhật mật khẩu qua PATCH /api/admin/settings/ADMIN_KEY, giá trị mới tự động được băm. Mật khẩu không bao giờ được lưu dưới dạng văn bản thuần túy.
Cập nhật cấu hình runtime: Khi patching cài đặt rate-limit (RATE_LIMIT_ENABLED, RATE_LIMIT_MAX, RATE_LIMIT_WINDOW_MS) hoặc cài đặt kết nối Redis (REDIS_HOST, REDIS_PORT, REDIS_DB, REDIS_PASSWORD, REDIS_URL), server áp dụng thay đổi ngay lập tức qua lớp RuntimeConfig — không cần khởi động lại. Thay đổi rate-limit gọi rateLimiter.updateConfig() để hot-swap hành vi middleware, trong khi cài đặt Redis kích hoạt kết nối lại an toàn qua Redis.reconnect().
Kết quả xác minh Argon2 được lưu cache trong bộ nhớ 5 giây cho mỗi token, tránh băm lặp lại trên các request admin liên tiếp. Khi có lỗi, kết quả cũng được lưu cache là không hợp lệ — ngăn chặn rò rỉ thông tin qua timing hoặc thông báo lỗi.
Response Headers
Mọi response đều bao gồm header CORS và giới hạn tốc độ:
Access-Control-Allow-Origin: *
X-Powered-By: json-api-server/1.0
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 58 ← giây cho đến khi cửa sổ reset
X-RateLimit-Store: redis ← "redis" hoặc "memory"
Khi vượt quá giới hạn tốc độ, response 429 Too Many Requests được trả về:
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 0
X-RateLimit-Store: redis
Retry-After: 300
{
"error": "Too Many Requests",
"message": "Rate limit exceeded. Max 100 requests per 60s window.",
"retryAfter": 300
}
Ví dụ
# Danh sách user
curl http://localhost:3000/api/users
# Tạo bài viết mới
curl -X POST http://localhost:3000/api/posts \
-H "Content-Type: application/json" \
-d '{"userId": 1, "title": "Hello", "body": "World"}'
# Cập nhật một phần
curl -X PATCH http://localhost:3000/api/posts/1 \
-H "Content-Type: application/json" \
-d '{"title": "Updated title"}'
# Xóa
curl -X DELETE http://localhost:3000/api/posts/1
# Kiểm tra sức khỏe
curl http://localhost:3000/health
Xem docs/TECHNICAL.vi.md để biết kiến trúc và ghi chú triển khai chi tiết.
Database
- 7 bảng:
users,posts,comments,albums,photos,todos,settings - Chế độ WAL cho hiệu suất đọc đồng thời tốt hơn
- Ràng buộc khóa ngoại được thực thi qua
PRAGMA foreign_keys=ON - Dữ liệu mẫu được lấy từ JSONPlaceholder lần chạy đầu:
- 10 users (với
addressvàcompanylưu dưới dạng JSON, phân tích khi đọc) - 100 bài viết
- 500 bình luận
- 100 album
- 5000 ảnh
- 200 việc cần làm
- 14 cài đặt (biến môi trường:
NODE_ENV,PORT,DB_PATH,DEBUG_SQL,REDIS_HOST,REDIS_PORT,REDIS_DB,REDIS_PASSWORD,REDIS_URL,RATE_LIMIT_ENABLED,RATE_LIMIT_MAX,RATE_LIMIT_WINDOW_MS,DEFAULT_PAGE_SIZE,ADMIN_KEY)
- 10 users (với
Script hỗ trợ
sqlite3 storage/data.db < manual/inspect-queries.sql
Script này chạy các truy vấn toàn diện để kiểm tra số lượng dòng, metadata cột, quan hệ, kiểm tra toàn vẹn và thống kê.
Script Database
| Script | Lệnh | Mô tả |
|---|---|---|
db:migrate |
npm run db:migrate |
Tạo 7 bảng (dotenv được tải bởi config.js) |
db:seed |
npm run db:seed |
Lấy dữ liệu mẫu từ JSONPlaceholder, tự động chạy migrate + seed-settings |
db:seed-settings |
npm run db:seed-settings |
Seed biến môi trường vào bảng settings (dotenv được tải bởi config.js) |
db:setup |
npm run db:setup |
Chạy db:seed + db:seed-settings (migrate + JSONPlaceholder + env settings) |
test |
npm test |
Chạy kiểm thử tích hợp vitest |
test:coverage |
npm run test:coverage |
Chạy kiểm thử với báo cáo vùng phủ V8 |
Kiểm thử
Sử dụng vitest với vùng phủ V8 gốc. 250 bài kiểm thử trên 14 file bao phủ toàn bộ stack — từ kiểm thử tích hợp (HTTP server thật + SQLite) đến kiểm thử đơn vị cho mọi module.
npm test # Chạy tất cả kiểm thử một lần
npm run test:watch # Chế độ watch
npm run test:coverage # Với báo cáo vùng phủ (100% trên mọi chỉ số)
Xem tests/README.md để biết tài liệu đầy đủ.
Giấy phép
MIT — Bản quyền (c) 2026 Dang Khoa <i.am@dangkhoa.dev>
Ghi công
Dự án này có sử dụng tài nguyên đồ họa từ Flaticon:
- Sustainability stickers được sáng tạo bởi Manuel Viveros - Flaticon