Nodejs-JSON-API-Server / README.vi.md
dangkhoa2016's picture
docs: add project highlights and similar project note
b8e6260
|
Raw History Blame Contribute Delete
21.5 kB

Nodejs JSON API Server

Nodejs 22.x Nodejs 24.x Nodejs 26.x CI License: MIT

🌐 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.

Điểm nổi bật

  • Zero-framework, dependency tối thiểu — Chỉ 1 dependency production (argon2). HTTP, SQLite, networking — tất cả đều dùng built-ins của Node.js. Không Express, không ORM, không Redis driver.
  • Redis client tự xây dựng — Một Redis client hoàn chỉnh triển khai giao thức RESP qua TCP sockets. Hỗ trợ AUTH, SELECT, EVAL (Lua script), chuỗi kết nối URL, và tự động kết nối lại — tất cả trong ~200 dòng.
  • 100% kiểm thử — 250 bài kiểm thử trên 14 file đạt 100% ở statements, branches, functions và lines. Kiểm thử tích hợp chạy với HTTP server thật + SQLite; kiểm thử đơn vị dùng dependency injection và CJS cache mocking.
  • Giới hạn tốc độ đa tầng — Ba tầng fallback: Redis (Lua nguyên tử) → in-memory (LRU, 10k mục) → cho phép tất cả. Tích hợp circuit breaker (3 lỗi → mở 30s), trích xuất IP proxy dựa trên CIDR, và thời gian chặn tăng dần (5 ph → 20 ph → 1 giờ).
  • Docker tối ưu cho production — Multi-stage build, user không phải root, tự động thiết lập DB khi khởi động, file .env bị loại trừ. Dotenv bị bỏ qua trong production — mọi cấu hình đều qua biến môi trường.
  • Cấu hình runtime — Cập nhật cài đặt rate-limit và Redis qua admin API mà không cần khởi động lại. Thay đổi có hiệu lực ngay lập tức qua ghi đè trong bộ nhớ.
  • Bảo mật Argon2 — Mật khẩu admin được băm bằng argon2, kết quả được lưu cache với TTL 5 giây và LRU 1k mục. Ngăn chặn SQL injection qua danh sách trắng cột và thoát LIKE. Giới hạn kích thước body ở 1 MB.
  • Dev server với file watching tích hợp — npm run dev dùng cờ --watch gốc của Node. Không cần Nodemon, chokidar, hay bất kỳ dependency thêm nào.
  • Tài liệu song ngữ — Đầy đủ tài liệu bằng tiếng Anh và tiếng Việt cho README, hướng dẫn kiểm thử và kiến trúc kỹ thuật.

Công nghệ sử dụng

  • Node.js >= 22 — runtime với node:sqlite, node:http, node:net tí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:sqlite tí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 .env và .env.* bị loại trừ bởi .dockerignore và không được copy vào image.
  • Entrypoint chạy npm run db:setup khi 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 user sẽ xóa posts, albums, và todos của họ. Xóa post sẽ xóa comments của nó. Xóa album sẽ xóa photos củ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 address và company lư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)

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 đủ.

Dự án tương tự

Nếu bạn thích server này nhưng muốn có giao diện dashboard được xây dựng bằng Tailwind CSS, hãy xem:

Dự án cung cấp cùng API tương thích JSONPlaceholder nhưng kèm giao diện web trực quan — cũng rất hay!

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: