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](https://img.shields.io/badge/Nodejs-22.x-339933?style=flat&logo=nodedotjs&logoColor=white)](https://nodejs.org/)
[![Nodejs 24.x](https://img.shields.io/badge/Nodejs-24.x-339933?style=flat&logo=nodedotjs&logoColor=white)](https://nodejs.org/)
[![Nodejs 26.x](https://img.shields.io/badge/Nodejs-26.x-339933?style=flat&logo=nodedotjs&logoColor=white)](https://nodejs.org/)
[![CI](https://github.com/dangkhoa2016/NodeJs-JSON-API-Server/actions/workflows/test.yml/badge.svg)](https://github.com/dangkhoa2016/NodeJs-JSON-API-Server/actions/workflows/test.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
> 🌐 Language / Ngôn ngữ: [English](README.md) | **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
```bash
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
```bash
docker build -t json-api-server .
```
### Chạy
```bash
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
```bash
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:
```bash
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`):
```bash
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
```bash
# 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` |
```bash
# 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`) |
```bash
# 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.
```bash
# 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
```
```json
{
"error": "Too Many Requests",
"message": "Rate limit exceeded. Max 100 requests per 60s window.",
"retryAfter": 300
}
```
---
## Ví dụ
```bash
# 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](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](https://jsonplaceholder.typicode.com) 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ợ
```bash
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](https://jsonplaceholder.typicode.com), 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.
```bash
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](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:
- **GitHub:** [JSON-API-Server-With-Dashboard-UI](https://github.com/dangkhoa2016/JSON-API-Server-With-Dashboard-UI)
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](LICENSE) — Bản quyền (c) 2026 Dang Khoa &lt;i.am@dangkhoa.dev&gt;
## Ghi công
Dự án này có sử dụng tài nguyên đồ họa từ Flaticon:
* [Sustainability stickers](https://www.flaticon.com/free-stickers/sustainability) được sáng tạo bởi [Manuel Viveros - Flaticon](https://www.flaticon.com/authors/manuel-viveros?type=sticker)